iaik.pkcs.pkcs7
Class EncryptedContentInfo

java.lang.Object
  |
  +--iaik.pkcs.pkcs7.EncryptedContentInfoStream
        |
        +--iaik.pkcs.pkcs7.EncryptedContentInfo

public class EncryptedContentInfo

extends EncryptedContentInfoStream

This class implements the PKCS#7 EncryptedContentInfo type.

The PKCS#7 Cryptographic Message Standard defines the EncryptedContentInfo type for specifying the content type, the content encryption algorithm and the encrypted content of an EnvelopedData, SignedAndEnvelopedData, or EncryptedData structure (Version 1.5)::

 EncryptedContentInfo ::= SEQUENCE {
   contentType                 ContentType,
   contentEncryptionAlgorithm  ContentEncryptionAlgorithmIdentifier,
   encryptedContent            [0] IMPLICIT EncryptedContent OPTIONAL }
 

 EncryptedContent ::= OCTET STRING
 

This class provides several constructors and methods for creating an EncryptedContentInfo, encrypting its content (thereby optionally creating a secret content-encryption key in accordance with the specified content-encryption algorithm), and "re-decrypting" the encrypted content again.

This class - as in common with all IAIK-JCE PKCS#7 implementations - provides mechanims for encoding the inherent encrypted content data as indefinite primitive octet string instead of using the default primitive definite encoding scheme:

 0x24 0x80
           0x04 <blocksize> <first encrypted content block>
           0x04 <blocksize> <second encrypted content block>
           0x04 <blocksize> <third encrypted content block>
                ...
 0x00 0x00
 

instead of:

 0x04 <length> <encrypted content>
 

The indefinte constrcuted encoding scheme may be preferable when intending to be compatible to the encoding practice of some particular application (for instance some versions of Netscape Navigator).
For enabling an indefinte constructed encoding of the inherent encrypted content, the setBlockSize method of the parent EncryptedContentInfoStream class has to be used for defining the length of each primitive definite encoded octet string component before actually performing the encoding by means of the getEncoded method, e.g.:

 //create a EncryptedContentInfo for the data to be encrypted, supplied as byte array:
 byte[] data = ...;
 EncryptedContentInfo eci = new EncryptedContentInfo(ObjectID.pkcs7_data, data);
 //generate secret key and set up the cipher for encryption:
 SecretKey key = eci.setupCipher(AlgorithmID.des_EDE3_CBC);
 //optionally set the block size for splitting the encoding:
 eci.setBlockSize(1024);
 //transform the EncryptedContentInfo into an ASN1Object or immediately
 //perform the DER encoding:
 ASN1Object obj = eci.toASN1Object(); //respectively: byte[]encoding = eci.getEncoded();
 

Note: in contrast to the equivalent stream supporting EncryptedContentInfoStream parent class, where the setupCipher method only initializes the cipher and the content encryption actually is done during the encoding by piping the data through a cipher stream, in this class whole the content encryption already is performed inside the setupCipher method.

When parsing an already existing EncryptedContentInfo object a proper setupCipher method has to be used for initializing the cipher and decrypting the encrypted content:

 //create an EncryptedContentInfo from the given EncryptedContentInfo ASN1Object:
 //(if the EncryptedContentInfo is supplied as DER encoding first decode it to an ASN1Objet)
 ASN1Object obj = DerCoder.decode(encoding);
 EncryptedContentInfo eci = new EncryptedContentInfo(obj);
 //setup the cipher with the right secret key and decrypt the encrypted content:
 eci.setupCipher(key);
 //get the recovered raw data:
 byte[] data = eci.getContent();
 

Version:

File Revision 36

See Also:

EnvelopedData, SignedAndEnvelopedData, EncryptedData, EncryptedContentInfoStream

Constructor Summary

protected	EncryptedContentInfo() Default constructor.
	EncryptedContentInfo(ASN1Object obj) Creates an EncryptedContentInfo from an ASN1Object.
	EncryptedContentInfo(InputStream is) Creates a new EncryptedContentInfo where the DER encoded data is read from the given InputStream.
	EncryptedContentInfo(ObjectID contentType, AlgorithmID contentEncAlg) Creates an EncryptedContentInfo with given content type and content-encryption algorithm ID.
	EncryptedContentInfo(ObjectID contentType, byte[] content) Creates a new EncryptedContentInfo for the given content type.

Method Summary

void	decode(ASN1Object obj) Decodes the EncryptedContentInfo supplied as ASN1Object.
protected void	decode(InputStream is) Reads and decodes the EncryptedContentInfo from a DerInputStream.
byte[]	getContent() Returns the content.
byte[]	getEncoded() Returns the DER encoding of this EncryptedContentInfo in a byte array.
InputStream	getInputStream() Returns an InputStream for reading the content.
boolean	hasContent() Returns true if there is a content.
void	setupCipher(AlgorithmID contentEA, Key key, AlgorithmParameterSpec params) Setups the cipher and encrypts the content.
void	setupCipher(Key key, AlgorithmParameterSpec params) Uses the specified key and paramters for setting up the cipher and decrypting the content.
void	setVersion(int version) Sets the version of this EncryptedContentInfo.
ASN1Object	toASN1Object() Returns this EncryptedContentInfo as ASN1Object.

Methods inherited from class iaik.pkcs.pkcs7.EncryptedContentInfoStream

getBlockSize, getContentEncryptionAlgorithm, getContentType, setBlockSize, setupCipher, setupCipher, setupCipher, toString, writeTo

Methods inherited from class java.lang.Object

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

Constructor Detail

EncryptedContentInfo

protected EncryptedContentInfo()

Default constructor. The block size is set to -1 meaning that the data will be encoded a one simple octet string by deafult.

EncryptedContentInfo

public EncryptedContentInfo(ObjectID contentType,
                            byte[] content)

Creates a new EncryptedContentInfo for the given content type. The content data to be encrypted is supplied as a byte array.

Parameters:

contentType - the PKCS#7 content type

content - the byte array holding the content data to encrypt

EncryptedContentInfo

public EncryptedContentInfo(ObjectID contentType,
                            AlgorithmID contentEncAlg)

Creates an EncryptedContentInfo with given content type and content-encryption algorithm ID. The encrypted data must be supplied by other means.

Parameters:

contentType - the PKCS#7 content type of the encrypted content

contentEncAlg - the algorithm used to encrypt the content

EncryptedContentInfo

public EncryptedContentInfo(ASN1Object obj)
                     throws PKCSParsingException

Creates an EncryptedContentInfo from an ASN1Object. The ASN1Object supplied to this constructor represents an already exisiting EncryptedContentInfo object that may have been created by calling toASN1Object.

Use the EncryptedContentInfo(ObjectID contentType, byte[] content) constructor for supplying the content to be encrypted when creating an EncryptedContentInfo object.

Parameters:

obj - the ASN1Object of ASN.1 type EncryptedContentInfo

Throws:

PKCSParsingException - if the ASN.1 object could not be parsed

EncryptedContentInfo

public EncryptedContentInfo(InputStream is)
                     throws IOException,
                            PKCSParsingException

Creates a new EncryptedContentInfo where the DER encoded data is read from the given InputStream.

Parameters:

is - the InputStream holding a DER encoded PKCS#7 EncryptedContentInfo object

Throws:

IOException - if an I/O error occurs during reading from the InputStream

PKCSParsingException - if an error occurs while parsing the object

Method Detail

decode

public void decode(ASN1Object obj)
            throws PKCSParsingException

Decodes the EncryptedContentInfo supplied as ASN1Object.

Parameters:

obj - the PKCS#7 EncryptedContentInfo as ASN1Object

Throws:

PKCSParsingException - if an error occurs while parsing the object

decode

protected void decode(InputStream is)
               throws IOException,
                      PKCSParsingException

Reads and decodes the EncryptedContentInfo from a DerInputStream. If the supplied InputStream actually is not an instance of DerInputStream, internally a DerInputStream is created before parsing the data.

Overrides:

decode in class EncryptedContentInfoStream

Parameters:

is - the InputStream holding a DER encoded PKCS#7 EncryptedContentInfo object

Throws:

IOException - if an I/O error occurs during reading from the InputStream

PKCSParsingException - if an error occurs while parsing the object

setupCipher

public void setupCipher(AlgorithmID contentEA,
                        Key key,
                        AlgorithmParameterSpec params)
                 throws NoSuchAlgorithmException,
                        InvalidKeyException,
                        InvalidAlgorithmParameterException

Setups the cipher and encrypts the content. If IV parameters are specified they are set for the given content encryption algorithm.
In contrast to the same-name method of the parent EncryptedContentInfoStream class, where the cipher only is initialized, in this class this method already performs the content encryption.

Note: The supplied parameters are used for initializing the cipher. They may, for instance, constitute a initialization vector of type IvParameterSpec. In such cases, if the supplied contentEA algorithmID does not include parameters, an OCTET_STRING is created from the iv value and set as parameters for the contentEA algorithmID. However, if the contentEA algorithmID expects parameters of other ASN.1 representation than an OCTET_STRING constituting the IV, an application itself should take care for setting the parameters before supplying the algorithmID to this method. Imagine, for instance, RC2-CBC as used by S/MIME, where the parameters are encoded as SEQUENCE with two components having the OCTET_STRING iV as second component (see RFC 2311):

 RC2-CBC parameter ::=  SEQUENCE {
    rc2ParameterVersion  INTEGER,
    iv                   OCTET STRING (8)}
 

In such case an application may:

• Create the parameters
• Create a SEQUENCE with the IV in its second component
• Set the parameters (SEQUENCE) for the contentEA algorithmID
• Supply the contentEA and the iV parameters (as IvParameterSpec) to this setupCipher method

Overrides:

setupCipher in class EncryptedContentInfoStream

Parameters:

contentEA - the algorithm to use for encrypting the content

key - the key to use

params - the parameters for the specified algorithm

Throws:

NoSuchAlgorithmException - if there is no implementation for the specified algorithm

InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

InvalidAlgorithmParameterException - if the provided parameters are not appropriate for the algorithm

setupCipher

public void setupCipher(Key key,
                        AlgorithmParameterSpec params)
                 throws NoSuchAlgorithmException,
                        InvalidKeyException,
                        InvalidAlgorithmParameterException

Uses the specified key and paramters for setting up the cipher and decrypting the content. In contrast to the same-name method of the parent EncryptedContentInfoStream class, where the cipher only is initialized, in this class this method already decrypts the encrypted content.

This method shall be used for initializing the cipher of an received EncryptedContentInfo object with key and parameters for decrypting the encrypted content, particularly when the parameters of the content encryption algorithmID do not constitute an OCTET_STRING that represents IV parameters. The following example parses PBE parameters from the algorithmID, and subsequently setups the cipher with key and derived parameters:

 //get the content encryption algorithm:
 AlgorithmID contentEA = eci.getContentEncryptionAlgorithm();
 //get PBE parameters
 SEQUENCE seq = (SEQUENCE)contentEA.getParameter;
 OCTET_STRING oct = (OCTET_STRING)seq.getComponentAt(0);
 byte[] salt = (byte[])oct.getValue();
 INTEGER iteration_count = (INTEGER)seq.getComponentAt(1);
 int it = ((BigInteger)iteration_count.getValue()).intValue();
 PBEParameterSpec params = new PBEParameterSpec(salt, it);
 //now setup the cipher
 eci.setupCipher(pbeKey, params);
 // get the content
 byte[] content = eci.getContent();
 

This method may be used for setting up the cipher for an v1.6 EnvelopedData message, where the version number (1) indicates that the content encoding has been encrypted.

Overrides:

setupCipher in class EncryptedContentInfoStream

Parameters:

key - the (secret) key to decrypt the content

params - the algorithm parameters needed to decrypt the content

version - the version; either 0 or 1

Throws:

NoSuchAlgorithmException - if there is no implementation for the content-encryption-algorithm to be used

InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

InvalidAlgorithmParameterException - if the provided parameters are not appropriate for the created cipher

setVersion

public void setVersion(int version)

Sets the version of this EncryptedContentInfo.

Also an EncryptedContentInfo itself does not have a version number, when expilitly creating an EncryptedContentInfo for an EnvelopedData it might be necessary to decide whether to encrypt the content for a PKCS#7v1.5 EnvelopedData (default) or for a PKCS#7v1.6 EnvelopedData (the latter encrypting the content encoding).

The version number set by this method either may be 0 (indicating a PKCS#7v1.5 EnvelopedData) or 1 (indicating a PKCS#71.6 EnvelopedData); default is 0.

Parameters:

version - the version; either 0 or 1

toASN1Object

public ASN1Object toASN1Object()
                        throws PKCSException

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

Overrides:

toASN1Object in class EncryptedContentInfoStream

Returns:

this EncryptedContentInfo as ASN1Object.

getContent

public byte[] getContent()

Returns the content.

The returned content depends on whether creating a new EncryptedContentInfo or parsing an existing one:

• When creating a new EncryptedContentInfo:
  If the content yet has not been encrypted, the plain content is returned
• When parsing an existing EncryptedContentInfo:
  If the content yet has not been decrypted, the encryptet content is returned

Returns:

a byte array holding the content or null if there is no content

getInputStream

public InputStream getInputStream()

Returns an InputStream for reading the content.

The returned content depends on whether creating a new EncryptedContentInfo or parsing an existing one:

• When creating a new EncryptedContentInfo:
  If the content yet has not been encrypted, the plain content is returned
• When parsing an existing EncryptedContentInfo:
  If the content yet has not been decrypted, the encryptet content is returned

This method only overrides the corresponding getInputStream method of the parent EncryptedContentInfoStream class for returning the content of this EncryptedContentInfo object. There should be no real necessity for using this method since the content immediately can be obtained by the getContent method. However, in contrast to the equivalent getInputStream method of the parent EncryptedContentInfoStream class, this method may be called arbitrarly often; it only returns a ByteArrayInputStream that is initialized with the content bytes.

Overrides:

getInputStream in class EncryptedContentInfoStream

Returns:

an InputStream holding the content or null if there is no content

hasContent

public boolean hasContent()

Returns true if there is a content.

Overrides:

hasContent in class EncryptedContentInfoStream

Returns:

true if there is a content

getEncoded

public byte[] getEncoded()
                  throws PKCSException

Returns the DER encoding of this EncryptedContentInfo in a byte array.

If the setBlockSize method of the parent EncryptedContentInfoStream class has been utilized for defining a positive blockSize value, the encrypted content is encoded as indefinite constructed octet string being composed of a certain number of definite primitive encoded octet strings of blockSize length:

 0x24 0x80
           0x04 <blocksize> <first encrypted content block>
           0x04 <blocksize> <second encrypted content block>
           0x04 <blocksize> <third encrypted content block>
                ...
 0x00 0x00
 

Otherwise, whole the encrypted content is encoded as definite primitive octet string:

  0x04 <length> <encrypted content>
 

Returns:

a byte array holding the DER encoding of this EncryptedContentInfo