com.ibm.security.pkcs8
Class PrivateKeyInfo

java.lang.Object
  |
  +--com.ibm.security.pkcsutil.PKCSDerObject
        |
        +--com.ibm.security.pkcs8.PrivateKeyInfo

public class PrivateKeyInfo
extends PKCSDerObject
implements PrivateKey

Implements the PrivateKeyInfo data type as defined in PKCS #8.

PrivateKeyInfo ::= SEQUENCE { version INTEGER, privateKeyAlgorithm AlgorithmIdentifier, privateKey OCTET STRING, attributes [0] IMPLICIT Attributes OPTIONAL }

This class may be subclassed by specific private key classes wishing to adhere to the PKCS #8 standard.

See Also:
Serialized Form

Field Summary
protected  AlgorithmId algid
          The algorithm information (name, parameters, etc).
protected  PKCSAttributes attributes
          The attributes associated with the key.
protected  byte[] key
          The key bytes, without the algorithm information
static BigInteger version
          The version for this key
 
Fields inherited from class com.ibm.security.pkcsutil.PKCSDerObject
provider
 
Fields inherited from interface java.security.PrivateKey
serialVersionUID
 
Fields inherited from interface java.security.Key
serialVersionUID
 
Constructor Summary
PrivateKeyInfo()
          Create an uninitialized PrivateKeyInfo object.
PrivateKeyInfo(AlgorithmId algid, byte[] key, PKCSAttributes attrs)
          Creates a PrivateKeyInfo object with the specified values.
PrivateKeyInfo(AlgorithmId algid, byte[] key, PKCSAttributes attrs, String provider)
          Creates a PrivateKeyInfo object with the specified values.
PrivateKeyInfo(byte[] der)
          Create a PKCS #8 PrivateKeyInfo object with a DER byte array.
PrivateKeyInfo(byte[] der, String provider)
          Create a PKCS #8 PrivateKeyInfo object with a DER byte array.
PrivateKeyInfo(String provider)
          Create an uninitialized PrivateKeyInfo object.
PrivateKeyInfo(String filename, boolean base64)
          Create a PrivateKeyInfo with the filename of the DER-encoded or BASE64-encoded object.
PrivateKeyInfo(String filename, boolean base64, String provider)
          Create a PrivateKeyInfo with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 PrivateKeyInfo addAttribute(PKCSAttribute attrib)
          Add a PKCS attribute into the set of attributes for this PrivateKeyInfo object.
 PrivateKeyInfo addAttributes(PKCSAttributes attribs)
          Add a PKCSAttributes set of attributes into the set of attributes for this PrivateKeyInfo object.
 Object clone()
          Creates a clone of this PrivateKeyInfo object.
protected  void decode(com.ibm.security.pkcs8.DerValue encoding)
          Initialize an PrivateKeyInfo object from an input stream.
 void encode(OutputStream os)
          Encodes this object to an OutputStream.
 boolean equals(Object other)
          Determines if this PrivateKeyInfo object is equivalent to the input object.
protected  void finalize()
          Ensures that the key bytes are nulled out when there are no more references to this object.
 String getAlgorithm()
          Returns the algorithm to be used with this key.
 AlgorithmId getAlgorithmId()
          Returns the algorithm identifier.
 PKCSAttribute getAttribute(ObjectIdentifier oid)
          Returns an attribute from the attribute set based on an ObjectIdentifier.
 PKCSAttributes getAttributes()
          Returns the PKCS attributes associated with this key.
 byte[] getEncoded()
          Returns the DER-encoded form of the key as a byte array.
 String getFormat()
          Returns the format for this key: "PKCS#8"
 byte[] getKeyBytes()
          Return a copy of the private key byte array.
 boolean hasAttribute(ObjectIdentifier oid)
          Determines if this PrivateKeyInfo has the attribute specified by the ObjectIdentifier.
 boolean hasAttributes()
          Determines if this PrivateKeyInfo has any attributes.
 int hashCode()
          Calculates a hash code value for this object.
static PrivateKey parseKey(com.ibm.security.pkcs8.DerValue in)
          Constructs a PKCS #8 subject private key from a DER value.
static PrivateKey parseKey(com.ibm.security.pkcs8.DerValue in, String provider)
          Constructs a PKCS #8 subject private key from a DER value.
protected  void parseKeyBits()
          Parses the key bits.
 String toString()
          Returns a string representation of this PrivateKeyInfo object.
 
Methods inherited from class com.ibm.security.pkcsutil.PKCSDerObject
decode, decode, encode, getObjectIdentifier, read, readBASE64, write, write, writeBASE64
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

version

public static final BigInteger version
The version for this key

algid

protected AlgorithmId algid
The algorithm information (name, parameters, etc).

key

protected byte[] key
The key bytes, without the algorithm information

attributes

protected PKCSAttributes attributes
The attributes associated with the key.
Constructor Detail

PrivateKeyInfo

public PrivateKeyInfo()
Create an uninitialized PrivateKeyInfo object. This uninitialized object can be initialized with the decode method.

PrivateKeyInfo

public PrivateKeyInfo(String provider)
Create an uninitialized PrivateKeyInfo object. This uninitialized object can be initialized with the decode method.

PrivateKeyInfo

public PrivateKeyInfo(byte[] der)
               throws IOException
Create a PKCS #8 PrivateKeyInfo object with a DER byte array.
Parameters:
der - a DER byte array of a PrivateKeyInfo object.
Throws:
IOException - on decoding errors.

PrivateKeyInfo

public PrivateKeyInfo(byte[] der,
                      String provider)
               throws IOException
Create a PKCS #8 PrivateKeyInfo object with a DER byte array.
Parameters:
der - a DER byte array of a PrivateKeyInfo object.
provider - the provider to be used.
Throws:
IOException - on decoding errors.

PrivateKeyInfo

public PrivateKeyInfo(AlgorithmId algid,
                      byte[] key,
                      PKCSAttributes attrs)
               throws IOException
Creates a PrivateKeyInfo object with the specified values. All PKCS #8 key data is stored and transmitted losslessly, but no knowledge about this particular algorithm is available.
Parameters:
algid - the private key algorithm and any associated parameters.
key - the encoded private key.
attrs - optional PKCSAttributes for this key. May be null.
Throws:
IOException - if the object cannot be DER-encoded.

PrivateKeyInfo

public PrivateKeyInfo(AlgorithmId algid,
                      byte[] key,
                      PKCSAttributes attrs,
                      String provider)
               throws IOException
Creates a PrivateKeyInfo object with the specified values. All PKCS #8 key data is stored and transmitted losslessly, but no knowledge about this particular algorithm is available.
Parameters:
algid - the private key algorithm and any associated parameters.
key - the encoded private key.
attrs - optional PKCSAttributes for this key. May be null.
provider - the provider to be used.
Throws:
IOException - if the object cannot be DER-encoded.

PrivateKeyInfo

public PrivateKeyInfo(String filename,
                      boolean base64)
               throws IOException
Create a PrivateKeyInfo with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
Throws:
IOException - on decoding errors.

PrivateKeyInfo

public PrivateKeyInfo(String filename,
                      boolean base64,
                      String provider)
               throws IOException
Create a PrivateKeyInfo with the filename of the DER-encoded or BASE64-encoded object.
Parameters:
filename - name of the DER-encoded or base64-encoded object
base64 - true if BASE64-encoded, false if DER-encoded
provider - the provider to be used
Throws:
IOException - on decoding errors.
Method Detail

encode

public void encode(OutputStream os)
            throws IOException
Encodes this object to an OutputStream.
Overrides:
encode in class PKCSDerObject
Parameters:
os - the OutputStream on which to write the DER encoding.
Throws:
IOException - on encoding errors.

parseKey

public static PrivateKey parseKey(com.ibm.security.pkcs8.DerValue in)
                           throws IOException
Constructs a PKCS #8 subject private key from a DER value. If the runtime environment is configured with a specific class for this kind of key, a subclass is returned. Otherwise, a generic PrivateKeyInfo object is returned.

This mechanism gurantees that keys (and algorithms) may be freely manipulated and transferred, without risk of losing information. Also, when a key (or algorithm) needs some special handling, that specific need can be accomodated.

Parameters:
in - the DER-encoded PrivateKeyInfo value.
Returns:
a PrivateKey instance built from the input private key info.
Throws:
IOException - on data format errors.

parseKey

public static PrivateKey parseKey(com.ibm.security.pkcs8.DerValue in,
                                  String provider)
                           throws IOException
Constructs a PKCS #8 subject private key from a DER value. If the runtime environment is configured with a specific class for this kind of key, a subclass is returned. Otherwise, a generic PrivateKeyInfo object is returned.

This mechanism gurantees that keys (and algorithms) may be freely manipulated and transferred, without risk of losing information. Also, when a key (or algorithm) needs some special handling, that specific need can be accomodated.

Parameters:
in - the DER-encoded PrivateKeyInfo value.
provider - the provider to be used.
Returns:
a PrivateKey instance built from the input private key info.
Throws:
IOException - on data format errors.

addAttributes

public PrivateKeyInfo addAttributes(PKCSAttributes attribs)
Add a PKCSAttributes set of attributes into the set of attributes for this PrivateKeyInfo object. Replace the attribute if it already exists. This method returns a new instance of PrivateKeyInfo and leaves the original object unchanged.
Parameters:
attribs - the PKCSAttributes to add.

addAttribute

public PrivateKeyInfo addAttribute(PKCSAttribute attrib)
Add a PKCS attribute into the set of attributes for this PrivateKeyInfo object. Replace the attribute if it already exists. This method returns a new instance of PrivateKeyInfo and leaves the original object unchanged.
Parameters:
attrib - the PKCS attribute to add.

getAlgorithm

public String getAlgorithm()
Returns the algorithm to be used with this key.

getAlgorithmId

public AlgorithmId getAlgorithmId()
Returns the algorithm identifier. The algorithm identifier is an immutable object.

getEncoded

public byte[] getEncoded()
Returns the DER-encoded form of the key as a byte array.

getFormat

public String getFormat()
Returns the format for this key: "PKCS#8"

getAttribute

public PKCSAttribute getAttribute(ObjectIdentifier oid)
Returns an attribute from the attribute set based on an ObjectIdentifier. The attribute returned is immutable.
Parameters:
oid - ObjectIdentifier to match
Returns:
attribute matching the oid, null otherwise.

getAttributes

public PKCSAttributes getAttributes()
Returns the PKCS attributes associated with this key. The PKCS attributes object returned is immutable.

hasAttribute

public boolean hasAttribute(ObjectIdentifier oid)
Determines if this PrivateKeyInfo has the attribute specified by the ObjectIdentifier.
Parameters:
oid - ObjectIdentifier to match
Returns:
true if the oid exists in the attributes, false otherwise.

hasAttributes

public boolean hasAttributes()
Determines if this PrivateKeyInfo has any attributes.
Returns:
true if at least one attribute exists in the object, false otherwise.

equals

public boolean equals(Object other)
Determines if this PrivateKeyInfo object is equivalent to the input object.
Overrides:
equals in class PKCSDerObject
Parameters:
other - the object to compare this one to.
Returns:
true, if the two objects are equivalent, false otherwise.

toString

public String toString()
Returns a string representation of this PrivateKeyInfo object.
Overrides:
toString in class PKCSDerObject
Returns:
a string representation of this object.

hashCode

public int hashCode()
Calculates a hash code value for this object. Objects which are equal will also have the same hashcode.
Overrides:
hashCode in class PKCSDerObject

clone

public Object clone()
Creates a clone of this PrivateKeyInfo object.
Overrides:
clone in class Object
Returns:
clone of this PrivateKeyInfo object.

decode

protected void decode(com.ibm.security.pkcs8.DerValue encoding)
               throws IOException
Initialize an PrivateKeyInfo object from an input stream. The data on that input stream must be encoded using DER, obeying the PKCS #8 format: a sequence consisting of a version, an algorithm ID and a bit string which holds the key. (That bit string is often used to encapsulate another DER encoded sequence.)

Subclasses should not normally redefine this method; they should instead provide a parseKeyBits method to parse any fields inside the key member.

Parameters:
encoding - a DER-encoded PrivateKeyInfo object.
Throws:
IOException - on parsing errors.

parseKeyBits

protected void parseKeyBits()
                     throws IOException
Parses the key bits. This may be redefined by subclasses to take advantage of structure within the key. For example, RSA public keys encapsulate two unsigned integers (modulus and exponent) as DER values within the key bits; Diffie-Hellman and DSS/DSA keys encapsulate a single unsigned integer.

This function is called when creating PKCS #8 SubjectPublicKeyInfo values using the PrivateKeyInfo member functions, such as parse and decode.

Throws:
IOException - if a parsing error occurs.

getKeyBytes

public byte[] getKeyBytes()
Return a copy of the private key byte array.

finalize

protected void finalize()
Ensures that the key bytes are nulled out when there are no more references to this object.
Overrides:
finalize in class Object