iaik.cms
Class AuthEnvelopedDataOutputStream

java.lang.Object
  java.io.OutputStream
      iaik.cms.AuthEnvelopedDataOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable

public class AuthEnvelopedDataOutputStream
extends java.io.OutputStream

This is an OutputStream implementation of the AuthEnvelopedData structure as specified CMS.

This stream version will encode the authenticated encrypted content as a constructed OCTET STRING. Each write operation to this stream will result in an OCTET STRING block within this constructed OCTET STRING provided that the input data is at least as large as the block size of the employed (block) cipher. Calling close() will finish the authenticated encryption, i.e. it will do the padding (if required) and finish writing the resulting AuthEnvelopedData strucure.

The recipient infos must be added before the application starts writing data to this stream. RecipientInfo objects which are added later will not be included.

The typical usage of this class looks like the following example for creating a CMS AuthEnvelopedData structure and writing it to an output stream:

  // the certificate of the recipient
  X509Certificate recipientCert = ...
  // the input stream from which to read the data to be encrypted
  InputStream dataInputStream = ...
  // the output stream to which to write the AuthEnvelopedData
  OutputStream resultStream = ...
  
  // create enveloped data stream (in this sample we use AES-GCM as content-authenticated
  // encryption algorithm)
  AlgorithmID contentAuthEncAlg = (AlgorithmID)AlgorithmID.aes256_GCM.clone();
  AuthEnvelopedDataOutputStream authEnvelopingStream = 
    new AuthEnvelopedDataOutputStream(resultStream, contentAuthEncAlg);
  // use RSA for encrypting the content-authenticated encryption key  
  RecipientInfo recipientInfo = 
    new KeyTransRecipientInfo(recipientCert, (AlgorithmID)AlgorithmID.rsaEncryption.clone());
  authEnvelopingStream.addRecipientInfo(recipientInfo);
  ...
  // add any further recipients (if required)
  ...
  
  // write in the data to be authenticated encrypted
  byte[] buffer = new byte[2048];
  int bytesRead;
  while ((bytesRead = dataInputStream.read(buffer)) != -1) {
    authEnvelopingStream.write(buffer, 0, bytesRead);
  }
  // closing the stream finishes authenticated encryption and closes the underlying stream
  authEnvelopingStream.close();
 

If you want to encapsulate the AuthEnvelopedData into a ContentInfo you first must wrap a ContentInfoOutputStream around the final output stream (the ContentInfoOutputStream has to write its headers to the stream at first, thus it must be created at the "lowest" level):

  ContentInfoOutputStream contentInfoStream = 
    new ContentInfoOutputStream(ObjectID.cms_authEnvelopedData, resultStream);
  // now create AuthEnvelopedDataOutputStream for the ContentInfoStream:
  AuthEnvelopedDataOutputStream authEnvelopingStream = 
    new AuthEnvelopedDataOutputStream(contentInfoStream, contentAuthEncAlg);  
    
  // the further proceeding is same as above 
  RecipientInfo recipientInfo = 
    new KeyTransRecipientInfo(recipientCert, (AlgorithmID)AlgorithmID.rsaEncryption.clone());
  authEnvelopingStream.addRecipientInfo(recipientInfo);
  
  // write in the data to be authenticated encrypted
  byte[] buffer = new byte[2048];
  int bytesRead;
  while ((bytesRead = dataInputStream.read(buffer)) != -1) {
    authEnvelopingStream.write(buffer, 0, bytesRead);
  }
  // closing the stream finishes authenticated encryption and closes the underlying stream
  authEnvelopingStream.close();  
 

Use class AuthEnvelopedDataStream to read in and parse the encoded AuthEnvelopedData and decrypt the content.

Note: RFC 5084 specifies the usage of the AuthEnvelopedData type for the AES-CCM and AES-GCM authenticated encryption algorithms, both are supported by this implementation when used with IAIK-JCE, version > 3.17. AES-CCM needs to know the size of the to-be-auth-encrypted content in advance when creating an AuthEnvelopedData object. If you know to data input length (e.g. the size of a data file) you may set it by calling method setInputLength, otherwise tha data has to be internally buffered before starting the authentication-encryption process.
RFC 8103 specifies the AuthEnvelopedData content type for use with the ChaCha20-Poly1305 authenticated encryption algorithm (RFC 7539). ChaCha20-Poly1305 for CMS requires IAIK-JCE version 5.62 or later.

See Also:

RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo, PasswordRecipientInfo, OtherRecipientInfo, AuthEnvelopedDataStream

Constructor Summary

AuthEnvelopedDataOutputStream(ObjectID contentType, java.io.OutputStream out, AlgorithmID contentAuthEncAlg)
Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g.

AuthEnvelopedDataOutputStream(ObjectID contentType, java.io.OutputStream out, AlgorithmID contentAuthEncAlg, int keyLength)
Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g.

AuthEnvelopedDataOutputStream(ObjectID contentType, java.io.OutputStream out, AlgorithmID contentAuthEncAlg, int keyLength, SecurityProvider securityProvider)
Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g.

AuthEnvelopedDataOutputStream(java.io.OutputStream out, AlgorithmID contentAuthEncAlg)
Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g.

AuthEnvelopedDataOutputStream(java.io.OutputStream out, AlgorithmID contentAuthEncAlg, int keyLength)
Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g.

Method Summary

void	addRecipientInfo(RecipientInfo recipient) Adds one recipient to the list of recipient infos.
void	close() Finishes the encoding and writes any authenticated and unauthenticated attributes (if set) and the mac value to the underlying stream.
void	flush() Flushes any internal data and calls flush of the underlying stream.
SecurityProvider	getSecurityProvider() Gets the SecurityProvider installed for this EncryptedDataStream.
int	getVersion() Returns the syntax version number.
boolean	isPassThroughClose() Checks whether a call to close() will call close of the underlying output stream
void	setAuthenticatedAttributes(Attribute[] attributes) Sets a set of authenticated attributes.
void	setInputLength(long inputLength) Sets the length of input data.
void	setOriginatorInfo(OriginatorInfo originatorInfo) Sets the optional OriginatorInfo.
void	setPassThroughClose(boolean passThroughClose) Setting this to true will cause close() to call close of the underlying output stream.
void	setRecipientInfos(RecipientInfo[] recipients) Sets the recipient infos.
void	setSecurityProvider(SecurityProvider securityProvider) Sets the SecurityProvider for this AuthEnvelopedDataOutputStream.
void	setUnauthenticatedAttributes(Attribute[] attributes) Sets a set of unauthenticated attributes.
java.lang.String	toString() Returns a string giving some information about this EnvelopedData object.
java.lang.String	toString(boolean detailed) Returns a string giving some - if requested - detailed information about this AuthEnvelopedData object.
void	write(byte[] b) Authenticated encrypts, encodes and writes the given data to the output stream.
void	write(byte[] b, int off, int len) Authenticated encrypts, encodes and writes the given data to the output stream.
void	write(int b) Authenticated encrypts, encodes and writes the given data byte to the output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

AuthEnvelopedDataOutputStream

public AuthEnvelopedDataOutputStream(java.io.OutputStream out,
                                     AlgorithmID contentAuthEncAlg)

Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g. write(byte[])).

The content type is set to CMS Data.

When using this constructor, automatically a temporary symmetric key for authenticated content encryption will be generated. If using a content-authenticated encryption algorithm allowing keys of different size, you may specify the key length by using the AuthEnvelopedDataOutputStream(OutputStream, AlgorithmID, int) constructor.
Note that the supplied contentAuthEncAlg AlgorithmID internally is cloned.

Parameters:

out - the OutputStream receiving the authenticated enveloped data

contentAuthEncAlg - the content-authenticated encryption algorithm for authenticatedencrypting the content

AuthEnvelopedDataOutputStream

public AuthEnvelopedDataOutputStream(ObjectID contentType,
                                     java.io.OutputStream out,
                                     AlgorithmID contentAuthEncAlg)

Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g. write(byte[])).

When using this constructor, automatically a temporary symmetric key for authenticated content encryption is generated. If using a content-authenticated encryption algorithm allowing keys of different size, you may specify the key length by using the AuthEnvelopedDataOutputStream(ObjectID, OutputStream, AlgorithmID, int) constructor.
Note that the supplied contentAuthEncAlg AlgorithmID internally is cloned.

Parameters:

contentType - the content type of the content to be enveloped

out - the OutputStream receiving the authenticated enveloped data

contentAuthEncAlg - the content-authenticated encryption algorithm for authenticated encrypting the content

AuthEnvelopedDataOutputStream

public AuthEnvelopedDataOutputStream(java.io.OutputStream out,
                                     AlgorithmID contentAuthEncAlg,
                                     int keyLength)

Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g. write(byte[])).
The content type is set to CMS Data.

When using this constructor, automatically a symmetric key for authenticated content encryption is generated. If the specified content-authenticated 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.
Note that the supplied contentAuthEncAlg AlgorithmID internally is cloned.

Parameters:

out - the OutputStream receiving the authenticated enveloped data

contentAuthEncAlg - the content-authenticated encryption algorithm for authenticated encrypting the content

keyLength - the length of the content-authenticated-encryption key to be generated (when using a content-authenticated-encryption algorithm that supports variable key lengths)

AuthEnvelopedDataOutputStream

public AuthEnvelopedDataOutputStream(ObjectID contentType,
                                     java.io.OutputStream out,
                                     AlgorithmID contentAuthEncAlg,
                                     int keyLength)

Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g. write(byte[])).

When using this constructor, automatically a symmetric key for authenticated content encryption is generated. If the specified content-authenticated 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. constructor may be used.
Note that the supplied contentAuthEncAlg AlgorithmID internally is cloned.

Parameters:

contentType - the content type of the content to be authenticated enveloped

out - the OutputStream receiving the authenticated enveloped data

contentAuthEncAlg - the content-authenticated encryption algorithm for authenticated encrypting the content

keyLength - the length of the content-authenticated-encryption key to be generated (when using a content-authenticated-encryption algorithm that supports variable key lengths)

AuthEnvelopedDataOutputStream

public AuthEnvelopedDataOutputStream(ObjectID contentType,
                                     java.io.OutputStream out,
                                     AlgorithmID contentAuthEncAlg,
                                     int keyLength,
                                     SecurityProvider securityProvider)

Creates a new AuthEnvelopedDataOutputStream object where the content to be authenticated enveloped is later written to the given output stream (e.g. write(byte[])).

When using this constructor, automatically a symmetric key for authenticated content encryption is generated. If the specified content-authenticated 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.
Note that the supplied contentAuthEncAlg AlgorithmID is cloned internally.

Parameters:

contentType - the content type of the content to be authenticated enveloped

out - the OutputStream receiving the authenticated enveloped data

contentAuthEncAlg - the content-authenticated encryption algorithm for authenticated encrypting the content

keyLength - the length of the content-authenticated-encryption key to be generated (when using a content-authenticated-encryption algorithm that supports variable key lengths)

securityProvider - the security provider to be used; if null the default system-wide SecurityProvider is used

Method Detail

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Authenticated encrypts, encodes and writes the given data to the output stream.

Overrides:

write in class java.io.OutputStream

Parameters:

b - The data to be encrypted

off - The start offset in b.

len - The number of bytes to write.

Throws:

java.io.IOException - If an I/O error occurs.

write

public void write(byte[] b)
           throws java.io.IOException

Authenticated encrypts, encodes and writes the given data to the output stream.

Overrides:

write in class java.io.OutputStream

Parameters:

b - The data to be encrypted.

Throws:

java.io.IOException - If an I/O error occurs.

write

public void write(int b)
           throws java.io.IOException

Authenticated encrypts, encodes and writes the given data byte to the output stream.

Specified by:

write in class java.io.OutputStream

Parameters:

b - The data byte to be encrypted.

Throws:

java.io.IOException - If an I/O error occurs.

flush

public void flush()
           throws java.io.IOException

Flushes any internal data and calls flush of the underlying stream.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

java.io.IOException - If flushing the stream fails.

close

public void close()
           throws java.io.IOException

Finishes the encoding and writes any authenticated and unauthenticated attributes (if set) and the mac value to the underlying stream.

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.OutputStream

Throws:

java.io.IOException - if an I/O error occurs when writing to the stream

isPassThroughClose

public boolean isPassThroughClose()

Checks whether a call to close() will call close of the underlying output stream

Returns:

true if a call to close() will call close of the underlying output stream; false if a call to close() will not close the underlying stream.

setPassThroughClose

public void setPassThroughClose(boolean passThroughClose)

Setting this to true will cause close() to call close of the underlying output stream. If false, a call to close() will not close the underlying stream.

Parameters:

passThroughClose - true to pass through close() calls. false to not pass them through.

setSecurityProvider

public void setSecurityProvider(SecurityProvider securityProvider)

Sets the SecurityProvider for this AuthEnvelopedDataOutputStream.

This method allows to explicitly set a SecurityProvider for this AuthEnvelopedDataOutputStream. If no explicit SecurityProvider is set, the default system wide installed SecurityProvider will be used for the required cryptographic operations.

This class uses the following method(s) of the SecurityProvider, which may be overriden by an application, if required:

• getAuthCipherEngine to get an AuthCipher engine for authenticated encrypting the content
• generateKey to generate the symmetric content-authenticated encryption key

Parameters:

securityProvider - the SecurityProvider to be set

getSecurityProvider

public SecurityProvider getSecurityProvider()

Gets the SecurityProvider installed for this EncryptedDataStream.

This class uses the following method(s) of the SecurityProvider, which may be overriden by an application, if required:

• getAuthCipherEngine to get an AuthCipher engine for authenticated encrypting the content
• generateKey to generate the symmetric content-authenticated encryption key

If no explicit SecurityProvider has been set for this object, the default system wide installed SecurityProvider will be used for the required cryptographic operations. However, this method will return null if it does not have its own SecurityProvider.

Returns:

the SecurityProvider explicitly installed for this object, or null if this object does not have its own SecurityProvider

setOriginatorInfo

public void setOriginatorInfo(OriginatorInfo originatorInfo)

Sets the optional OriginatorInfo.

The originatorInfo may be set for including certificates and/or certificate revocation lists for the originator if required by the key management algorithm used.

Parameters:

originatorInfo - the OriginatorInfo to be set

setRecipientInfos

public void setRecipientInfos(RecipientInfo[] recipients)

Sets the recipient infos.

Any RecipientInfo added supplies recipient-specific information used for identifying the key of the recipient to be used for authenticated en/decrypting the content.

Parameters:

recipients - a collection of per-recipient information

See Also:

RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo, PasswordRecipientInfo, OtherRecipientInfo

addRecipientInfo

public void addRecipientInfo(RecipientInfo recipient)

Adds one recipient to the list of recipient infos.

Any RecipientInfo added supplies recipient-specific information used for identifying the key of the recipient to be used for authenticated en/decrypting the content.

Parameters:

recipient - the RecipientInfo to be added

See Also:

RecipientInfo, KeyTransRecipientInfo, KeyAgreeRecipientInfo, KEKRecipientInfo, PasswordRecipientInfo, OtherRecipientInfo

setAuthenticatedAttributes

public void setAuthenticatedAttributes(Attribute[] attributes)

Sets a set of authenticated attributes. These attributed will be authenticated only, but not encrypted.

Parameters:

attributes - the authenticated attributes to be set

setUnauthenticatedAttributes

public void setUnauthenticatedAttributes(Attribute[] attributes)

Sets a set of unauthenticated attributes. These attributed will be neither authenticated nor encrypted.

Parameters:

attributes - the unauthenticated attributes to be set

setInputLength

public void setInputLength(long inputLength)
                    throws java.lang.IllegalArgumentException

Sets the length of input data. The input data length may be required for stream-processing CCM which needs to know the data input length in advance.

Parameters:

inputLength - the length (number of bytes) of the input data

Throws:

java.lang.IllegalArgumentException - if the specified input length is not valid

getVersion

public int getVersion()

Returns the syntax version number.

Returns:

the syntax version number

toString

public java.lang.String toString()

Returns a string giving some information about this EnvelopedData object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation

toString

public java.lang.String toString(boolean detailed)

Returns a string giving some - if requested - detailed information about this AuthEnvelopedData object.

Parameters:

detailed - - whether or not to give detailed information

Returns:

the string representation