iaik.pkcs.pkcs8

Class PrivateKeyInfo

java.lang.Object

iaik.pkcs.pkcs8.PrivateKeyInfo

All Implemented Interfaces:

ASN1Type, java.io.Serializable, java.lang.Cloneable, java.security.Key, java.security.PrivateKey

Direct Known Subclasses:

DHPrivateKey, DSAPrivateKey, ElGamalPrivateKey, RawPrivateKey, RSAPrivateKey

public abstract class PrivateKeyInfo
extends java.lang.Object
implements ASN1Type, java.security.PrivateKey, java.lang.Cloneable

This class implements the PKCS#8 PrivateKeyInfo/OneAsymmetricKey type as as specified by RFC 5208 and RFC 5958 for protecting private key information.

A Private-key information according to PKCS#8 combines a private key (of a public-key algorithm) and some attributes containing additional key related informtation:

 PrivateKeyInfo ::= SEQUENCE {
   version Version,
   privateKeyAlgorithm PrivateKeyAlgorithmIdentifier,
   privateKey PrivateKey
   attributes [0] IMPLICIT Attributes OPTIONAL }
 

where:

 Version ::= INTEGER   -- Syntax Version Number
 PrivateKeyAlgorithmIdentifier ::= AlgorithmIdentifier  -- private key algorithm, e.g. rsaEncryption from PKCS#1
 PrivateKey ::= OCTET STRING   -- the value of the private key, e.g. a BER encoded RSAPrivateKey value
 Attributes ::= SET OF Attribute  -- additional information
 

RFC 5958 enhances the PrivateKeyInfo syntax by introducing the OneAsymmetricKey type that basically is the same as PKCS#8 the PKCS#8 PrivateKeyInfo but adds the publicKey field to the PrivateKeyInfo structure (see RFC 5958):

 OneAsymmetricKey ::= SEQUENCE {
     version                   Version,
     privateKeyAlgorithm       PrivateKeyAlgorithmIdentifier,
     privateKey                PrivateKey,
     attributes            [0] Attributes OPTIONAL,
     ...,
     [[2: publicKey        [1] PublicKey OPTIONAL ]],
     ...
    }
    
    PrivateKeyInfo ::= OneAsymmetricKey
 

Backwards compatibility is maintained by the version number field. IAIK-JCE adds support for the OneAsymmetricKey type by simply adding the publicKey field to this PrivateKeyInfo class. This allows to use the publicKey enhancement by all PrivateKey classes that are extended from PKCS#8 PrivateKeyInfo.

This class may be extended for every particular private key implementation wishing to support PKCS#8 PrivateKeyInfo/OneAsymmetricKey.

This class provides a variety of methods for creating, parsing, de- and encoding private key informations.

Version:

File Revision 33

See Also:

DHPrivateKey, DSAPrivateKey, RSAPrivateKey, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected AlgorithmID	private_key_algorithm Identifies the appertaining private-key algorithm.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PrivateKeyInfo() Default Constructor for derived classes.
	PrivateKeyInfo(ASN1Object obj) Creates a new PrivateKeyInfo from an ASN1Object.
	PrivateKeyInfo(byte[] arr) Creates a new PrivateKeyInfo from a byte array.
	PrivateKeyInfo(java.io.InputStream is) Creates a new PrivateKeyInfo from an InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	clone() Return a clone of this private key object.
protected void	createPrivateKeyInfo() Creates a PrivateKeyInfo ASN.1 data structure (PKCS#8).
void	decode(ASN1Object obj) Decodes the given ASN.1 PrivateKeyInfo object for parsing the internal structure.
protected abstract void	decode(byte[] privateKey) Abstract method to be implemented for decoding a DER encoded private key.
protected abstract byte[]	encode() Abstract method to be implemented for encoding this private key according to DER.
boolean	equals(java.lang.Object obj) Compares this private key to another private key.
abstract java.lang.String	getAlgorithm() Returns the name of the algorithm.
AlgorithmID	getAlgorithmID() Returns the key algorithm id.
Attribute[]	getAttributes() Gets any included attributes.
byte[]	getEncoded() Returns this PrivateKeyInfo as a DER encoded ASN.1 data structure.
java.lang.String	getFormat() Returns the name of the encoding format..
static java.security.PrivateKey	getPrivateKey(ASN1Object privateKeyInfo) Creates a PrivateKey from an ASN1Object.
static java.security.PrivateKey	getPrivateKey(ASN1Object privateKeyInfo, java.security.Provider provider) Creates a PrivateKey for the given provider from an ASN1Object.
static java.security.PrivateKey	getPrivateKey(ASN1Object privateKeyInfo, java.lang.String providerName) Creates a PrivateKey for the given provider from an ASN1Object.
static java.security.PrivateKey	getPrivateKey(byte[] privateKeyInfo) Creates a PrivateKey from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.
static java.security.PrivateKey	getPrivateKey(byte[] privateKeyInfo, java.security.Provider provider) Creates a PrivateKey for the given provider from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.
static java.security.PrivateKey	getPrivateKey(byte[] privateKeyInfo, java.lang.String providerName) Creates a PrivateKey for the given provider from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.
java.security.PublicKey	getPubKey() Gets the public key (if included).
int	hashCode() Returns a hash code for this object.
void	setAttributes(Attribute[] attributes) Sets any attributes to be included.
void	setPubKey(java.security.PublicKey publicKey) Sets the public key (if to be included).
ASN1Object	toASN1Object() Returns this PrivateKeyInfo as ASN1Object.
java.lang.String	toString() Returns a string that represents the contents of this private key.
void	writeTo(java.io.OutputStream os) Writes this private key to an output stream.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

private_key_algorithm

protected AlgorithmID private_key_algorithm

Identifies the appertaining private-key algorithm.

Constructor Detail

PrivateKeyInfo

protected PrivateKeyInfo()

Default Constructor for derived classes.

PrivateKeyInfo

public PrivateKeyInfo(ASN1Object obj)
               throws java.security.InvalidKeyException

Creates a new PrivateKeyInfo from an ASN1Object.

This constructor may be used for parsing an already existing PrivateKeyInfo object, supplied as ASN1Object that may have been created by calling toASN1Object.

Parameters:

obj - the PrivateKeyInfo as ASN1Object

Throws:

java.security.InvalidKeyException - if the data can not be parsed

PrivateKeyInfo

public PrivateKeyInfo(java.io.InputStream is)
               throws java.security.InvalidKeyException,
                      java.io.IOException

Creates a new PrivateKeyInfo from an InputStream.

Parameters:

is - the input stream from where the encoded PrivateKeyInfo shall be read

Throws:

java.security.InvalidKeyException - if the data can not be parsed

java.io.IOException - if an I/O error occurs

PrivateKeyInfo

public PrivateKeyInfo(byte[] arr)
               throws java.security.InvalidKeyException

Creates a new PrivateKeyInfo from a byte array.

This constructor may be used for parsing an already existing PrivateKeyInfo object, supplied as DER encoded ASN.1 structure, which may have been created by calling the getEncoded method of this class.

Parameters:

arr - the array containing the encoded PrivateKeyInfo

Throws:

java.security.InvalidKeyException - if the data can not be parsed

Method Detail

decode

protected abstract void decode(byte[] privateKey)
                        throws java.security.InvalidKeyException

Abstract method to be implemented for decoding a DER encoded private key.

Parameters:

privateKey - the private key as DER encoded byte array

Throws:

java.security.InvalidKeyException - if the does not match to the implemented public-key algorithm

encode

protected abstract byte[] encode()

Abstract method to be implemented for encoding this private key according to DER.

Returns:

the private key as a DER encoded ASN.1 data structure

getAlgorithm

public abstract java.lang.String getAlgorithm()

Returns the name of the algorithm.

Specified by:

getAlgorithm in interface java.security.Key

Returns:

the name of the algorithm

getAlgorithmID

public AlgorithmID getAlgorithmID()

Returns the key algorithm id.

Returns:

the key algorithm id

setAttributes

public void setAttributes(Attribute[] attributes)

Sets any attributes to be included.

Parameters:

attributes - the attributes

getAttributes

public Attribute[] getAttributes()

Gets any included attributes.

Returns:

the included attributes or null if no attributes are included

setPubKey

public void setPubKey(java.security.PublicKey publicKey)
               throws java.security.InvalidKeyException

Sets the public key (if to be included).

Parameters:

publicKey - the public key

Throws:

java.security.InvalidKeyException - if the public key algorithm is not appropriate for this private key

getPubKey

public java.security.PublicKey getPubKey()

Gets the public key (if included).

Returns:

the public key (if included)

clone

public java.lang.Object clone()

Return a clone of this private key object. The clone is not a deep clone (i.e. if attributes, publicKey fields are present the clone will contain the same attributes, publicKey fields as the original key.

Overrides:

clone in class java.lang.Object

Returns:

A clone of this private key object.

decode

public void decode(ASN1Object obj)
            throws CodingException

Decodes the given ASN.1 PrivateKeyInfo object for parsing the internal structure.

This method implements the ASN1Type interface and internally is called when creating a PKCS#8 PrivateKeyInfo object from an already existing PrivateKeyInfo object, supplied as ASN1Object or DER encoded ASN1Object.

Specified by:

decode in interface ASN1Type

Parameters:

obj - the PrivateKeyInfo as ASN1Object

Throws:

CodingException - if the ASN1Object could not be parsed

createPrivateKeyInfo

protected void createPrivateKeyInfo()

Creates a PrivateKeyInfo ASN.1 data structure (PKCS#8).

This method is called by extending classes for creating a PrivateKeyInfo. This method creates a PrivateKeyInfo as an ASN.1 SEQUENCE object with components as specified in the PKCS#8 Private-Key Information Syntax Standard:

• Version (integer)
• PrivateKeyAlgorithmIdentifier
• PrivateKey (OCTET STRING)
• Attributes (SET Of Attribute; optional)

getPrivateKey

public static java.security.PrivateKey getPrivateKey(ASN1Object privateKeyInfo)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey from an ASN1Object.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

Parameters:

privateKeyInfo - the PrivateKeyInfo as ASN1Object

Returns:

an instance of java.security.PrivateKey, parsed from the supplied ASN1Object; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the ASN1Object cannot be parsed

getPrivateKey

public static java.security.PrivateKey getPrivateKey(ASN1Object privateKeyInfo,
                                     java.lang.String providerName)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey for the given provider from an ASN1Object.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

Parameters:

privateKeyInfo - the PrivateKeyInfo as ASN1Object

providerName - the name of the provider from which to get a PrivateKey object

Returns:

an instance of java.security.PrivateKey, parsed from the supplied ASN1Object; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the ASN1Object cannot be parsed

getPrivateKey

public static java.security.PrivateKey getPrivateKey(ASN1Object privateKeyInfo,
                                     java.security.Provider provider)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey for the given provider from an ASN1Object.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

If Provider object based JCA/JCE KeyFactory engine instantiation is not available the Java VM in use (<1.4), this method tries to instantiate an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method KeyFactory.getInstance(algorithm,provider) is not available method KeyFactory.getInstance(algorithm,provider.getName()) is tried.

Parameters:

privateKeyInfo - the PrivateKeyInfo as ASN1Object

provider - the provider from which to get a PrivateKey object

Returns:

an instance of java.security.PrivateKey, parsed from the supplied ASN1Object; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the ASN1Object cannot be parsed

getPrivateKey

public static java.security.PrivateKey getPrivateKey(byte[] privateKeyInfo)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

Parameters:

privateKeyInfo - the PrivateKey as DER encoded byte array

Returns:

an instance of java.security.PrivateKey, parsed from the supplied DER encoding; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the privateKey cannot be parsed

getPrivateKey

public static java.security.PrivateKey getPrivateKey(byte[] privateKeyInfo,
                                     java.lang.String providerName)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey for the given provider from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

Parameters:

privateKeyInfo - the PrivateKey as DER encoded byte array

providerName - the name of the provider from which to get a PrivateKey object

Returns:

an instance of java.security.PrivateKey, parsed from the supplied DER encoding; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the privateKey cannot be parsed

getPrivateKey

public static java.security.PrivateKey getPrivateKey(byte[] privateKeyInfo,
                                     java.security.Provider provider)
                                              throws java.security.InvalidKeyException

Creates a PrivateKey for the given provider from a DER encoded byte array in PKCS#8 PrivateKeyInfo format.

This method tries to instantiate a KeyFactory for the key algorithm. If no KeyFactory is available a generic PrivateKey is created allowing to get some information about the key (algorithm, encoding).

If Provider object based JCA/JCE KeyFactory engine instantiation is not available the Java VM in use (<1.4), this method tries to instantiate an implementation based on the provider name (if the Provider is installed within the Security Provider framework). I.e. if method KeyFactory.getInstance(algorithm,provider) is not available method KeyFactory.getInstance(algorithm,provider.getName()) is tried.

Parameters:

privateKeyInfo - the PrivateKey as DER encoded byte array

provider - the provider from which to get a PrivateKey object

Returns:

an instance of java.security.PrivateKey, parsed from the supplied DER encoding; if no KeyFactory is available for the key algorithm a RawPrivateKey object is returned

Throws:

java.security.InvalidKeyException - if the privateKey cannot be parsed

toASN1Object

public ASN1Object toASN1Object()

Returns this PrivateKeyInfo as ASN1Object.

Specified by:

toASN1Object in interface ASN1Type

Returns:

this PrivateKeyInfo as ASN1Object

equals

public boolean equals(java.lang.Object obj)

Compares this private key to another private key. This method simply compares the DER encoded versions of the keys.

Overrides:

equals in class java.lang.Object

Returns:

true, if the 2 private keys are equal, false otherwise

hashCode

public int hashCode()

Returns a hash code for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

getEncoded

public byte[] getEncoded()

Returns this PrivateKeyInfo as a DER encoded ASN.1 data structure.

Specified by:

getEncoded in interface java.security.Key

Returns:

this PrivateKeyInfo as DER encoded byte array

getFormat

public java.lang.String getFormat()

Returns the name of the encoding format..

Specified by:

getFormat in interface java.security.Key

Returns:

the string "PKCS#8"

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes this private key to an output stream.

Parameters:

os - the output stream

Throws:

java.io.IOException - if an I/O error occurs

toString

public java.lang.String toString()

Returns a string that represents the contents of this private key.

Overrides:

toString in class java.lang.Object

Returns:

the string representation