iaik.pkcs.pkcs7

Class DataStream

java.lang.Object

iaik.pkcs.pkcs7.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 PKCS#7 content type Data.

Each PKCS#7 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.1.113549.1.7.1".

PKCS#7 specifies the Data content type as base type without any cryptographic enhancements:

Data ::= OCTET STRING

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 PKCS#7 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.

Version:

File Revision 20

See Also:

ContentStream, ContentInfoStream, OCTET_STRING

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataStream() Default constructor for dynamic object creation in ContentInfo.
	DataStream(java.io.InputStream is) Creates a new PKCS#7 data from a BER encoded InputStream.
	DataStream(java.io.InputStream is, int blockSize) Creates a new PKCS#7 Data from an InputStream supplying the raw content data.

Method Summary

Modifier and Type	Method and Description
void	decode(java.io.InputStream is) Reads and decodes the Data from a DerInputStream.
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 PKCS#7 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 PKCS#7 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 PKCS#7 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

Constructor Detail

DataStream

protected DataStream()

Default constructor for dynamic object creation in ContentInfo. The block size is set to 2048.

DataStream

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

Creates a new PKCS#7 Data from an InputStream supplying the raw content data. If the value of blockSize is smaller or equal to zero, the data will be DER encoded as primitive definite OCTET STRING when writing it to a stream by means of the writeTo method. However, 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 initiating an entire primitive definite encoding, when being not positive

See Also:

OCTET_STRING

DataStream

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

Creates a new PKCS#7 data from a BER encoded InputStream. Do not use this constructor for supplying the content value. This constructor may be used for decoding and parsing an already existing 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

PKCSParsingException - if an error occurs while parsing the object

Method Detail

decode

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

Reads and decodes the Data from a DerInputStream. If the supplied InputStream actually is not an instance of DerInputStream, internally a DerInputStream is created before parsing the data.

Specified by:

decode in interface ContentStream

Parameters:

is - the InputStream holding a DER encoded PKCS#7 Data object

Throws:

java.io.IOException - if an I/O error occurs during reading from the InputStream

PKCSParsingException - if an error occurs while parsing the object

See Also:

DerInputStream

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

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. This method may be used for enforcing block encoding when wrapping the EncryptedData into a ContentInfo.

Specified by:

getBlockSize in interface ContentStream

Returns:

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

See Also:

OCTET_STRING

getContentType

public ObjectID getContentType()

Returns the object identifier of this PKCS#7 Data.

Specified by:

getContentType in interface ContentStream

Returns:

ObjectID.pkcs7_data

See Also:

ObjectID

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 PKCSException

Returns this PKCS#7 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:

PKCSException - if the ASN1Object could not be created

See Also:

OCTET_STRING

writeTo

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

Writes this PKCS#7 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:

PKCSException - if an encoding error occurs

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

See Also:

OCTET_STRING

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