com.ibm.security.pkcs12
Class PFX

com.ibm.security.pkcs12.PFX

public final class PFX
implements Cloneable

Implements the PKCS #12 PFX PDU type in a format importable into Netscape Communicator's certificate database or Microsoft's Certificate Import Wizard. These PFXs are a subset of those described by the PKCS #12 standard, and certain requirements must be met in their construction. For example, these PFXs must use password integrity mode and therefore include a MacData. The password used to create the message authentication code must be the same password used to provide protection to any data that is privacy protected. Another requirement is that all data items in the PFX must include a LocalKeyId attribute. There are other requirements as well.

The format of a PFX object is as follows:

PFX ::= SEQUENCE { version INTEGER, // 3 for this PKCS #12 v1.0 authSafe ContentInfo, // content type Data macData MacData // not OPTIONAL in this class }

To construct a PKCS #12 PFX that deviates from the format required by Netscape or Microsoft, for example, one that uses public-key cryptotography, use the PKCS12PFX class.

PFX objects are not immutable; they may be changed once created. After construction, data items such as private keys, encrypted private keys, certificates and certificate revocation lists may be added. In addition, a message authentication code can be added to protect the data integrity of the PFX.

See Also:
ContentInfo, MacData, PKCS12PFX

Constructor Summary
PFX()
          Create a PFX object with data attributes to be filled in later.
PFX(byte[] der)
          Create a PFX object with a DER byte array.
PFX(byte[] der, String provider)
          Create a PFX object with a DER byte array.
PFX(String provider)
          Create a PFX object with data attributes to be filled in later.
PFX(String filename, boolean base64)
          Create a PFX with the filename of the DER-encoded or BASE64-encoded object.
PFX(String filename, boolean base64, String provider)
          Create a PFX with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 void addCertificate(Certificate cert, String friendlyName, byte[] localKeyId)
          Add a certificate to this PFX object.
 void addCRL(CRL crl, String friendlyName, byte[] localKeyId)
          Add a certificate revocation list (CRL) to this PFX object.
 void addPrivateKey(PrivateKey key, String friendlyName, byte[] localKeyId)
          Add a private key to this PFX object.
 void addShroudedKey(EncryptedPrivateKeyInfo key, String friendlyName, byte[] localKeyId)
          Add a shrouded key (encrypted private key) to this PFX object.
 Object clone()
          Creates a clone of this PFX object.
protected  void decode(com.ibm.security.pkcs12.DerValue der)
          Initialize a PFX object from an input stream.
 void encode(OutputStream out)
          Encodes this object to a DER OutputStream.
 boolean equals(Object other)
          Determines if this PFX object is equivalent to the input object.
protected  void finalize()
          Ensures that the bytes of this key are set to zero when there are no more references to it.
 Certificate[] getCertificates(char[] pwd)
          Get all certificates stored in this PFX and protected with the input password.
 Certificate[] getCertificatesByFriendlyName(char[] pwd, String friendlyName)
          Get all certificates stored in this PFX having the input friendly name and protected with the input password (or unprotected).
 CRL[] getCRLs(char[] pwd)
          Get all certificate revocation lists (CRLs) stored in this PFX and protected with the input password.
 String[] getFriendlyNames(char[] pwd)
          Get all friendly names attached to data items stored in this PFX and protected with the input password (or unprotected).
 MacData getMacData()
          Returns the MacData (SHA-1 HMAC) of this PFX.
 PrivateKeyInfo[] getPrivateKeys(char[] pwd)
          Get all private keys stored in this PFX and protected with the input password.
 PrivateKeyInfo[] getPrivateKeysByFriendlyName(char[] pwd, String friendlyName)
          Get all private keys stored in this PFX having the input friendly name and protected with the input password (or unprotected).
 EncryptedPrivateKeyInfo[] getShroudedKeys(char[] pwd)
          Get all encrypted private keys (shrouded keys) stored in this PFX and protected with the input password.
 EncryptedPrivateKeyInfo[] getShroudedKeysByFriendlyName(char[] pwd, String friendlyName)
          Get all encrypted private keys (shrouded keys) stored in this PFX having the input friendly name and protected with the input password (or unprotected).
 void protect(String encryptionAlg, char[] pwd)
          Protect the private information in this PFX and attach a message authentication code based on the enclosed data.
 String toString()
          Returns a string representation of this PFX object.
 boolean verifyMac(char[] pwd)
          Verifies the message authentication code attached to this PFX.
 

Constructor Detail

PFX

public PFX()
Create a PFX object with data attributes to be filled in later.

PFX

public PFX(String provider)
Create a PFX object with data attributes to be filled in later.

PFX

public PFX(byte[] der)
    throws IOException
Create a PFX object with a DER byte array. The DER byte array should be the encoding of a PFX that is importable into Netscape or the Microsoft Certificate Import Wizard.

This PFX should be treated as a "read-only" object. If you add any data and then protect it, the original information contained in the input DER byte array will be lost.


PFX

public PFX(byte[] der,
           String provider)
    throws IOException
Create a PFX object with a DER byte array. The DER byte array should be the encoding of a PFX that is importable into Netscape or the Microsoft Certificate Import Wizard.

This PFX should be treated as a "read-only" object. If you add any data and then protect it, the original information contained in the input DER byte array will be lost.


PFX

public PFX(String filename,
           boolean base64)
    throws IOException
Create a PFX 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.

PFX

public PFX(String filename,
           boolean base64,
           String provider)
    throws IOException
Create a PFX 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 - a provider to be used
Throws:
IOException - on decoding errors.
Method Detail

clone

public Object clone()
Creates a clone of this PFX object.
Returns:
clone of this PFX object.

addCertificate

public void addCertificate(Certificate cert,
                           String friendlyName,
                           byte[] localKeyId)
                    throws PKCSException
Add a certificate to this PFX object. Information must be protected by the protect method before it is available in the PFX.
Parameters:
cert - the certificate to add.
friendlyName - the name to be used as the label for this certificate. This may be null.
localKeyId - the local key id attribute for this certificate.
Throws:
PKCSException - if the input is invalid or if the information cannot be added to the PFX.

addPrivateKey

public void addPrivateKey(PrivateKey key,
                          String friendlyName,
                          byte[] localKeyId)
                   throws PKCSException,
                          IOException
Add a private key to this PFX object. Information must be protected by the protect method before it is available in the PFX.
Parameters:
key - the private key to add.
friendlyName - the name to be used as the label for this key. This may be null.
localKeyId - the local key id attribute for this private key.
Throws:
PKCSException - if the input is invalid or if the information cannot be added to the PFX.

addShroudedKey

public void addShroudedKey(EncryptedPrivateKeyInfo key,
                           String friendlyName,
                           byte[] localKeyId)
                    throws PKCSException
Add a shrouded key (encrypted private key) to this PFX object. Information must be protected by the protect method before it is available in the PFX.
Parameters:
key - the shrouded key to add.
friendlyName - the name to be used as the label for this key. This may be null.
localKeyId - the local key id attribute for this shrouded key.
Throws:
PKCSException - if the input is invalid or if the information cannot be added to the PFX.

addCRL

public void addCRL(CRL crl,
                   String friendlyName,
                   byte[] localKeyId)
            throws PKCSException
Add a certificate revocation list (CRL) to this PFX object. Information must be protected by the protect method before it is available in the PFX.
Parameters:
crl - the CRL to add.
friendlyName - the name to be used as the label for this CRL. This may be null.
localKeyId - the local key id attribute for this CRL.
Throws:
PKCSException - if the input is invalid or if the information cannot be added to the PFX.

protect

public void protect(String encryptionAlg,
                    char[] pwd)
             throws NoSuchAlgorithmException,
                    IOException,
                    PKCSException
Protect the private information in this PFX and attach a message authentication code based on the enclosed data. If PFX data has been previously protected using a different password or algorithm, the data will be reprotected and a new HMAC calculated. No data added to the PFX is available until it has been protected.
Parameters:
encryptionAlg - the algorithm used to protect the PFX data. Valid values are "3KeyTripleDES", "2KeyTripleDES", "40BitRC2", "128BitRC2", "40BitRC4" and "128BitRC4".
pwd - the password used in the data encryption operation.
Throws:
NoSuchAlgorithmException - if the input algorithm is not found on the system.
IOException -  
PKCSException -  

getPrivateKeys

public PrivateKeyInfo[] getPrivateKeys(char[] pwd)
                                throws IOException,
                                       PKCSException
Get all private keys stored in this PFX and protected with the input password. This method will also return unprotected private keys.
Parameters:
pwd - the password with which to decrypt the private keys.
Returns:
an array of all the private keys retrievable using the input password, including unprotected private keys.
Throws:
PKCSException -  
IOException -  

getShroudedKeys

public EncryptedPrivateKeyInfo[] getShroudedKeys(char[] pwd)
                                          throws IOException,
                                                 PKCSException
Get all encrypted private keys (shrouded keys) stored in this PFX and protected with the input password. This method will also return unprotected shrouded keys.
Parameters:
pwd - the password with which to decrypt the shrouded keys.
Returns:
an array of all the shrouded keys retrievable using the input password, including unprotected shrouded keys.
Throws:
PKCSException -  
IOException -  

getCertificates

public Certificate[] getCertificates(char[] pwd)
                              throws IOException,
                                     PKCSException
Get all certificates stored in this PFX and protected with the input password. This method will also return unprotected certificates.
Parameters:
pwd - the password with which to decrypt the certificates.
Returns:
an array of all the certificates retrievable using the input password, including unprotected certificates.
Throws:
PKCSException -  
IOException -  

getCRLs

public CRL[] getCRLs(char[] pwd)
              throws IOException,
                     PKCSException
Get all certificate revocation lists (CRLs) stored in this PFX and protected with the input password. This method will also return unprotected CRLs.
Parameters:
pwd - the password with which to decrypt the CRLs.
Returns:
an array of all the CRLs retrievable using the input password, including unprotected CRLs.
Throws:
PKCSException -  
IOException -  

getFriendlyNames

public String[] getFriendlyNames(char[] pwd)
                          throws PKCSException
Get all friendly names attached to data items stored in this PFX and protected with the input password (or unprotected).
Parameters:
pwd - the password with which to decrypt the contents.
Returns:
an array of all the friendly names retrievable using the input password.

getCertificatesByFriendlyName

public Certificate[] getCertificatesByFriendlyName(char[] pwd,
                                                   String friendlyName)
                                            throws PKCSException
Get all certificates stored in this PFX having the input friendly name and protected with the input password (or unprotected).
Parameters:
pwd - the password with which to decrypt the certificates.
friendlyName - the friendly name to search for.
Returns:
an array of all the certificates with the specified friendly name retrievable using the input password, including unprotected certificates.
Throws:
PKCSException -  

getPrivateKeysByFriendlyName

public PrivateKeyInfo[] getPrivateKeysByFriendlyName(char[] pwd,
                                                     String friendlyName)
                                              throws PKCSException
Get all private keys stored in this PFX having the input friendly name and protected with the input password (or unprotected).
Parameters:
pwd - the password with which to decrypt the certificates.
friendlyName - the friendly name to search for.
Returns:
an array of all the private keys with the specified friendly name retrievable using the input password, including unprotected private keys.
Throws:
PKCSException -  

getShroudedKeysByFriendlyName

public EncryptedPrivateKeyInfo[] getShroudedKeysByFriendlyName(char[] pwd,
                                                               String friendlyName)
                                                        throws PKCSException
Get all encrypted private keys (shrouded keys) stored in this PFX having the input friendly name and protected with the input password (or unprotected).
Parameters:
pwd - the password with which to decrypt the certificates.
friendlyName - the friendly name to search for.
Returns:
an array of all the shrouded keys with the specified friendly name retrievable using the input password, including unprotected shrouded keys.
Throws:
PKCSException -  

encode

public void encode(OutputStream out)
            throws IOException
Encodes this object to a DER OutputStream.
Parameters:
out - the DER OutputStream to write the encoded data to.
Throws:
IOException - on encoding errors, including if the contents have not been integrity-protected with a MAC or a digital signature.

equals

public boolean equals(Object other)
Determines if this PFX object is equivalent to the input object.
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 PFX object.
Returns:
a string representation of this object.

verifyMac

public boolean verifyMac(char[] pwd)
                  throws IOException
Verifies the message authentication code attached to this PFX.
Parameters:
pwd - the password used to verify the MAC.
Returns:
true, if the attached MAC is verifiable with this password; false, otherwise (including if there is no attached MAC).
Throws:
IOException -  

getMacData

public MacData getMacData()
Returns the MacData (SHA-1 HMAC) of this PFX.
Returns:
the MacData of this PFX.

decode

protected void decode(com.ibm.security.pkcs12.DerValue der)
               throws IOException
Initialize a PFX object from an input stream. The data on that input stream must be a DER-encoded PFX object and should be the encoding of a PFX that is importable into Netscape or the Microsoft Certificate Import Wizard.
Parameters:
encoding - an input stream with a DER-encoded PFX object.
Throws:
IOException - on parsing errors.

finalize

protected void finalize()
Ensures that the bytes of this key are set to zero when there are no more references to it.