PKCS12 ("Entrust Authority Security Toolkit for the Java Platform")

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

```
public class PKCS12
extends java.lang.Object
```
This class implements PKCS#12 objects exported 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 tested 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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`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[] keyBags, CertificateBag[] certificateBags)` Creates a new PKCS#12 object from an array of KeyBags and an array of CertificateBags.
`PKCS12(KeyBag[] keyBags, CertificateBag[] certificateBags, int hashCount)` Creates a new PKCS#12 object from an array of KeyBags and an array of CertificateBags.
`PKCS12(KeyBag keyBag, CertificateBag[] certificateBags)` Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags.
`PKCS12(KeyBag keyBag, CertificateBag[] certificateBags, int hashCount)` Creates a new PKCS#12 object from a KeyBag and an array of CertificateBags.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 algorithm)` Uses the provided password and algorithm to encrypt the content of this PKCS#12 object.
`void`	`encrypt(char[] password, AlgorithmID algorithm, java.security.spec.AlgorithmParameterSpec params)` Uses the provided password to encrypt the content of this PKCS#12 object.
`void`	`encrypt(char[] password, java.lang.String algorithmStringName)` 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.
`void`	`skipUnsupportedSafeBags(boolean skipUnsupportedSafeBags)` Call this method to set the behaviour when an unsupported SafeBag type is encountered when decoding.
`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.
    
    See Also:
    
    Constant Field Values
  - PASSWORD_INTEGRITY_MODE
```
public static final int PASSWORD_INTEGRITY_MODE
```
    The password integrity mode.
    
    See Also:
    
    Constant Field Values
  - 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[] keyBags,
              CertificateBag[] certificateBags)
       throws PKCSException
```
    Creates a new PKCS#12 object from an array of KeyBags and an array of CertificateBags. The SafeBags must already include the desired attributes like a friendly name or a local key id.
    
    Parameters:
    
    keyBags - the SafeBags containing the private keys
    
    certificateBags - the SafeBags containing the users certificates 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,
              int hashCount)
       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
    
    hashCount - the iteration count used to generate the keybags. a hash count of 2000 is recommended.
    
    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[] keyBags,
              CertificateBag[] certificateBags,
              int hashCount)
       throws PKCSException
```
    Creates a new PKCS#12 object from an array of KeyBags and an array of CertificateBags. The SafeBags must already include the desired attributes like a friendly name or a local key id.
    
    Parameters:
    
    keyBags - the SafeBags containing the private keys
    
    certificateBags - the SafeBags containing the users certificate and maybe a chain to a CA
    
    hashCount - the iteration count used to generate the keybags. a hash count of 2000 is recommended.
    
    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
    
    java.io.IOException
- 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
    
    java.io.IOException
  - 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 family algorithms based on a sceret key which is derived from pseudorandom inegrity key material of 160, 224, 256, 384 or 512 bit length, created with the corresponding SHA-1, SHA-224, SHA-256, SHA-384 or SHA-512 hash algorithm as proposed by Appendix A. Message Authentication Codes (MACs). 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. This function uses a Key Derivation Functions (functions specified for PBKDF2) and an encryption scheme (encryption schemes recommended in RFC 8018 and RFC 7292 for PBES2 scheme) to encrypt the content. The KeyBag containing the private key is encrypted using the same PBES2 algorithm.
    The default Pesudo-random Function for PBKDF2 is HmacSHA256 while the underlying encryption scheme is AES-256-CBC.
    salt - default length of eight octets (64 bits) long.
    iteration count - default to 10,000; a minimum of 1000 is recommended.
    
    Parameters:
    
    password - the password for performing privacy encryption and integrity MAC computation
    
    Throws:
    
    PKCSException - if the PKCS#12 object could not be encrypted
  - encrypt
```
public void encrypt(char[] password,
                    java.lang.String algorithmStringName)
             throws PKCSException
```
    Uses the provided password to encrypt the content of this PKCS#12 object. This function uses a Key Derivation Functions (functions specified for PBKDF2) and an encryption scheme (encryption schemes recommended in RFC 8018 and RFC 7292) to encrypt the content. The algorithm string should be in the format
    "PBEWith"+keyDerivationFunctionAlgorithm+"And"+ encryptionSchemeAlgorithm+"_"keyLength Examples for supported algorithms:
    PBEWithHmacSHA1AndAES_128 PBEWithHmacSHA224AndAES_128 PBEWithHmacSHA256AndAES_128 PBEWithHmacSHA384AndAES_128 PBEWithHmacSHA512AndAES_128 PBEWithHmacSHA1AndAES_256 PBEWithHmacSHA224AndAES_256 PBEWithHmacSHA256AndAES_256 PBEWithHmacSHA384AndAES_256 PBEWithHmacSHA512AndAES_256
    
    Parameters:
    
    password - the password for performing privacy encryption and integrity MAC computation
    
    algorithm - the algorithm string for encryption and key derivation
    
    Throws:
    
    PKCSException - if the PKCS#12 object could not be encrypted
  - encrypt
```
public void encrypt(char[] password,
                    AlgorithmID algorithm,
                    java.security.spec.AlgorithmParameterSpec params)
             throws PKCSException
```
    Uses the provided password to encrypt the content of this PKCS#12 object. This function uses a Key Derivation Functions (functions specified for PBKDF2) and an encryption scheme (encryption schemes recommended in RFC 8018 and RFC 7292) to encrypt the content.
    salt - it should be at least eight octets (64 bits) long.
    iteration count - default to 10,000 and a minimum of 1,000 is recommended.
    Key Derivation Function - PBKDF2 with Pseudo-random Functions include HMAC with SHA-1, SHA-224, SHA-256, SHA-384, SHA512, SHA-512/224 and SHA-512/256.
    Encryption Schemes - an underlying encryption scheme Encryption Schemes such as AES-CBC-Pad.
    
    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)
    
    params - the parameter specifications for the algorithm
    
    Throws:
    
    PKCSException - if the PKCS#12 object could not be encrypted
    
    Since:
    
    9.0
  - encrypt
```
public void encrypt(char[] password,
                    AlgorithmID algorithm)
             throws PKCSException
```
    Uses the provided password and algorithm to encrypt the content of this PKCS#12 object. If the algorithm indicated is PBES2, the KeyBag containing the private key is also encrypted using the same algorithm; otherwise, the KeyBag containing the private key is encrypted with a 168 bit TripleDES in CBC mode, and the certificates are encrypted with the passed in Algorithm, which can be one of 168 bit TripleDES, 40 bit RC2 or 56 bit DES with MD5.
    
    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
    
    Throws:
    
    PKCSException
  - 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"));
 
```
    Throws:
    
    java.io.IOException
  - skipUnsupportedSafeBags
```
public void skipUnsupportedSafeBags(boolean skipUnsupportedSafeBags)
```
    Call this method to set the behaviour when an unsupported SafeBag type is encountered when decoding. When set to true (the default), any unsupported SafeBag types are skipped. When set to false, any unsupported SafeBag will cause a CodingException to be thrown.
    To be effective, this method must be called before decrypt(char[]).
    
    Parameters:
    
    skipUnsupportedSafeBags - whether or not to skip unsupported SafeBag types when parsing.
    
    Since:
    
    Entrust 7.0
  - 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

Class PKCS12

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PUBLIC_KEY_INTEGRITY_MODE

PASSWORD_INTEGRITY_MODE

authenticated_safes

mode

Constructor Detail

PKCS12

PKCS12

PKCS12

PKCS12

PKCS12

PKCS12

Method Detail

decode

decrypt

getAuthenticatedSafes

getKeyBag

getCertificateBags

verify

encrypt

encrypt

encrypt

encrypt

toASN1Object

writeTo

skipUnsupportedSafeBags

toString