iaik.cms
Interface ContentStream

All Known Subinterfaces:

Content

All Known Implementing Classes:

AuthenticatedData, AuthenticatedDataStream, AuthEnvelopedData, AuthEnvelopedDataStream, CompressedData, CompressedDataStream, Data, DataStream, DigestedData, DigestedDataStream, EncryptedData, EncryptedDataStream, EnvelopedData, EnvelopedDataStream, JMailSMimeSigned, Receipt, SignedData, SignedDataInOutStream, SignedDataStream, SMimeAuthEncrypted, SMimeEncrypted, SMimeSigned

public interface ContentStream

The interface for the stream implementations of the CMS content types.

The stream support has been included into the iaik.cms package for providing an utility to handle large amounts of data which cannot be processed properly within the memory "as a whole". The idea behind the stream interface comes from the possibility of using the indefinite constructed method for BER encoding an OCTET_STRING instead of encoding it definite primitive. Remember that the ASN.1 type OCTET_STRING is used for encoding the content of an inherent EncapsulatedContentInfo object ( RFC 5652):

 EncapsulatedContentInfo ::= SEQUENCE {
      eContentType ContentType,
      eContent [0] EXPLICIT OCTET STRING OPTIONAL }

 ContentType ::= OBJECT IDENTIFIER

 

Generally, if the length of the raw data to be encoded is known in advance the definite primitive method is used for DER encoding an octet string. In this way, the encoding is initialized by the primitive octet string identifier tag 0x04, followed by the length encoding, and concluded by the data bytes:

 0x04 <length> <data>
 

Consider, for example the five data bytes 0x01 0xAB 0x23 0x7F 0xCA and their primitive definite encoding to:

 0x04 0x05 0x01 0xAB 0x23 0x7F 0xCA
 

However, this method may not be suitable for large data volumes when the data length is not known in advance. Since an octet string is not allowed to be indefinite primitive encoded (how to distinguish EOC octets from two adjacent 0x00 0x00 data bytes?), a BER encoding variant has to be used where whole the octet string is encoded as indefinite constructed octet string, being composed of a certain number of rather small primitive definite encoded octet string components. The length of each primitive component shall be set to a predefined blocksize:

 0x24 0x80
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
                ...
 0x00 0x00
 

Of course, the last block may be shorter than the defined blocksize!
So, the example from above may be encoded as:

 0x24 0x80
           0x04 0x02 0x01 0xAB
           0x04 0x02 0x23 0x7F
           0x04 0x01 0xCA
 0x00 0x00 
 

In this way, the general encoding procedure for the stream supporting classes of the iaik.cms package can be summarized as follows:

• the data is read from the input stream not before the encoding actually is performed
• during the encoding the data is read from the input stream block by block according to a predefined block size; immediately when reading a block it is definite primitive encoded - and, if necessary, processed according to the specific requirements of the actual CMS object - and written to the encoding output stream, which previously has been initialized for the data encoding by writing the constructed indefinite identifier and length tags 0x24 0x80
• after actually processing the last data block the encoding output stream is closed by writing the EOC tags 0x00 0x00

This procedure makes it possible to limit the data volumes actually processed within the memory to a reasonable small size!

This interface supplies some abstract methods that have to be implemented by any class that represents the stream implementation of one of the several CMS content types. Since any non-stream supporting class of the IAIK-CMS package implements the Content interface, which itself inherits from this ContenStream interface, all non-stream supporting classes of the CMS package implement the abstract methods of this interface, too. Within the IAIK-CMS package, this interface is implemented for all six content types specified by CMS (RFC 5652), and for the CompressedData type ( RFC 3274):

• Data (stream implementation by DataStream)
• SignedData (stream implementation by SignedDataStream)
• EnvelopedData (stream implementation by EnvelopedDataStream)
• DigestedData (stream implementation by DigestedDataStream)
• EncryptedData (stream implementation by EncryptedDataStream)
• AuthenticatedData (stream implementation by AuthenticatedDataStream)
• CompressedData (stream implementation by CompressedDataStream)

Implementations of this interface do not represent the contentType field of the CMS ContentInfo structure. They represent the ASN.1 structures defined by the Cryptographic Message Syntax (CMS) (RFC 5652) for the several CMS content types. Implementations of this interface are instantiated for supplying values for the content field of the CMS ContentInfostructure. Each implementation shall implement the getContentType method allowing to query for the OID unequivocally identifying the implemented CMS content type. This OID value actually represents the value of the CMS ContentInfo contentType field:

 ContentInfo ::= SEQUENCE {
    contentType ContentType,
    content
      [0] EXPLICIT ANY DEFINED BY contentType }
 

 ContentType ::= OBJECT IDENTIFIER
 

See Also:

ContentInfoStream, DataStream, SignedDataStream, EnvelopedDataStream, DigestedDataStream, EncryptedDataStream, AuthenticatedDataStream, CompressedDataStream

Method Summary

void	decode(java.io.InputStream is) Decodes the BER encoded data of the implemented CMS content type, supplied from an input stream.
int	getBlockSize() Gets the block size defining the length of each definite primitive encoded octet string component.
ObjectID	getContentType() Returns the OID of the implemented CMS content type.
void	setBlockSize(int blockSize) Sets the block size for defining the length of each definite primitive encoded octet string component.
ASN1Object	toASN1Object() Returns the content value of the implemented CMS content type as an ASN1Object.
java.lang.String	toString(boolean detailed) Returns a string giving some - if requested - detailed information about the implemented CMS content type.

Method Detail

getContentType

ObjectID getContentType()

Returns the OID of the implemented CMS content type.

Returns:

the content type object identifier

decode

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

Decodes the BER encoded data of the implemented CMS content type, supplied from an input stream.

Parameters:

is - the BER encoded CMS content type as input stream

Throws:

java.io.IOException - if an error occurs while reading the stream

CMSParsingException - if an error occurs during the decoding process

toASN1Object

ASN1Object toASN1Object()
                        throws CMSException

Returns the content value of the implemented CMS content type as an ASN1Object.

Returns:

the content value of the implemented CMS content type as ASN1Object

Throws:

CMSException - if the ASN1Object could not be created

toString

java.lang.String toString(boolean detailed)

Returns a string giving some - if requested - detailed information about the implemented CMS content type.

Parameters:

detailed - whether or not to give detailed information about the implemented CMS content type.

Returns:

the string representation

setBlockSize

void setBlockSize(int blockSize)

Sets the block size for 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.

Parameters:

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

getBlockSize

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.

Returns:

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