codec.pkcs12
Class PFX

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--java.util.ArrayList
                    |
                    +--codec.asn1.ASN1AbstractCollection
                          |
                          +--codec.asn1.ASN1Sequence
                                |
                                +--codec.pkcs12.PFX

All Implemented Interfaces:

ASN1Collection, ASN1Type, Cloneable, Collection, Externalizable, List, Serializable

public class PFX

extends ASN1Sequence

implements Serializable

This class represents a PFX as defined in PKCS#12. The ASN.1 definition of this structure is

  PFX ::= SEQUENCE {
   version     INTEGER{v3(3)}(v3,...),
   authSafe    ContentInfo,
   macData     MacData OPTIONAL
 }
 MacData ::= SEQUENCE {
   mac         DigestInfo,
   macSalt     OCTET STRING,
   iterations  INTEGER DEFAULT 1
   --NOTE: The default is for historical reasons and its use is deprecated.
           A higher value like 1024 is recommended.
 

PFX The PFX is the outer integrity wrapper of a PDU.

To create a PKCS#12 file that can be read by Netscape or Internet Explorer, do the following:

 PrivateKey priv = ...;
 PublicKey pub = ...;
 X509Certificate cert = ...;
 char[] password = ...; // this password protects both privacy and integrity
 PFX myPFX = new PFX( priv, cert, null, password, "My Certificate", null);
 DEREncoder enc = new DEREncoder(new FileOutputStream("myCert.p12"));
 myPFX.encode(enc);
 enc.close(); 
 

Version:

"$Id: PFX.java,v 1.2 2004/08/12 14:50:20 pebinger Exp $"

Author:

Michele Boivin

See Also:

Serialized Form

Field Summary

protected ContentInfo	authSafe_ The actual content of this structure.
protected int	INTEGRITY_MODE_ holds the current integrity mode
static int	INTEGRITY_MODE_NONE for PFX with no integrity mode
static int	INTEGRITY_MODE_PASSWORD for PFX protected in password integrity mode
static int	INTEGRITY_MODE_PUBLIC_KEY for PFX protected in public key integrity mode
protected MacData	macData_ The mac data that protects the integrity of the PFX in password-based-integrity- mode.
protected static ASN1Integer	version_ The PFX Version Number.

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

PFX()
This constructor builds the tree of ASN.1 objects used for decoding this structure.

PFX(AuthenticatedSafe authSafe)
This constructor creates a PFX without integrity protection.

PFX(AuthenticatedSafe authSafe, char[] pwd)
This constructor takes an authenticated safe and creates a PFX PDU that is protected through password-integrity-mode.

PFX(AuthenticatedSafe authSafe, PrivateKey pk, X509Certificate cert, String sigAlgName, AlgorithmParameters params)
This constructor takes an authenticated safe and creates a PFX PDU that is protected by public-key-integrity-mode.

PFX(PrivateKey pr_key, X509Certificate cert, X509Certificate[] chain, char[] pin, String user_fn, byte[] lk_id)
This constructor is for the convenient use of a PFX PDU for PKCS#12 files that can be imported by Netscape or Internet Explorer.

Method Summary

boolean	checkIntegrity(char[] pwd) verifies the the Hmac of this PFX if INTEGRITY_MODE_PASSWORD was used.
X509Certificate	checkIntegrity(X509Certificate cert) verifies the signature of the AuthenticatedSafe if INTEGRITY_MODE_PUBLIC_KEY was used.
void	decode(Decoder dec) Decodes this structure.
AuthenticatedSafe	getAuthSafe() This method returns the AuthenticatedSafe structure inside this PFX PDU
int	getIntegrityMode() Returns the integrity protection mode.
ASN1Integer	getVersion() This method returns the version number of this structure.
String	toString() Returns a human-readable String representation of this object.

Methods inherited from class codec.asn1.ASN1Sequence

getTag

Methods inherited from class codec.asn1.ASN1AbstractCollection

checkConstraints, encode, getCollection, getConstraint, getTagClass, getValue, isExplicit, isOptional, isType, readExternal, setConstraint, setExplicit, setOptional, writeExternal

Methods inherited from class java.util.ArrayList

add, add, addAll, addAll, clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, removeRange, set, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, remove, removeAll, retainAll

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, remove, removeAll, retainAll, subList

Field Detail

version_

protected static ASN1Integer version_

The PFX Version Number.

authSafe_

protected ContentInfo authSafe_

The actual content of this structure.

macData_

protected MacData macData_

The mac data that protects the integrity of the PFX in password-based-integrity- mode.

INTEGRITY_MODE_NONE

public static final int INTEGRITY_MODE_NONE

for PFX with no integrity mode

INTEGRITY_MODE_PASSWORD

public static final int INTEGRITY_MODE_PASSWORD

for PFX protected in password integrity mode

INTEGRITY_MODE_PUBLIC_KEY

public static final int INTEGRITY_MODE_PUBLIC_KEY

for PFX protected in public key integrity mode

INTEGRITY_MODE_

protected int INTEGRITY_MODE_

holds the current integrity mode

Constructor Detail

PFX

public PFX()

This constructor builds the tree of ASN.1 objects used for decoding this structure. This structure should be decoded using the DERDecoder of the asn1 package.

PFX

public PFX(AuthenticatedSafe authSafe)
    throws ASN1Exception

This constructor creates a PFX without integrity protection. Use of integrity protection is strongly encouraged!

Throws:

ASN1Exception - if the authSafe could not be encoded

PFX

public PFX(AuthenticatedSafe authSafe,
           char[] pwd)
    throws ASN1Exception,
           NoSuchAlgorithmException,
           InvalidKeySpecException,
           InvalidKeyException,
           InvalidAlgorithmParameterException

This constructor takes an authenticated safe and creates a PFX PDU that is protected through password-integrity-mode.

Parameters:

authSafe - The AuthenticatedSafe to be wrapped in a PFX PDU.

pwd - The password used to ensure the integrity of the PFX PDU.

Throws:

ASN1Exception - if the authSafe could not be encoded

NoSuchAlgorithmException - if the HMAC algorithms is not available

InvalidKeySpecException - if there was a problem with the HMAC

InvalidKeyException - if there was a problem with the HMAC

InvalidAlgorithmParameterException - if there was a problem with the HMAC

PFX

public PFX(AuthenticatedSafe authSafe,
           PrivateKey pk,
           X509Certificate cert,
           String sigAlgName,
           AlgorithmParameters params)
    throws SignatureException,
           GeneralSecurityException,
           ASN1Exception

This constructor takes an authenticated safe and creates a PFX PDU that is protected by public-key-integrity-mode. The pdu is protected by signing the authenticated safe.

Parameters:

authSafe - the authenticated safe that shall be secured in a pdu.

pk - the private key that is used to sign the pdu.

cert - the corresponding certificate to the private key.

sigAlgName - the signature algorithm name

params - the parameters needed for the signature algorithm. if no parameters are needed params should be null.

Throws:

SignatureException - if there was a problem with the signing of the PFX pdu

GeneralSecurityException - if some general problem with the signing occured

ASN1Exception - if the authSafe could not be encoded

PFX

public PFX(PrivateKey pr_key,
           X509Certificate cert,
           X509Certificate[] chain,
           char[] pin,
           String user_fn,
           byte[] lk_id)
    throws GeneralSecurityException,
           CertificateEncodingException,
           ASN1Exception

This constructor is for the convenient use of a PFX PDU for PKCS#12 files that can be imported by Netscape or Internet Explorer. It takes a private key, a certificate (optionally with a certificate chain) and a pin and creates a SafeContents for the key and the certificates. The private key will be password encrypted with the pin using PbeWithSHAAnd3_KeyTripleDES_CBC and saved in a PKCS8ShroudedKeyBag. The certificates are packed into certificate bags. The bags are saved in a password protected AuthenticatedSafe using PbeWithSHAAnd40BitRC2_CBC and the pin.

Parameters:

pr_key - the private key.

cert - The certificate corresponding to the private key

chain - The certificate chain up to the root CA (excluding the certificate passed in cert). If no chain is used, just pass null

pin - The password to encrypt and integrity-protect this PFX

user_fn - the user friendlyName attribute (can be null)

lk_id - the localKeyId attribute (can be null)

Throws:

GeneralSecurityException - if there was a general problem with the signature

CertificateEncodingException - if there was a problem with the certificate

ASN1Exception - if some ASN1 type could not be encoded properly

Method Detail

checkIntegrity

public boolean checkIntegrity(char[] pwd)
                       throws NoSuchAlgorithmException,
                              InvalidAlgorithmParameterException,
                              InvalidKeyException,
                              InvalidKeySpecException

verifies the the Hmac of this PFX if INTEGRITY_MODE_PASSWORD was used.

Parameters:

pwd - the password protecting the pdu

Returns:

true if the password integrity check was correct

Throws:

NoSuchAlgorithmException - if the HMAC algorithm is not available

InvalidAlgorithmParameterException - if there was a problem with the HMAC

InvalidKeyException - if there was a problem with the HMAC

InvalidKeySpecException - if there was a problem with the HMAC

IllegalStateException - if there this PFX is not protected by INTEGRITY_MODE_PASSWORD

checkIntegrity

public X509Certificate checkIntegrity(X509Certificate cert)
                               throws GeneralSecurityException

verifies the signature of the AuthenticatedSafe if INTEGRITY_MODE_PUBLIC_KEY was used.

Parameters:

cert - the certificate with the public-key to verify the signature on the AuthenticatedSafe.

Returns:

X509Certificate if signature is valid, null if not.

Throws:

GeneralSecurityException - if there was a problem with the signature

decode

public void decode(Decoder dec)
            throws ASN1Exception,
                   IOException

Decodes this structure. This structure should be decoded with a BERDecoder.

Overrides:

decode in class ASN1AbstractCollection

Following copied from class: codec.asn1.ASN1AbstractCollection

Parameters:

dec - The decoder to read from.

getAuthSafe

public AuthenticatedSafe getAuthSafe()
                              throws ASN1Exception,
                                     IllegalStateException

This method returns the AuthenticatedSafe structure inside this PFX PDU

Returns:

the AuthenticatedSafe structure

Throws:

IllegalStateException - if there were no data

ASN1Exception - if the authSafe could not proberly be decoded

getIntegrityMode

public int getIntegrityMode()

Returns the integrity protection mode. This can either be INTEGRITY_MODE_NONE, INTEGRITY_MODE_PASSWORD or INTEGRITY_MODE_PUBLIC_KEY

getVersion

public ASN1Integer getVersion()

This method returns the version number of this structure.

toString

public String toString()

Returns a human-readable String representation of this object.

Overrides:

toString in class ASN1AbstractCollection

Following copied from class: codec.asn1.ASN1AbstractCollection

Returns:

The string representation of this ASN.1 collection.