iaik.cms
Class DataStream

java.lang.Object
  extended by 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.
 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.
 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 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 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

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