com.ibm.security.pkcs12
Class PKCS12PFX

com.ibm.security.pkcs12.PKCS12PFX

public final class PKCS12PFX
implements Cloneable

Implements the PKCS #12 PFX PDU type. The data in a PFX can be protected in one of two integrity modes: password or public-key integrity. The individual data items can be protected in one of three privacy modes: no privacy, password privacy or public-key privacy.

A PKCS #12 PFX PDU is composed of a PKCS #7 ContentInfo object of content type Data (in password-integrity mode) or content type SignedData (in public-key integrity mode) and an optional MAC data (present only in password-integrity mode). The version number is 3 for the PKCS #12 v1.0 standard (dated June 24, 1999).

PFX ::= SEQUENCE { version INTEGER, authSafe ContentInfo macData MacData OPTIONAL }

The authSafe ContentInfo contents is itself a sequence of ContentInfos which may each be protected in one of three privacy modes: no privacy (content type Data), password privacy (content type SignedData) or public-key privacy (content type EnvelopedData). Netscape and most other PFX applications do not support public-key integrity or privacy. There are also certain requirements on the methodology of password protection for Netscape-importable PFXs. For this reason, if you wish to construct a PFX for use in Netscape browsers, use the PFX class.

PKCS12PFX 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, PFX

Constructor Summary
PKCS12PFX()
          Create a PKCS12PFX object with attributes to be filled in later.
PKCS12PFX(byte[] der)
          Create a PKCS12PFX object with a DER byte array.
PKCS12PFX(byte[] der, String provider)
          Create a PKCS12PFX object with a DER byte array.
PKCS12PFX(String provider)
          Create a PKCS12PFX object with attributes to be filled in later.
PKCS12PFX(String filename, boolean base64)
          Create a PKCS12PFX with the filename of the DER-encoded or BASE64-encoded object.
PKCS12PFX(String filename, boolean base64, String provider)
          Create a PKCS12PFX with the filename of the DER-encoded or BASE64-encoded object.
 
Method Summary
 void addBag(Object obj, PKCSAttributes attrs)
          Add a piece of private information (represented by an input object) to this PFX.
 void addBagWithPasswordPrivacy(Object obj, PKCSAttributes attrs, String cipherAlg, char[] pwd)
          Add a piece of private information (represented by an input object) to this PFX.
 void addBagWithPubkeyPrivacy(Object obj, PKCSAttributes attrs, Certificate[] certs)
          Add a piece of private information (represented by an input object) to this PFX.
 void addSafeBags(SafeBag[] bags)
          Add private information (packaged in SafeBags) to this PFX.
 void addSafeBagsWithPasswordPrivacy(SafeBag[] bags, String cipherAlg, char[] pwd)
          Add private information (packaged in SafeBags) to this PFX.
 void addSafeBagsWithPubkeyPrivacy(SafeBag[] bags, Certificate[] certs)
          Add private information (packaged in SafeBags) to this PFX.
 void applyMac(char[] pwd)
          Apply a message authentication code to the contents of this PFX.
 void applySignature(String digestAlg, String signatureAlg, Certificate cert, PrivateKey key)
          Apply a digital signature to the contents of this PFX.
 Object clone()
          Create a clone of this PFX object.
protected  void decode(com.ibm.security.pkcs12.DerValue encoding)
          Initialize a PFX object from an input stream.
 void encode(OutputStream out)
          Encode this object to a DER OutputStream.
 boolean equals(Object other)
          Determine if this PFX object is equivalent to the input object.
 Certificate[] getAllCertificates(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getCertificates method except that unprotected certificates are returned, regardless of input arguments.
 CRL[] getAllCRLs(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getCRLs method except that unprotected CRLs are returned, regardless of input arguments.
 PrivateKeyInfo[] getAllPrivateKeys(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getPrivateKeys method except that unprotected private keys are returned, regardless of input arguments.
 SafeBag[] getAllSafeBags(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getSafeBags method except that unprotected SafeBags are returned, regardless of input arguments.
 SafeContents[] getAllSafeContents(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getSafeContents method except that unprotected SafeContents are returned, regardless of input arguments.
 EncryptedPrivateKeyInfo[] getAllShroudedKeys(char[] pwd, PrivateKey key, Certificate cert)
          Same as the getShroudedKeys method except that unprotected shrouded keys are returned, regardless of input arguments.
 Certificate[] getCertificates(char[] pwd, PrivateKey key, Certificate cert)
          Get certificates stored in this PFX.
 CRL[] getCRLs(char[] pwd, PrivateKey key, Certificate cert)
          Get certificate revocation lists (CRLs) stored in this PFX.
 MacData getMacData()
          Returns the MacData (SHA-1 HMAC) of this PFX, or null if this PFX has not been protected with password integrity.
 PrivateKeyInfo[] getPrivateKeys(char[] pwd, PrivateKey key, Certificate cert)
          Get private keys stored in this PFX.
 SafeBag[] getSafeBags(char[] pwd, PrivateKey key, Certificate cert)
          Get SafeBags stored in this PFX.
 SafeContents[] getSafeContents(char[] pwd, PrivateKey key, Certificate cert)
          Get SafeContents stored in this PFX.
 EncryptedPrivateKeyInfo[] getShroudedKeys(char[] pwd, PrivateKey key, Certificate cert)
          Get encrypted private keys (shrouded keys) stored in this PFX.
 boolean hasDigitalSignature()
          Determine if this PFX has a digital signature on the authSafe data.
 String toString()
          Returns a string representation of this PFX object.
 boolean verifyMac(char[] pwd)
          Verifies the message authentication code attached to this PFX.
 boolean verifySignature(Certificate cert)
          Verify the digital signature on the SignedData contents of this PFX's authSafe.
 

Constructor Detail

PKCS12PFX

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

PKCS12PFX

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

PKCS12PFX

public PKCS12PFX(byte[] der)
          throws IOException
Create a PKCS12PFX object with a DER byte array.

PKCS12PFX

public PKCS12PFX(byte[] der,
                 String provider)
          throws IOException
Create a PKCS12PFX object with a DER byte array.

PKCS12PFX

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

PKCS12PFX

public PKCS12PFX(String filename,
                 boolean base64,
                 String provider)
          throws IOException
Create a PKCS12PFX 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()
Create a clone of this PFX object.
Returns:
clone of this PFX object.

addBag

public void addBag(Object obj,
                   PKCSAttributes attrs)
            throws PKCSException,
                   IOException
Add a piece of private information (represented by an input object) to this PFX. The information will not be protected with any form of privacy.
Parameters:
obj - the object to add to this PFX. Valid input objects are PrivateKeyInfo (KeyBag), EncryptedPrivateKeyInfo(ShroudedKeyBag), Certificate (CertBag), CRL (CrlBag) and SafeContents (SafeContentsBag). This method does not currently support SecretBags.
attrs - PKCS attributes to associate with this object.
Throws:
PKCSException -  
IOException -  

addBagWithPasswordPrivacy

public void addBagWithPasswordPrivacy(Object obj,
                                      PKCSAttributes attrs,
                                      String cipherAlg,
                                      char[] pwd)
                               throws NoSuchAlgorithmException,
                                      IOException,
                                      PKCSException
Add a piece of private information (represented by an input object) to this PFX. The information will be protected with password privacy based upon the input cipher algorithm and password.
Parameters:
obj - the object to add to this PFX. Valid input objects are PrivateKeyInfo (KeyBag), EncryptedPrivateKeyInfo(ShroudedKeyBag), Certificate (CertBag), CRL (CrlBag) and SafeContents (SafeContentsBag). This method does not currently support SecretBags.
attrs - PKCS attributes to associate with this object.
cipherAlg - the cipher algoirithm used to password-protect the information. The cipher must be one of "128BitRC2", "40BitRC2", "3KeyTripleDES", "2KeyTripleDES", "128BitRC4" or "40BitRC4". All encryption will incorporate SHA-1 digests, PKCS5Padding and CBC chaining mode.
pwd - the password to use in the encryption.
Throws:
PKCSException -  
IOException -  
NoSuchAlgorithmException -  

addBagWithPubkeyPrivacy

public void addBagWithPubkeyPrivacy(Object obj,
                                    PKCSAttributes attrs,
                                    Certificate[] certs)
                             throws PKCSException,
                                    IOException
Add a piece of private information (represented by an input object) to this PFX. The information will be protected with public-key privacy. The information will be protected within an EnvelopedData ContentInfo, and the recipients within the ContentInfo are represented by the input certificates.
Parameters:
obj - the object to add to this PFX. Valid input objects are PrivateKeyInfo (KeyBag), EncryptedPrivateKeyInfo(ShroudedKeyBag), Certificate (CertBag), CRL (CrlBag) and SafeContents (SafeContentsBag). This method does not currently support SecretBags.
attrs - PKCS attributes to associate with this object.
certs - the certificates of the intended receivers of this PFX.
Throws:
PKCSException -  
IOException -  

addSafeBags

public void addSafeBags(SafeBag[] bags)
                 throws PKCSException,
                        IOException
Add private information (packaged in SafeBags) to this PFX. The information will not be protected with any form of privacy.
Parameters:
bags - the SafeBags to add to this PFX.
Throws:
PKCSException -  
IOException -  

addSafeBagsWithPasswordPrivacy

public void addSafeBagsWithPasswordPrivacy(SafeBag[] bags,
                                           String cipherAlg,
                                           char[] pwd)
                                    throws NoSuchAlgorithmException,
                                           IOException,
                                           PKCSException
Add private information (packaged in SafeBags) to this PFX. The information will be protected with password privacy based upon the input cipher algorithm and password. information will not be protected with any form of privacy.
Parameters:
bags - the SafeBags to add to this PFX.
cipherAlg - the cipher algoirithm used to password-protect the information. The cipher must be one of "128BitRC2", "40BitRC2", "3KeyTripleDES", "2KeyTripleDES", "128BitRC4" or "40BitRC4". All encryption will incorporate SHA-1 digests, PKCS5Padding and CBC chaining mode.
pwd - the password to use in the encryption.
Throws:
PKCSException -  
IOException -  

addSafeBagsWithPubkeyPrivacy

public void addSafeBagsWithPubkeyPrivacy(SafeBag[] bags,
                                         Certificate[] certs)
                                  throws PKCSException,
                                         IOException
Add private information (packaged in SafeBags) to this PFX. The information will be protected with public-key privacy. The information will be protected within an EnvelopedData ContentInfo, and the recipients within the ContentInfo are represented by the input certificates.
Parameters:
bags - the SafeBags to add to this PFX.
certs - the certificates of the intended receivers of this PFX.
Throws:
PKCSException -  
IOException -  

applySignature

public void applySignature(String digestAlg,
                           String signatureAlg,
                           Certificate cert,
                           PrivateKey key)
                    throws PKCSException,
                           NoSuchAlgorithmException,
                           IOException
Apply a digital signature to the contents of this PFX. If the PFX has been previoyusly MAC'd, the macData will be erased.
Parameters:
digestAlg - the digest algorithm for the digital signature, for example "SHA1".
signatureAlg - the signature algorithm for the digital signature, for example "RSA".
cert - the certificate of the signing entity.
key - the private key of the signing entity.
Throws:
PKCSException -  
NoSuchAlgorithmException -  
IOException -  

verifySignature

public boolean verifySignature(Certificate cert)
                        throws IOException,
                               PKCSException,
                               NoSuchAlgorithmException
Verify the digital signature on the SignedData contents of this PFX's authSafe.
Parameters:
cert - the certificate with which to verify the signature.
Returns:
true, if the signature is verifiable with the input certificate; false, otherwise.
Throws:
IOException -  
PKCSException -  
NoSuchAlgorithmException -  

hasDigitalSignature

public boolean hasDigitalSignature()
Determine if this PFX has a digital signature on the authSafe data.
Returns:
true, if the authSafe data is signed; false, otherwise.

encode

public void encode(OutputStream out)
            throws IOException
Encode 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)
Determine 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.

applyMac

public void applyMac(char[] pwd)
              throws PKCSException,
                     NoSuchAlgorithmException,
                     IOException
Apply a message authentication code to the contents of this PFX. If the PFX has been digitally signed, the signature will be erased. HMAC is used as the message authentication code.
Parameters:
pwd - the password with which to derive the HMAC key.
Throws:
PKCSException -  
NoSuchAlgorithmException -  
IOException -  

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, or null if this PFX has not been protected with password integrity.
Returns:
the MacData of this PFX, or null if this PFX has not been protected with password integrity.

getCertificates

public Certificate[] getCertificates(char[] pwd,
                                     PrivateKey key,
                                     Certificate cert)
                              throws IOException,
                                     PKCSException
Get certificates stored in this PFX. To get all unprotected certificates, pass in null for all arguments. To get certificates protected with password privacy, pass in the password and null for the other two arguments. To get certficates protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then certficates protected by the password and those protected by the input certificate public key are returned. If certificate data is protected by different passwords or public keys, this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the certificates retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllCertificates

public Certificate[] getAllCertificates(char[] pwd,
                                        PrivateKey key,
                                        Certificate cert)
                                 throws IOException,
                                        PKCSException
Same as the getCertificates method except that unprotected certificates are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the certificates retrievable using the input arguments, including unprotected certificates.
Throws:
PKCSException -  
IOException -  

getCRLs

public CRL[] getCRLs(char[] pwd,
                     PrivateKey key,
                     Certificate cert)
              throws IOException,
                     PKCSException
Get certificate revocation lists (CRLs) stored in this PFX. To get all unprotected CRLs, pass in null for all arguments. To get CRLs protected with password privacy, pass in the password and null for the other two arguments. To get CRLs protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then CRLs protected by the password and those protected by the input certificate public key are returned. If CRL data is protected by different passwords or public keys, this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the certificate revocation lists retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllCRLs

public CRL[] getAllCRLs(char[] pwd,
                        PrivateKey key,
                        Certificate cert)
                 throws IOException,
                        PKCSException
Same as the getCRLs method except that unprotected CRLs are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the CRLs retrievable using the input arguments, including unprotected CRLs.
Throws:
PKCSException -  
IOException -  

getPrivateKeys

public PrivateKeyInfo[] getPrivateKeys(char[] pwd,
                                       PrivateKey key,
                                       Certificate cert)
                                throws IOException,
                                       PKCSException
Get private keys stored in this PFX. To get all unprotected private keys, pass in null for all arguments. To get private keys protected with password privacy, pass in the password and null for the other two arguments. To get private keys protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then private keys protected by the password and those protected by the input certificate public key are returned. If private key data is protected by different passwords or public keys, this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the private keys retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllPrivateKeys

public PrivateKeyInfo[] getAllPrivateKeys(char[] pwd,
                                          PrivateKey key,
                                          Certificate cert)
                                   throws IOException,
                                          PKCSException
Same as the getPrivateKeys method except that unprotected private keys are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the private keys retrievable using the input arguments, including unprotected private keys.
Throws:
PKCSException -  
IOException -  

getShroudedKeys

public EncryptedPrivateKeyInfo[] getShroudedKeys(char[] pwd,
                                                 PrivateKey key,
                                                 Certificate cert)
                                          throws IOException,
                                                 PKCSException
Get encrypted private keys (shrouded keys) stored in this PFX. To get all unprotected shrouded keys, pass in null for all arguments. To get shrouded keys protected with password privacy, pass in the password and null for the other two arguments. To get shrouded keys protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then shrouded keys protected by the password and those protected by the input certificate public key are returned. If shrouded key data is protected by different passwords or public keys, * this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the shrouded keys retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllShroudedKeys

public EncryptedPrivateKeyInfo[] getAllShroudedKeys(char[] pwd,
                                                    PrivateKey key,
                                                    Certificate cert)
                                             throws IOException,
                                                    PKCSException
Same as the getShroudedKeys method except that unprotected shrouded keys are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the shrouded keys retrievable using the input arguments, including unprotected shrouded keys.
Throws:
PKCSException -  
IOException -  

getSafeContents

public SafeContents[] getSafeContents(char[] pwd,
                                      PrivateKey key,
                                      Certificate cert)
                               throws IOException,
                                      PKCSException
Get SafeContents stored in this PFX. To get all unprotected SafeContents, pass in null for all arguments. To get SafeContents protected with password privacy, pass in the password and null for the other two arguments. To get SafeContents protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then SafeContents protected by the password and those protected by the input certificate public key are returned. If SafeContents data is protected by different passwords or public keys, this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the SafeContents retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllSafeContents

public SafeContents[] getAllSafeContents(char[] pwd,
                                         PrivateKey key,
                                         Certificate cert)
                                  throws IOException,
                                         PKCSException
Same as the getSafeContents method except that unprotected SafeContents are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the SafeContents retrievable using the input arguments, including unprotected SafeContents.
Throws:
PKCSException -  
IOException -  

getSafeBags

public SafeBag[] getSafeBags(char[] pwd,
                             PrivateKey key,
                             Certificate cert)
                      throws IOException,
                             PKCSException
Get SafeBags stored in this PFX. To get all unprotected SafeBags, pass in null for all arguments. To get SafeBags protected with password privacy, pass in the password and null for the other two arguments. To get SafeBags protected with public key privacy, pass in null for the password and valid values for the certificate and key arguments. If all three arguments are non-null, then SafeBags protected by the password and those protected by the input certificate public key are returned. If SafeBag data is protected by different passwords or public keys, this method must be called separately for each distinct protection mechanism.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the SafeBags retrievable using the input arguments.
Throws:
PKCSException -  
IOException -  

getAllSafeBags

public SafeBag[] getAllSafeBags(char[] pwd,
                                PrivateKey key,
                                Certificate cert)
                         throws IOException,
                                PKCSException
Same as the getSafeBags method except that unprotected SafeBags are returned, regardless of input arguments.
Parameters:
pwd - the password with which to decrypt items protected with password privacy.
key - the private key with which to decrypt items protected with public key protection.
cert - the certificate correspoding to the private key with which to decrypt items protected with public key protection.
Returns:
an array of all the SafeBags retrievable using the input arguments, including unprotected SafeBags.
Throws:
PKCSException -  
IOException -  

decode

protected void decode(com.ibm.security.pkcs12.DerValue encoding)
               throws IOException
Initialize a PFX object from an input stream. The data on that input stream must be a DER-encoded PFX object.
Parameters:
encoding - an input stream with a DER-encoded PFX object.
Throws:
IOException - on parsing errors.