iaik.pkcs.pkcs7
Interface ContentStream

All Known Subinterfaces:

Content

All Known Implementing Classes:

DataStream, DigestedDataStream, EncryptedDataStream, SignedDataStream, EnvelopedDataStream, SignedAndEnvelopedDataStream

public interface ContentStream

The interface for the stream implementations of the PKCS#7 content types.

The stream support has been included into the iaik.pkcs.pkcs7 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 defines the base Data content type of the PKCS#7 Cryptographic Message Standard:

 Data ::= OCTET STRING
 

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.pkcs.pkcs7 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 PKCS#7 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 PKCS#7 content types. Since any non-stream supporting class of the IAIK-JCE PKCS#7 package implements the Content interface, which itself inherits from this ContenStream interface, all non-stream supporting classes of the PKCS#7 package implement the abstract methods of this interface, too. Within the IAIK-JCE PKCS#7 package, this interface is implemented for all six content types specified by PKCS#7, Version 1.5:

• Data (stream implementation by DataStream)
• SignedData (stream implementation by SignedDataStream)
• EnvelopedData (stream implementation by EnvelopedDataStream)
• SignedAndEnvelopedData (stream implementation by SignedAndEnvelopedDataStream)
• DigestedData (stream implementation by DigestedDataStream)
• EncryptedData (stream implementation by EncryptedDataStream)

Implementations of this interface do not represent the contentType field of the PKCS#7 ContentInfo structure. They represent the ASN.1 structures defined in the PKCS#7 specification for the several PKCS#7 content types. Implementations of this interface are instantiated for supplying values for the content field of the PKCS#7 ContentInfo structure. Each implemention shall implement the getContentType method allowing to query for the OID unequivocally identifying the implemented PKCS#7 content type. This OID value actually represents the value of the PKCS#7 ContentInfo contentType field:

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

 ContentType ::= OBJECT IDENTIFIER
 

Version:

File Revision 16

See Also:

ContentInfoStream, DataStream, SignedDataStream, EnvelopedDataStream, SignedAndEnvelopedDataStream, DigestedDataStream, EncryptedDataStream

Method Summary

void	decode(InputStream is) Decodes the DER encoded data of the implemented PKCS#7 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 PKCS#7 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 PKCS#7 content type as an ASN1Object.
String	toString(boolean detailed) Returns a string giving some - if requested - detailed information about the implemented PKCS#7 content type.

Method Detail

getContentType

public ObjectID getContentType()

Returns the OID of the implemented PKCS#7 content type.

Returns:

the content type object identifier

decode

public void decode(InputStream is)
            throws IOException,
                   PKCSParsingException

Decodes the DER encoded data of the implemented PKCS#7 content type, supplied from an input stream.

Parameters:

is - the DER encoded PKCS#7 content type as input stream

Throws:

IOException - if an error occurs while reading the stream

PKCSParsingException - if an error occurs during the decoding process

toASN1Object

public ASN1Object toASN1Object()
                        throws PKCSException

Returns the content value of the implemented PKCS#7 content type as an ASN1Object.

Returns:

the content value of the implemented PKCS#7 content type as ASN1Object

Throws:

PKCSException - if the ASN1Object could not be created

toString

public String toString(boolean detailed)

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

Parameters:

detailed - whether or not to give detailed information about the implemented PKCS#7 content type.

Returns:

the string representation

setBlockSize

public 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

See Also:

OCTET_STRING

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.

Returns:

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

See Also:

OCTET_STRING