iaik.cms
Class DataStream

java.lang.Object
  iaik.cms.DataStream

All Implemented Interfaces:

ContentStream

Direct Known Subclasses:

Data

public class DataStream
extends java.lang.Object
implements ContentStream

This class represents the stream-implementation of the CMS content type Data.

Each CMS content type is associated with a specific object identifier, derived from:

 pkcs-7 OBJECT IDENTIFIER ::=
   { iso(1) member-body(2) US(840) rsadsi(113549)
       pkcs(1) 7 }
 

The object identifier for the Data content type is defined as:

data OBJECT IDENTIFIER ::= { pkcs-7 1 }

which corresponds to the OID string "1.2.840.113549.1.7.1".

The Cryptographic Message Syntax (CMS) (RFC 5652) specifies the Data content type as base type without any cryptographic enhancements. Please note that in difference to PKCS#7, CMS specifies the Data as arbitrary octet strings, such as ASCII text files; the interpretation is left to the application. From this point of view the CMS type Data itself does not have an ASN.1 respresentation in contrast to its PKCS#7 equivalent where Data is defined as ASN.1 OCTET STRING:

Data ::= OCTET STRING

This class only may be used for compatibility to PKCS#7 for allowing to include Data(Stream) objects into ContentInfo(Stream)s. Within SignedData or EnvelopedData objects the internal content always is wrapped by an EncapsulatedContentInfo object. Since an EncapsulatedContentInfo anytime is encoded as OCTET STRING backwards compatibility to PKCS#7 is preserved even when the inner content type is Data

Use the DataStream(InputStream is, int blockSize) constructor to create a new DataStream object for the given raw data supplying input stream:

 InputStream input_stream = ...;
 int blockSize = ...;
 DataStream data_stream = new DataStream(InputStream, blockSize);
 

If blockSize is set to a positive value, the data is BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length:

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

However, if blockSize is not positive, whole the data is encoded as one single primitive definite octet string, which may cause a memory overflow when dealing with large data volumes (consult the documentation of the ContentStream class for more information about the difference between the two encoding schemes).

In contrast to the non-stream variant of the CMS Data type (implemented by the Data class), where the raw data is supplied as byte array and therefore can be accessed arbitrarily often, it is important to keep in mind that now for the DataStream class, the raw data carrying input stream only can be read once, which shall not be done before actually performing the encoding (again, see ContentStream)!

After writing a DataStream object BER encoded to an output stream by calling the writeTo method, it may be read back, decoded and re-parsed again by means of the DataStream(InputStream is) constructor. In this case, the getInputStream method may be used for reading the raw data included in the received DataStream object.

See Also:

ContentStream, ContentInfoStream

Field Summary

protected int	blockSize_ The block size for block encoding.
protected java.io.InputStream	inputStream_ The data carrying input stream.

Constructor Summary

protected	DataStream() Default constructor for dynamic object creation in ContentInfoStream.
	DataStream(java.io.InputStream is) Creates a new DataStream from a BER encoded Data object which is read from the given InputStream.
	DataStream(java.io.InputStream is, int blockSize) Creates a new CMS Data from an InputStream supplying the raw content data.

Method Summary

void	decode(java.io.InputStream is) Reads and decodes the BER encoded Data from an input stream.
int	getBlockSize() Gets the block size defining the length of each definite primitive encoded octet string component.
iaik.asn1.ObjectID	getContentType() Returns the object identifier of this CMS Data.
java.io.InputStream	getInputStream() Returns an InputStream where the contents of this object can be read.
void	setBlockSize(int blockSize) Sets the block size for defining the length of each definite primitive encoded octet string component.
iaik.asn1.ASN1Object	toASN1Object() Returns this CMS Data as ASN1Object.
java.lang.String	toString() Returns a string giving some information about this DataStream object.
java.lang.String	toString(boolean detailed) Returns a string giving some - if requested - detailed information about this DataStream object.
void	writeTo(java.io.OutputStream os) Writes this CMS DataStream object BER encoded to the given output stream.

Methods inherited from class java.lang.Object

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

Field Detail

inputStream_

protected java.io.InputStream inputStream_

The data carrying input stream.

blockSize_

protected int blockSize_

The block size for block encoding. (Default: 2048 to enforce indefinite constructed encoding).

Constructor Detail

DataStream

protected DataStream()

Default constructor for dynamic object creation in ContentInfoStream. Shall be not used by an application. The block size is set to 2048 to enforce indefinite constructed encoding.

DataStream

public DataStream(java.io.InputStream is,
                  int blockSize)

Creates a new CMS Data from an InputStream supplying the raw content data. If blockSize is set to a positive value, the data will be BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length:

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

Parameters:

is - the stream containing the content

blockSize - the block size defining the length of each primitive definite encoded octet string component; or not splitting the encoding, when being not positive

DataStream

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

Creates a new DataStream from a BER encoded Data object which is read from the given InputStream. The encoded Data may (or may not) be wrapped into a ContentInfo. Do not use this constructor for supplying the content value. This constructor may be used for decoding and parsing an already exisiting DataStream object, supplied as BER encoded input stream that may have been created by calling writeTo.

Use the DataStream(InputStream is, int blockSize) constructor for supplying the content data when creating a DataStream 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

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

Reads and decodes the BER encoded Data from an input stream. The encoded Data may (or may not) be wrapped into a ContentInfo.

Specified by:

decode in interface ContentStream

Parameters:

is - the InputStream holding a BER encoded CMS Data 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

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.

Specified by:

setBlockSize in interface ContentStream

Parameters:

blockSize - for defining the encoding scheme and setting the octet string component length, 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 Data into a ContentInfo.

Specified by:

getBlockSize in interface ContentStream

Returns:

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

getContentType

public iaik.asn1.ObjectID getContentType()

Returns the object identifier of this CMS Data.

Specified by:

getContentType in interface ContentStream

Returns:

ObjectID.cms_data

getInputStream

public java.io.InputStream getInputStream()

Returns an InputStream where the contents of this object can be read. Attention! The stream only may be read once.

When having created a new DataStream 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 DataStream object coming from some stream, this method may be used for reading the raw data.

Returns:

an InputStream with the contents of this object

toASN1Object

public iaik.asn1.ASN1Object toASN1Object()
                                  throws CMSException

Returns this CMS Data as ASN1Object. From the internal value an ASN.1 OCTET STRING object is created. If block size has a value > 0 a constructed OCTET STRING is created.

Specified by:

toASN1Object in interface ContentStream

Returns:

this Data as ASN1Object

Throws:

CMSException - if the ASN1Object could not be created

writeTo

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

Writes this CMS DataStream object BER encoded to the given output stream. From the internal value an ASN.1 OCTET STRING object is created, BER encoded and written to the stream. If block size has a value > 0 a constructed OCTET STRING is created. In this case the encoding is splitted according to the defined block size:

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

If the block size is not positive, whole the data is encoded as one single primitive definite octet string:

 0x04 <length> <data>
 

Parameters:

os - the output stream to which to encode the data

Throws:

java.io.IOException - if an error occurs during encoding to the stream

toString

public java.lang.String toString()

Returns a string giving some information about this DataStream 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 DataStream object.

Specified by:

toString in interface ContentStream

Parameters:

detailed - - whether or not to give detailed information

Returns:

the string representation