iaik.pkcs.pkcs12

Class AuthenticatedSafe

java.lang.Object

iaik.pkcs.pkcs12.AuthenticatedSafe

All Implemented Interfaces:

ASN1Type

public class AuthenticatedSafe
extends java.lang.Object
implements ASN1Type

This class implements the ASN.1 structure AuthenticatedSafe as defined in the PKCS#12 standard.

An AuthenticatedSafe object represents a PKCS#7 ContentInfo struture whose content type is either Data, EncryptedData, or EnvelopedData, depending on whether the supplied PKCS#12 SafeContents structure has to be ...

• ... left cryptographic "unprocessed" (mode UNENCRYPTED)
• ... password-based encrypted (mode PASSWORD_ENCRYPTED, password-privacy mode)
• ... public-key encrypted (mode PUBLIC_KEY_ENCRYPTED, public-key privacy mode)

This class does not support the public-key privacy mode!

The supplied SafeContents object consists of a sequence of SafaBags. A SafeBag represents one basic building block of a PFX PDU by collecting one particular piece of information (a key, a certificate, ...) together with some optional attributes. Currently, IAIK-JCE supports the three safe bag types keyBag, pkcs-8ShroudedKeyBag, and certBag.

All AuthenticatedSafe objects created as instances of this class are collected to form an AuthenticatedSafes object, which is DER encoded to give the content of a ContentInfo object of type Data. If password-integrity mode is chosen, the final PFX PDU is created by computing a SHA-1 HMAC on the contents of this Data object, but if public-key integrity mode is chosen, the Data from the previuos step is digitally signed by creating a SignedData ContentInfo structure:

 PFX ::= SEQUENCE {
   version     Version    -- V3(3) for this version.
   authSafes   ContentInfo,    -- from PKCS #7 v1.5
               -- SignedData in public-key integrity mode
               -- Data in password integrity mode
   macData     MacData OPTIONAL
               -- present only in password integrity mode
 }
 

For more information consult the PKCS#12 Personal Information Exchange Syntax Standard specification of the RSA Laboratories.

When creating a new AuthenticatedSafe object from a sequence of safe bags (constituting a SafeContents structure), you have to specify if the Data shall be left unencrypted, or if it shall be password-encrypted (remember that public-key privacy mode is not supported), e.g.:

 SafeBag[] safeBags = ...;
  ...
 AuthenticatedSafe authenticatedSafe = null;
 authenticatedSafe = new AuthenticatedSafe(AuthenticatedSafe.UNENCRYPTED, safeBags);
 

respectively:

 SafeBag[] safeBags = ...;
  ...
 AuthenticatedSafe authenticatedSafe = null;
 authenticatedSafe = new AuthenticatedSafe(AuthenticatedSafe.PASSWORD_ENCRYPTED, safeBags);
 

See Also:

SafeBag, PKCS12, iaik.pkcs.pkcs7.ContentInfo, iaik.pkcs.pkcs7.Data, iaik.pkcs.pkcs7.SignedData, iaik.pkcs.pkcs7.EnvelopedData, iaik.pkcs.pkcs7.EncryptedData

Field Summary

Fields

Modifier and Type	Field and Description
static int	PASSWORD_ENCRYPTED AuthenticatedSafe mode: PASSWORD_ENCRYPTED
static int	PUBLIC_KEY_ENCRYPTED AuthenticatedSafe mode: PUBLIC_KEY_ENCRYPTED (currently not supported)
static int	UNENCRYPTED AuthenticatedSafe mode: UNENCRYPTED

Constructor Summary

Constructors

Constructor and Description
AuthenticatedSafe(ASN1Object obj) Creates a new AuthenticatedSafe object from an ASN1Object.
AuthenticatedSafe(int mode, SafeBag[] safeBags) Creates a new AuthenticatedSafe containing the given SafeBags with the desired mode.

Method Summary

Methods

Modifier and Type	Method and Description
void	decode(ASN1Object obj) Decode and inits this AuthenticatedSafe from an ASN1Object.
void	decrypt(char[] password) Uses the given password for decrypting the password-based encryptet contents of this AuthenticatedSafe to recover the safe bags constituting this AuthenticatedSafe object.
void	encrypt(char[] password, AlgorithmID algorithm) Password-based encrypts the Data containing the sequence of safe bags included in this AuthenticatedSafe, if the PASSWORD_ENCRYPTED mode has been set when creating this AuthenticatedSafe object.
SafeBag[]	getSafeBags() Returns the SafeBags this AuthenticatedSafe contains.
void	skipUnsupportedSafeBags(boolean skipUnsupportedSafeBags) Call this method to set the behaviour when an unsupported SafeBag type is encountered when decoding.
ASN1Object	toASN1Object() Returns this AuthenticatedSafe as ASN1Object.
java.lang.String	toString() Returns a string giving some information about this AuthenticatedSafe object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNENCRYPTED

public static final int UNENCRYPTED

AuthenticatedSafe mode: UNENCRYPTED

See Also:

Constant Field Values

PASSWORD_ENCRYPTED

public static final int PASSWORD_ENCRYPTED

AuthenticatedSafe mode: PASSWORD_ENCRYPTED

See Also:

Constant Field Values

PUBLIC_KEY_ENCRYPTED

public static final int PUBLIC_KEY_ENCRYPTED

AuthenticatedSafe mode: PUBLIC_KEY_ENCRYPTED (currently not supported)

See Also:

Constant Field Values

Constructor Detail

AuthenticatedSafe

public AuthenticatedSafe(int mode,
                 SafeBag[] safeBags)
                  throws PKCSException

Creates a new AuthenticatedSafe containing the given SafeBags with the desired mode.

Depending on the specified privacy mode either a ContentInfo object of content type Data (mode UNENCRYPTED), or of content type EncryptedData is created from the supplied safe bags. The public-key privacy mode (PUBLIC_KEY_ENCRYPTED) currently is not supported.

Parameters:

asMode - the privacy mode (UNENCRYPTED, PASSWORD_ENCRYPTED, PUBLIC_KEY_ENCRYPTED)

safeBags - the safe contents as an Array of SafeBags

Throws:

PKCSException - if the AutenticatedSafe can not be created for some reason (e.g. some unknown or unsupported mode is requested)

AuthenticatedSafe

public AuthenticatedSafe(ASN1Object obj)
                  throws PKCSParsingException

Creates a new AuthenticatedSafe object from an ASN1Object.

Do not use this constructor for supplying safe bags and setting the privacy mode. This constructor may be used for parsing an already exisiting AuthenticatedSafe object, supplied as ASN1Object that may have been created by calling toASN1Object.

Use the AuthenticatedSafe(int asMode, SafeBag[] safeBags) constructor for supplying safe bags and setting privacy mode when creating an AuthenticatedSafe object.

Parameters:

obj - a AuthenticatedSafe as ASN1Object

Throws:

PKCSParsingException - if the object could not be parsed

Method Detail

decode

public void decode(ASN1Object obj)
            throws CodingException

Decode and inits this AuthenticatedSafe from an ASN1Object.

This method implements the ASN1Type interface and internally is called when creating a PKCS#12 AuthenticatedSafe object from an already existing AuthenticatedSafe object, supplied as ASN1Object:

Specified by:

decode in interface ASN1Type

Parameters:

obj - an AuthenticatedSafe as ASN1Object

Throws:

CodingException - if the object could not be parsed

toASN1Object

public ASN1Object toASN1Object()
                        throws CodingException

Returns this AuthenticatedSafe as ASN1Object.

The ASN1Object returned by this method may be used as parameter value when creating an AuthenticatedSafe object using the AuthenticatedSafe(ASN1Object obj) constructor.

Specified by:

toASN1Object in interface ASN1Type

Returns:

this AuthenticatedSafe as ASN1Object

Throws:

CodingException - if there occurs an error while creating the ASN1Object

encrypt

public void encrypt(char[] password,
           AlgorithmID algorithm)
             throws java.security.NoSuchAlgorithmException,
                    PKCSException

Password-based encrypts the Data containing the sequence of safe bags included in this AuthenticatedSafe, if the PASSWORD_ENCRYPTED mode has been set when creating this AuthenticatedSafe object.

The general proceeding is described in the PKCS#12 specification of the RSA Laboratories. From the safe bags supplied when creating this AuthenticatedSafe object, a PKCS#7 ContentInfo object of content type Data has been constructed, whose DER encoding is password-based encrypted when calling this method. Currently only the PbeWithSHAAnd40BitRC2_CBC or the PbeWithSHAAnd3_KeyTripleDES_CBC or the pbeWithMD5AndDES_CBC algorithm can be used for encrypting the Data, based on a PBEKeyBMP key which is created from the supplied password.

If the UNENCRYPTED mode has been set when creating this AuthenticatedSafe object, a call to this method would not have any effect; if the PUBLIC_KEY_ENCRYPTED mode has been set, calling this method would raise a RuntimeException, since the public-key privacy mode is not supported.

Parameters:

password - the password to encrypt the contents

algorithm - the PBE algorithm to be used for encryption; currently only the PbeWithSHAAnd40BitRC2_CBC or the PbeWithSHAAnd3_KeyTripleDES_CBC or the pbeWithMD5AndDES_CBC is supported

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation of the requested algorithm

PKCSException

See Also:

PBEKeyBMP

decrypt

public void decrypt(char[] password)
             throws PKCSException,
                    java.security.NoSuchAlgorithmException

Uses the given password for decrypting the password-based encryptet contents of this AuthenticatedSafe to recover the safe bags constituting this AuthenticatedSafe object.

Password based decryption only is performed, if the PASSWORD_ENCRYPTED privacy mode has been set when creating this AuthenticatedSafe object. If the UNENCRYPTED mode has been set, a call to this method would not have any effect; if the PUBLIC_KEY_ENCRYPTED mode has been set, calling this method would raise a RuntimeException, since the public-key privacy mode is not supported.

Parameters:

password - the password to decrypt the contents

Throws:

PKCSException - if there occurs an error while decrypting

java.security.NoSuchAlgorithmException - if there is no implementation of the encryption algorithm

getSafeBags

public SafeBag[] getSafeBags()

Returns the SafeBags this AuthenticatedSafe contains.

Returns:

the SafeBags this AuthenticatedSafe contains, as array of SafeBag

See Also:

SafeBag

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.

Currently supported SafeBag types are pkcs8ShroudedKeyBag, keyBag, and certificateBag.

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 AuthenticatedSafe object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation