iaik.cms

Class EncryptedContentInfoStream

java.lang.Object

iaik.cms.EncryptedContentInfoStream

Direct Known Subclasses:

EncryptedContentInfo

public class EncryptedContentInfoStream
extends java.lang.Object

This class represents the stream-supporting implementation of the CMS type EncryptedContentInfo.

The CMS Cryptographic Message Syntax (RFC 2630) defines the EncryptedContentInfo type for specifying the content type, the content encryption algorithm and the encrypted content of an EnvelopedData, or EncryptedData structure:

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

 EncryptedContent ::= OCTET STRING
 

This class provides several constructors and methods for creating an EncryptedContentInfoStream, 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 CMS content type implementations - provides mechanims for encoding the inherent encrypted content data as indefinite constructed 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 for properly handling large amounts of data, or/and 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 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 writeTo method, e.g.:

 //create a EncryptedContentInfoStream for the data to be encrypted, supplied from an input stream:
 InputStream dataStream = ...;
 EncryptedContentInfoStream eci = new EncryptedContentInfoStream(ObjectID.cms_data, dataStream);
 //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);
 //perform the content encryption and encode the EncryptedContentInfo to an output stream
 eci.writeTo(output_stream);
 

Note: in contrast to the equivalent non-stream supporting EncryptedContentInfo class, where the content encryption already is performed when calling a proper setupCipher method, this class performs the content encryption actually during the encoding by piping the data through a cipher stream when executing the writeTo method. The corresponding setupCipher method only initializes the cipher for the cipher stream pipe.

In the same way, when parsing an already existing EncryptedContentInfoStream object a proper setupCipher method has to be used for initializing the cipher stream pipe for decryption. The decryption actually is performed when reading the data previously obtained by means of the getInputstream method:

 //create an EncryptedContentInfoStream from the input stream supplying the encoding:
 EncryptedContentInfoStream eci = new EncryptedContentInfoStream(encoded_stream);
 //setup the cipher for decryption using the right secret key:
 eci.setupCipher(key);
 //get and read the data thereby actually performing the decryption
 InputStream data_is = signed_data.getInputStream();
 byte[] buf = new byte[1024];
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 }
 

See Also:

EnvelopedDataStream, EncryptedDataStream

Field Summary

Fields

Modifier and Type	Field and Description
protected int	blockSize_ The block size.
protected javax.crypto.Cipher	cipher_ The Cipher engine used for en/decryption.
protected AlgorithmID	contentEncryptionAlgorithm_ The content-encryption algorithm
protected ObjectID	contentType_ The type of the content.
protected java.io.InputStream	inputStream_ The data carrying input stream.
protected SecurityProvider	securityProvider_ The SeucrityProvider used for cryptographic tasks.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EncryptedContentInfoStream() Default constructor.
	EncryptedContentInfoStream(java.io.InputStream is) Creates a new EncryptedContentInfoStream where the BER encoded data is read from the given InputStream.
	EncryptedContentInfoStream(ObjectID contentType, AlgorithmID contentEncAlg) Creates an EncryptedContentInfoStream with given content type and content-encryption algorithm ID.
	EncryptedContentInfoStream(ObjectID contentType, java.io.InputStream is) Creates a new EncryptedContentInfoStream for the given content type where the content data to be encrypted is read from the provided InputStream.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	decode(java.io.InputStream is) Reads and decodes an encoded EncryptedContentInfoStream from an input stream.
int	getBlockSize() Gets the block size defining the length of each definite primitive encoded octet string component.
AlgorithmID	getContentEncryptionAlgorithm() Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContentInfoStream.
ObjectID	getContentType() Returns the type of the content encrypted by this EncryptedContentInfoStream.
java.io.InputStream	getInputStream() Returns an InputStream for reading the decrypted content.
boolean	hasContent() Returns true if there is a content.
void	setBlockSize(int blockSize) Sets the block size for encoding the encrypted content.
javax.crypto.SecretKey	setupCipher(AlgorithmID contentEA) Setups the cipher and generates a secret key for encrypting the content.
javax.crypto.SecretKey	setupCipher(AlgorithmID contentEA, int keyLength) Setups the cipher and generates a secret key for encrypting the content.
void	setupCipher(AlgorithmID contentEA, java.security.Key key, java.security.AlgorithmParameters params) Setups the cipher for encrypting the content.
void	setupCipher(AlgorithmID contentEA, java.security.Key key, java.security.spec.AlgorithmParameterSpec params) Setups the cipher for encrypting the content.
void	setupCipher(java.security.Key key) Uses the specified content-encryption key to setup the cipher for decrypting the content.
void	setupCipher(java.security.Key key, java.security.AlgorithmParameters params) Uses the specified key and paramters to setup the cipher for decrypting the content.
void	setupCipher(java.security.Key key, java.security.spec.AlgorithmParameterSpec params) Uses the specified key and paramters to setup the cipher for decrypting the content.
ASN1Object	toASN1Object() Returns this EncryptedContentInfoStream as ASN1Object.
java.lang.String	toString() Returns a string giving some information about this EncryptedContentInfoStream object.
void	writeTo(java.io.OutputStream os) Writes the BER encoding of this object to the given OutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

contentType_

protected ObjectID contentType_

The type of the content.

contentEncryptionAlgorithm_

protected AlgorithmID contentEncryptionAlgorithm_

The content-encryption algorithm

inputStream_

protected java.io.InputStream inputStream_

The data carrying input stream.

cipher_

protected javax.crypto.Cipher cipher_

The Cipher engine used for en/decryption.

blockSize_

protected int blockSize_

The block size.

securityProvider_

protected SecurityProvider securityProvider_

The SeucrityProvider used for cryptographic tasks.

Constructor Detail

EncryptedContentInfoStream

protected EncryptedContentInfoStream()

Default constructor.

EncryptedContentInfoStream

public EncryptedContentInfoStream(ObjectID contentType,
                          java.io.InputStream is)

Creates a new EncryptedContentInfoStream for the given content type where the content data to be encrypted is read from the provided InputStream.

Parameters:

contentType - the CMS content type

is - the input stream holding the content data to encrypt

EncryptedContentInfoStream

public EncryptedContentInfoStream(ObjectID contentType,
                          AlgorithmID contentEncAlg)

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

Parameters:

contentType - the type of the encrypted content

contentEncAlg - the algorithm used to encrypt the content

EncryptedContentInfoStream

public EncryptedContentInfoStream(java.io.InputStream is)
                           throws java.io.IOException,
                                  CMSParsingException

Creates a new EncryptedContentInfoStream where the BER encoded data is read from the given InputStream.

The given input stream supplies the BER encoding of an already exisiting EncryptedContentInfoStream object that may have been created by calling writeTo.

Use the EncryptedContentInfoStream(ObjectID contentType, InputStream is) constructor for supplying the content to be encrypted when creating an EncryptedContentInfoStream object.

Parameters:

is - the InputStream holding a BER encoded EncryptedContentInfoStream object

Throws:

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

CMSParsingException - if an error occurs while parsing the object

Method Detail

decode

protected void decode(java.io.InputStream is)
               throws java.io.IOException,
                      CMSParsingException

Reads and decodes an encoded EncryptedContentInfoStream from an input stream.

Parameters:

is - the InputStream holding a BER encoded EncryptedContentInfoStream object

Throws:

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

CMSParsingException - if an error occurs while parsing the object

setupCipher

public void setupCipher(AlgorithmID contentEA,
               java.security.Key key,
               java.security.AlgorithmParameters params)
                 throws java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException,
                        java.security.InvalidAlgorithmParameterException

Setups the cipher for encrypting the content.

If parameters are specified they are set for the given content encryption algorithm. This method creates a cipher for the specified content-encryption algorithm and initializes it with given key and parameters. The content encryption actually is performed during the encoding when writing this EncyrptedContentInfo to a stream by calling the writeTo method. So it is important to setup the cipher before writing to the stream!

Note: This method internaly creates a clone of the supplied AlgorithmID. If parameters are supplied they are used for initializing the Cipher engine. After initializing the Cipher engine, method Cipher.getParameters() is called to get (back) the parameters the Cipher has been initialized with (respectively the Cipher has created itsself) for including them into the AlgorithmID to be sent to the recipient. This may override any parameters that have been included in the AlgorithmID by the user. So, if you have included parameters in the AlgorithmID, take care to supply them as params for initializing the Cipher, too. If params is null, the Cipher will create and use (and send in the AlgorithmID) its own parameters.

Parameters:

contentEA - the algorithm to use for encrypting the content

key - the key to use

params - the parameters to initialize the cipher

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm

java.security.InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

java.security.InvalidAlgorithmParameterException - if the provided parameters are not appropriate for the algorithm

setupCipher

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

Setups the cipher for encrypting the content. If parameters are specified they are set for the given content encryption algorithm. This method creates a cipher for the specified content-encryption algorithm and initializes it with given key and parameters. The content encryption actually is performed during the encoding when writing this EncyrptedContentInfo to a stream by calling the writeTo method. So it is important to setup the cipher before writing to the stream!

Note: This method internaly creates a clone of the supplied AlgorithmID. If parameters are supplied they are used for initializing the Cipher engine. After initializing the Cipher engine, method Cipher.getParameters() is called to get (back) the parameters the Cipher has been initialized with (respectively the Cipher has created itsself) for including them into the AlgorithmID to be sent to the recipient. This may override any parameters that have been included in the AlgorithmID by the user. So, if you have included parameters in the AlgorithmID, take care to supply them as params for initializing the Cipher, too. If params is null, the Cipher will create and use (and send in the AlgorithmID) its own parameters.

Parameters:

contentEA - the algorithm to use for encrypting the content

key - the key to use

params - the parameters to initialize the cipher

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm

java.security.InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

java.security.InvalidAlgorithmParameterException - if the provided parameters are not appropriate for the algorithm

setupCipher

public javax.crypto.SecretKey setupCipher(AlgorithmID contentEA)
                                   throws java.security.NoSuchAlgorithmException

Setups the cipher and generates a secret key for encrypting the content.

This method creates a cipher for the specified content-encryption algorithm and initializes it with a newly generated secret key. The content encryption actually is performed during the encoding when writing this EncyrptedContentInfo to a stream by calling the writeTo method. So it is important to setup the cipher before writing to the stream!

Attention! This method only shall be used for cipher setup if the secret key to be generated has a predefined length or default setting, since no key length parameter is offered. For generating a Key of specific length to be used for encrypting the content call method {#setupCipher(AlgorithmID, int) setupCipher(AlgorithmID contentEA, int keyLength)}.

Note: This method internaly creates a clone of the supplied AlgorithmID.

Parameters:

contentEA - the algorithm to use for encrypting the content

Returns:

the new symmetric key for encrypting the content

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm

setupCipher

public javax.crypto.SecretKey setupCipher(AlgorithmID contentEA,
                                 int keyLength)
                                   throws java.security.NoSuchAlgorithmException

Setups the cipher and generates a secret key for encrypting the content.

If the specified content encryption algorithm supports variable key lengths, a particular key length may be set by means of the keyLength parameter. If no length is specified, the defined default key length will be used. If the algorithm only works with keys of fixed-size length, the keyLength parameter may be set to -1 or the setupCipher(AlgorithmID) method may be used.

This method creates a cipher for the specified content-encryption algorithm and initializes it with the newly generated secret key. The content encryption actually is performed during the encoding when writing this EncyrptedContentInfo to a stream by calling the writeTo method. So it is important to setup the cipher before writing to the stream!

Parameters:

contentEA - the algorithm to use for encrypting the content

keyLength - the key length that may be set when using a content encryption algorithm that supports variable key lengths

Returns:

the new symmetric key for encrypting the content

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for the specified algorithm

setupCipher

public void setupCipher(java.security.Key key,
               java.security.spec.AlgorithmParameterSpec params)
                 throws java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException,
                        java.security.InvalidAlgorithmParameterException

Uses the specified key and paramters to setup the cipher for decrypting the content.

The decryption actually is performed when subsequently getting and reading the content by means of the getInputStream method. So the content should not be read before setting up the cipher!

Parameters:

key - the (secret) key to decrypt the content

params - the algorithm parameters needed to decrypt the content

Throws:

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

java.security.InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

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

setupCipher

public void setupCipher(java.security.Key key,
               java.security.AlgorithmParameters params)
                 throws java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException,
                        java.security.InvalidAlgorithmParameterException

Uses the specified key and paramters to setup the cipher for decrypting the content.

The decryption actually is performed when subsequently getting and reading the content by means of the getInputStream method. So the content should not be read before setting up the cipher!

Parameters:

key - the (secret) key to decrypt the content

params - the algorithm parameters needed to decrypt the content

Throws:

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

java.security.InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

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

setupCipher

public void setupCipher(java.security.Key key)
                 throws java.security.NoSuchAlgorithmException,
                        java.security.InvalidKeyException,
                        CMSException

Uses the specified content-encryption key to setup the cipher for decrypting the content.

The decryption actually is performed when subsequently getting and reading the content by means of the getInputStream method. So the content should not be read before setting up the cipher!

Parameters:

key - the (secret) key to decrypt the content

Throws:

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

java.security.InvalidKeyException - if the key is inappropriate for the content-encryption algorithm

CMSException - if the algorithm parameter cannot be retrieved from the algorithm

setBlockSize

public void setBlockSize(int blockSize)

Sets the block size for encoding the encrypted content. If blockSize is positive, 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
 

If blockSize is not positive, whole the encrypted content is encoded as definite primitive octet string when calling the writeTo method:

  0x04 <length> <encrypted content>
 

Parameters:

blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive

getBlockSize

public int getBlockSize()

Gets the block size defining the length of each definite primitive encoded octet string component.

If the value of blockSize is smaller or equal to zero the whole data is encoded as definite primitive octet string. This method may be used for enforcing block encoding when wrapping the EncryptedData into a ContentInfo.

Returns:

blockSize defining the encoding scheme and setting the octet string component length, if positive

toASN1Object

public ASN1Object toASN1Object()
                        throws CMSException

Returns this EncryptedContentInfoStream as ASN1Object.

Returns:

this EncryptedContentInfoStream as ASN1Object.

Throws:

CMSException

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException,
                    CMSException

Writes the BER encoding of this object to the given OutputStream.

When encoding the content data to the given stream it is piped through a cipher stream thereby performing the content encryption.

If the setBlockSize method 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>
 

Parameters:

os - the OutputStream to which the encoding shall be written to

Throws:

java.io.IOException - if an I/O error occurs during writing to the OutputStream

CMSException - if an error occurs while encoding the object

getContentType

public ObjectID getContentType()

Returns the type of the content encrypted by this EncryptedContentInfoStream.

Returns:

the content type

getContentEncryptionAlgorithm

public AlgorithmID getContentEncryptionAlgorithm()

Returns the content-encryption algorithm (including any associated parameters) of this EncryptedContentInfoStream.

Returns:

the content-encryption AlgorithmID

getInputStream

public java.io.InputStream getInputStream()

Returns an InputStream for reading the decrypted content. Attention! The stream only may be read once.

When having created a new EncryptedContentInfoStream object to be encoded to a stream, this method should not be utilized at all, since the stream automatically will be read during performing the encoding (which is done when calling the writeTo method).
When having decoded and parsed a received EncryptedContentInfoStream object coming from some stream, this method may be used for obtaining the raw (decrypted) data after having done the cipher setup.

Returns:

an InputStream for reading the content data

hasContent

public boolean hasContent()

Returns true if there is a content.

Returns:

true if there is a content

toString

public java.lang.String toString()

Returns a string giving some information about this EncryptedContentInfoStream object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation