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, 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:

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):

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 implemention 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

This Javadoc may contain text parts from text parts from IETF Internet Standard specifications (see copyright note).

IAIK-CMS 5.1, (c) 2002 IAIK, (c) 2003 - 2010 SIC