iaik.pkcs.pkcs12
Class PKCS12

java.lang.Object
  |
  +--iaik.pkcs.pkcs12.PKCS12

public class PKCS12

extends Object

This class implements PKCS#12 objects exportet from Netscape Navigator or MS Internet Explorer.

The PKCS#12 Personal Information Exchange Syntax Standard describes a transfer syntax for personal identity information, including private keys, certificates, miscellaneous secrets, and extensions.

This version was successfully testet with Netscape 4.05, 4.5 and can not be used to import files created with version 4.03 or lower. On the MSIE side this version was tested against IE 4.0 with SP3 and SP4 on Windows NT. After installing SP4 on Windows NT one can choose enhanced security when exporting a private key and the corresponding certificate.

Enhanced security in that context means, that when deriving the content encryption keys from the passphrase and the salt the value of the iteration count is set to 2000, thus increasing the cost of brute force attacks against the private key. This feature can be switched on when creating a new PKCS#12 object through setting parameter moreSecure to true in the corresponding constructor. It is also possible to import these secured versions in Navigator 4.5!

Version:

File Revision 26

See Also:

SafeBag, AuthenticatedSafe

Field Summary

protected AuthenticatedSafe[]	authenticated_safes
protected int	mode
static int	PASSWORD_INTEGRITY_MODE The password integrity mode.
static int	PUBLIC_KEY_INTEGRITY_MODE The public-key integrity mode.

Constructor Summary

PKCS12(ASN1Object obj)
Creates a PKCS#12 object from an ASN1Object.

PKCS12(InputStream is)
Creates a new PKCS#12 object from an InputStream.

PKCS12(KeyBag keyBag, CertificateBag[] certificateBags)
Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags.

PKCS12(KeyBag keyBag, CertificateBag[] certificateBags, boolean moreSecure)
Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags.

Method Summary

protected void	decode() Decodes this given PKCS#12 object for parsing the internal structure.
void	decrypt(char[] password) Uses the provided password to decrypt this PKCS12 object for recovering the inherent authenticatedSafes.
void	encrypt(char[] password) Uses the provided password to encrypt the content of this PKCS#12 object.
void	encrypt(char[] password, AlgorithmID authSafesAlg, AlgorithmID shroudedKeyBagAlg) Uses the provided password to encrypt the content of this PKCS#12 object.
AuthenticatedSafe[]	getAuthenticatedSafes() Returns all AuthenticatesSafes included in this PKCS#12 object for manually parsing.
CertificateBag[]	getCertificateBags() Returns an array of all CertificateBags within this PKCS#12 object.
KeyBag	getKeyBag() Tries to find a KeyBag within all AuthenticatedSafes and returns it.
KeyBag[]	getKeyBags() Tries to find KeyBags within all AuthenticatedSafes and returns them.
ASN1Object	toASN1Object() Returns this PKCS#12 object as ASN1Object.
String	toString() Returns a string giving some information about this PKCS12 object.
boolean	verify(char[] password) Verifies the MAC of this PKCS12 object.
void	writeTo(OutputStream os) Writes this PKCS#12 object to the specified output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PUBLIC_KEY_INTEGRITY_MODE

public static final int PUBLIC_KEY_INTEGRITY_MODE

The public-key integrity mode.

PASSWORD_INTEGRITY_MODE

public static final int PASSWORD_INTEGRITY_MODE

The password integrity mode.

authenticated_safes

protected AuthenticatedSafe[] authenticated_safes

mode

protected int mode

Constructor Detail

PKCS12

public PKCS12(KeyBag keyBag,
              CertificateBag[] certificateBags)
       throws PKCSException

Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags. The SafeBags must already include the desired attributes like a friendly name or a local key id.

Parameters:

keyBag - the SafeBag containing the private key

certificateBags - the SafeBags containing the users certificate and maybe a chain to a CA

Throws:

PKCSException - if the PKCS#12 object can not be created because of an encoding problem concerning the private key or the certificates

PKCS12

public PKCS12(KeyBag keyBag,
              CertificateBag[] certificateBags,
              boolean moreSecure)
       throws PKCSException

Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags. The SafeBags must already include the desired attributes like a friendly name or a local key id.

Parameters:

keyBag - the SafeBag containing the private key

certificateBags - the SafeBags containing the users certificate and maybe a chain to a CA

moreSecure - if true, an iteration count of 2000 is used for generating the keys. Take a look at the general class documentation for a description of this parameter.

Throws:

PKCSException - if the PKCS#12 object can not be created because of an encoding problem concerning the private key or the certificates

PKCS12

public PKCS12(InputStream is)
       throws IOException,
              PKCSParsingException

Creates a new PKCS#12 object from an InputStream.

Use this constructor for creating an object from an InputStream containing a DER encoded PKCS#12 object which was exported from MSIE or Netscape.

Parameters:

is - the input stream where the object shall be read from

Throws:

IOException - if the object could not be read

PKCSParsingException - if the object could not be parsed

PKCS12

public PKCS12(ASN1Object obj)
       throws PKCSParsingException

Creates a PKCS#12 object from an ASN1Object.

Do not use this constructor for supplying authenticatedSafes and setting the integrity mode. This constructor may be used for parsing an already exisiting PKCS12 object, supplied as ASN1Object that may have been created by calling toASN1Object.

Parameters:

obj - the PKCS12 object as ASN1Object

Throws:

PKCSParsingException - if the ASN1Object could not be parsed

Method Detail

decode

protected void decode()
               throws PKCSParsingException

Decodes this given PKCS#12 object for parsing the internal structure.

Throws:

PKCSParsingException - if this object can not be parsed

decrypt

public void decrypt(char[] password)
             throws PKCSException

Uses the provided password to decrypt this PKCS12 object for recovering the inherent authenticatedSafes.

This method may be used for performing the decryption after creating a PKCS12 object from a file that has been exported from some platform, e.g.:

 PKCS12 pkcs12 = new PKCS12(new FileInputStream("pkcs12.pfx"));
 pkcs12.decrypt(password);
 

This method automatically decrypts all inherent AuthenticatedSafe objects that have been encrypted with password-encrypted privacy mode. The password may even be null; e.g. if the key has been exported from Internet Explorer without a password.

Parameters:

password - the password to decrypt the PKCS#12 object. null is a valid password.

Throws:

PKCSException - if the PKCS#12 object could not be decrypted

getAuthenticatedSafes

public AuthenticatedSafe[] getAuthenticatedSafes()

Returns all AuthenticatesSafes included in this PKCS#12 object for manually parsing.

Returns:

the authenticates safes

getKeyBag

public KeyBag getKeyBag()

Tries to find a KeyBag within all AuthenticatedSafes and returns it.

Returns:

the KeyBag of this PKCS#12 or null if there is no KeyBag

getKeyBags

public KeyBag[] getKeyBags()

Tries to find KeyBags within all AuthenticatedSafes and returns them.

Returns:

the KeyBaga of this PKCS#12 or an empty array if there is no KeyBag

getCertificateBags

public CertificateBag[] getCertificateBags()

Returns an array of all CertificateBags within this PKCS#12 object. The static method Certificate[] CertificateBag.getCertificates(CertificateBag[]) can be used to convert this array to a Certificate array.

Returns:

all CertificateBags within this PKCS#12 object

verify

public boolean verify(char[] password)
               throws PKCSException

Verifies the MAC of this PKCS12 object.

The MAC is computed by using the HMAC/SHA algorithm based on a sceret key which is derived from pseudorandom inegrity key material of 160 bit length, created with the SHA-1 hash algorithm as proposed by PKCS#12. The salt value necessary for generating the integrity key is derived from the macData, and is the same as has been used when creating this object.

Parameters:

password - the password that was used to protect this PKCS#12 object

Returns:

true if the MAC turns out to be correct, false otherwise

Throws:

PKCSException - if an error occurs during the verification process (e.g. the inherent DigestInfo cannot be parsed; or the MAC computation fails)

encrypt

public void encrypt(char[] password)
             throws PKCSException

Uses the provided password to encrypt the content of this PKCS#12 object. The KeyBag containing the private key is encrypted with a 168 bit TripleDES in CBC mode, and the certificates are encrypted with a 40 bit RC2. The password may even be null; the result is the same as if a key is exported from Internet Explorer without providing a password.

Parameters:

password - the password for performing privacy encryption and integrity MAC computation. null is a valid password.

Throws:

PKCSException - if the PKCS#12 object could not be encrypted

encrypt

public void encrypt(char[] password,
                    AlgorithmID authSafesAlg,
                    AlgorithmID shroudedKeyBagAlg)
             throws PKCSException

Uses the provided password to encrypt the content of this PKCS#12 object. The PBE algorithm to be used for encryption may be any combination of PbeWithSHAAnd40BitRC2_CBC and PbeWithSHAAnd3_KeyTripleDES_CBC. The password may even be null; the result is the same as if a key is exported from Internet Explorer without providing a password.

Parameters:

password - the password for performing privacy encryption and integrity MAC computation. null is a valid password.

authSafesAlg - the PBE algorithm to be used to encrypt authenticated safes

shroudedKeyBagAlg - the PBE algorithm to be used to encrypt the shrouded key bags

Throws:

PKCSException - if the PKCS#12 object could not be encrypted

toASN1Object

public ASN1Object toASN1Object()
                        throws PKCSException

Returns this PKCS#12 object as ASN1Object.

Returns:

this PKCS#12 object as ASN1Object

writeTo

public void writeTo(OutputStream os)
             throws IOException

Writes this PKCS#12 object to the specified output stream.

This method may be used for writing this PFX object to a file to be imported into some platform, e.g.:

 pkcs12.writeTo(new FileOutputStream("pkcs12.pfx"));
 

toString

public String toString()

Returns a string giving some information about this PKCS12 object.

Overrides:

toString in class Object

Returns:

the string representation