iaik.pkcs.pkcs12
Class PKCS12

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

public class PKCS12

extends java.lang.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!

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(java.io.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.
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.
ASN1Object	toASN1Object() Returns this PKCS#12 object as ASN1Object.
java.lang.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(java.io.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(java.io.InputStream is)
       throws java.io.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:

java.io.IOException - if the object could not be read

PKCSParsingException - if the object could not be parsed

PKCS12

public PKCS12(ASN1Object obj)
       throws PKCSParsingException,
              java.io.IOException

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,
                      java.io.IOException

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.

Parameters:

password - the password to decrypt the PKCS#12 object

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

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 RC4.

Parameters:

password - the password for performing privacy encryption and integrity MAC computation

algorithm - the ID (and any associated parameters) of the PBE algorithm to be used for password-based encrypting the inherent AuthenticatedSafe objects claiming for password-privacy mode; Attention: this ID does not specify the MAC algorithm for fulfilling the password-integrity mode (for this, HMAC/SHA is used)

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(java.io.OutputStream os)
             throws java.io.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 java.lang.String toString()

Returns a string giving some information about this PKCS12 object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation