iaik.cms
Class CompressedDataStream

java.lang.Object
  extended by iaik.cms.CompressedDataStream
All Implemented Interfaces:
ContentStream
Direct Known Subclasses:
CompressedData

public class CompressedDataStream
extends java.lang.Object
implements ContentStream

This class represents the stream supporting implementation of the CMS CompressedData type.

The compressed-data content type is identified by the following object identifier:

 id-ct-compressedData OBJECT IDENTIFIER ::= { iso(1) member-body(2)
       us(840) rsadsi(113549) pkcs(1) pkcs-9(9) smime(16) ct(1) 9 }
 

which corresponds to the OID string "1.2.840.113549.1.9.16.1.9".

The CompressedData type provides a syntax for compressing/decompressing the content of a CMS message. An algorithm identifier identifies the compression algorithm to be used ( RFC 3274 refers the ZLIB compression algorithm [RFC1950], [RFC1951]) for compressing the encapsulated content:

 CompressedData ::= SEQUENCE {
   version CMSVersion,
   compressionAlgorithm CompressionAlgorithmIdentifier,
   encapContentInfo EncapsulatedContentInfo
 }
 


When creating a CompressedDataStream object an application has to decide whether the compressed content shall be incldued (IMPLICIT mode) into the CompressedData message or shall be transmitted by other means (EXPLICIT mode):

 int mode = CompressedDataStream.IMPLICIT; // include content
 
or
 int mode = CompressedDataStream.EXPLICIT; // do not include content
 
However, in both cases the content data has to be supplied when creating the CompressedDataStream object to perform the compression with some particular compression algorithm, e.g.:
 // transmission mode (EXPLICIT or IMPLICIT)
 int mode = ...; 
 // the content data supplying input stream
 InputSrteam[] dataIs = ...; 
 // compression algorithm
 AlgorithmID compressionAlg = CMSAlgorithmID.zlib_compress;
 // create the CompressedDataStream object:
 CompressedDataStream compressedData = new CompressedDataStream(dataIs, compressionAlg, mode);
 
If the content shall not be included in the CompressedData object (EXPLICIT mode) now it is time to read away the content to transmit it by other means. While reading the content from the stream it is compressed by piping it through a InputStreamCompressEngine, e.g.:
 // in explicit mode get and read (and thereby) compress the content 
 if (mode == CompressedDataStream.EXPLICIT) {
   InputStream contentIs = compressedData.getInputStream();
   byte[] buf = new byte[1024];
   int r;
   while ((r = data_is.read(buf)) > 0) {
     // do something useful
   }  
 }
 
Finally method writeTo has to be called for BER encoding the CompressedDataStream object and writing it to an output stream. It is recommended to specify a positive block size value for splitting the data encoding:
 int blockSize = ...; 
 compressedData.writeTo(output_stream, blockSize);
 
respectively
 compressedData.writeTo(output_stream);
 
It is recommended only to use the writeTo method where a particular block size can be specified, because it is the intended purpose of this stream-supporting CompressedData implementation to handle large amounts of data. When no block size is specified the whole content data is encoded as one primitive definite octet string, which advantageously may be done when using the non-stream supporting CompressedData implementation. When a positve block size is specified for encoding the CompressedData to a stream, the content data is BER encoded as indefinite constructed octet string being composed of a series of definite primitive encoded octet strings of blockSize length, e.g.:
 0x24 0x80
           0x04 0x02 0x01 0xAB
           0x04 0x02 0x23 0x7F
           0x04 0x01 0xCA
 0x00 0x00 
 
instead of:
 0x04 0x05 0x01 0xAB 0x23 0x7F 0xCA
 
for encoding the five bytes 0x01 0xAB 0x23 0x7F 0xCA.


When receiving an CompressedData message use the CompressedDataStream(InputStream) constructor for parsing the CompressedData from its BER encoding:

 // the input stream supplying the BER encoded CompressedData
 InputStream encodedStream = ...;
 // parse the CompressedData
 CompressedDataStream compressedData = new CompressedDataStream(encodedStream);
 
If the content has been transmitted by other means (EXPLICIT mode) it now has to be supplied by calling method setInputStream since it is required for being decompressed:
 if (compressedData.getMode() == CompressedDataStream.EXPLICIT) {
   // in explicit mode explicitly supply the compressed content to be decompressed 
   InputStream contentIs = ...; // the compressed content supplied from an input stream
   compressedData.setInputStream(contentIs);
 }
 
Now you may call method getInputStream to access the content. While reading the stream the compressed data is decompressed by piping it through a InputStreamCompressEngine, e.g.:
 InputStream contentIs = compressedData.getInputStream();
 byte[] buf = new byte[1024];
 int r;
 while ((r = data_is.read(buf)) > 0) {
   // do something useful
 } 
 


Field Summary
protected  int blockSize_
          The block size for block oriented stream encoding.
protected  AlgorithmID compressionAlgorithm_
          The compression algorithm to be used.
static ObjectID contentType
          The ContentType oid of the CompressedData type ("1.2.840.113549.1.9.16.1.9"):
protected  ObjectID encapContentType_
          The content type of the inherent EncapsulatedContentInfo.
static int EXPLICIT
          Denotes a mode where the compressed data is not included in the CompressedData message.
static int IMPLICIT
          Denotes a mode where the compressed data is included in the CompressedData message.
protected  java.io.InputStream inputStream_
          An InputStream holding the data.
protected  int version_
          The CMS version number.
 
Constructor Summary
protected CompressedDataStream()
          Default constructor for dynamic object creation.
  CompressedDataStream(java.io.InputStream is)
          Creates a CompressedDataStream object from a BER encoded CompressedData object which is read from the given input stream.
  CompressedDataStream(java.io.InputStream dataIs, AlgorithmID compressionAlgorithm, int mode)
          Creates a new CompressedDataStream object for the given content data.
  CompressedDataStream(ObjectID contentType, java.io.InputStream dataIs, AlgorithmID compressionAlgorithm, int mode)
          Creates a new CompressedDataStream object for the given content data.
 
Method Summary
 void decode(java.io.InputStream is)
          Reads and decodes a BER encoded CompressedData from an input stream.
 int getBlockSize()
          Gets the block size defining the length of each definite primitive encoded octet string component.
 AlgorithmID getCompressionAlgorithm()
          Returns the compression algorithm used for data compression/decompression.
 ObjectID getContentType()
          Returns the content type this class implements.
 ObjectID getEncapsulatedContentType()
          Returns the content type the inherent EncapsulatetContentInfo represents.
 java.io.InputStream getInputStream()
          Returns an input stream from which the compressed/decompressed data may be read.
 int getMode()
          Returns the mode of this CompressedData.
 SecurityProvider getSecurityProvider()
          Gets the SecurityProvider installed for this CompressedDataStream.
 int getVersion()
          Returns the version syntax number (0).
 void setBlockSize(int blockSize)
          Sets the block size for defining the length of each definite primitive encoded octet string component.
 void setInputStream(java.io.InputStream is)
          Sets the content suppliyng input stream.
 void setSecurityProvider(SecurityProvider securityProvider)
          Sets the SecurityProvider for this CompressedDataStream.
 ASN1Object toASN1Object()
          Returns the CompressedData as ASN1Object.
protected  ASN1Object toASN1Object(int blockSize)
          Returns the CompressedData as ASN1Object where a constructed OCTET STRING is used for encoding the compressed content.
 java.lang.String toString()
          Returns a string giving some information about this CompressedData object.
 java.lang.String toString(boolean detailed)
          Returns a string giving some - if requested - detailed information about this CompressedData object.
 void writeTo(java.io.OutputStream os)
          Writes the CompressedData BER encoded to the supplied output stream.
 void writeTo(java.io.OutputStream os, int blockSize)
          Writes this CompressedData to the supplied output stream where a constructed OCTET STRING is used for encoding the content.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

contentType

public static final ObjectID contentType
The ContentType oid of the CompressedData type ("1.2.840.113549.1.9.16.1.9"):


IMPLICIT

public static final int IMPLICIT
Denotes a mode where the compressed data is included in the CompressedData message.

See Also:
Constant Field Values

EXPLICIT

public static final int EXPLICIT
Denotes a mode where the compressed data is not included in the CompressedData message.

See Also:
Constant Field Values

version_

protected int version_
The CMS version number. Default: 0.


compressionAlgorithm_

protected AlgorithmID compressionAlgorithm_
The compression algorithm to be used.


encapContentType_

protected ObjectID encapContentType_
The content type of the inherent EncapsulatedContentInfo.


blockSize_

protected int blockSize_
The block size for block oriented stream encoding. (Default: 2048 to enforce indefinite constructed encoding).


inputStream_

protected java.io.InputStream inputStream_
An InputStream holding the data.

Constructor Detail

CompressedDataStream

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


CompressedDataStream

public CompressedDataStream(java.io.InputStream dataIs,
                            AlgorithmID compressionAlgorithm,
                            int mode)
Creates a new CompressedDataStream object for the given content data. The data to be compressed is supplied from an input stream. The mode parameter specifies whether to include the compressed data (mode = CompressedDataStream.IMPLICIT) or not include it (mode = CompressedDataStream.EXPLICIT). The content type of the inherent EncapsulatedContentInfo automatically is set to CMS Data.

Parameters:
dataIs - the data to be compressed, supplied from an input stream
compressionAlgorithm - the compression algorithm to be used for content compression
mode - either CompressedDataStream.IMPLICIT for including the compressed data, or CompressedDataStream.EXPLICIT for not including it

CompressedDataStream

public CompressedDataStream(ObjectID contentType,
                            java.io.InputStream dataIs,
                            AlgorithmID compressionAlgorithm,
                            int mode)
Creates a new CompressedDataStream object for the given content data. The data to be compressed is supplied from an input stream. The mode parameter specifies whether to include the compressed data (mode = CompressedDataStream.IMPLICIT) or not include it (mode = CompressedDataStream.EXPLICIT).

Parameters:
contentType - the content type (e.g. ObjectID.cms_data) of the data to be compressed
dataIs - the data to be compressed, supplied from an input stream
compressionAlgorithm - the compression algorithm to be used for content compression
mode - either CompressedDataStream.IMPLICIT for including the compressed data, or CompressedDataStream.EXPLICIT for not including it

CompressedDataStream

public CompressedDataStream(java.io.InputStream is)
                     throws java.io.IOException,
                            CMSParsingException
Creates a CompressedDataStream object from a BER encoded CompressedData object which is read from the given input stream. The encoded CompressedData may (or may not) be wrapped into a ContentInfo.

Parameters:
is - the InputStream holding the BER encoded CMS CompressedData object
Throws:
java.io.IOException - if an error occurs when reading from the stream
CMSParsingException - if the object can not be parsed
Method Detail

setSecurityProvider

public void setSecurityProvider(SecurityProvider securityProvider)
Sets the SecurityProvider for this CompressedDataStream.

This method allows to explicitly set a SecurityProvider for this CompressedDataStream. If no explicit SecurityProvider is set, the default system wide installed SecurityProvider will be used for the required cryptographic operations.

This class may use the following method of the SecurityProvider, which may be overriden by an application, if required:

Parameters:
securityProvider - the SecurityProvider to be set

getSecurityProvider

public SecurityProvider getSecurityProvider()
Gets the SecurityProvider installed for this CompressedDataStream.

This class uses the following method of the SecurityProvider, which may be overriden by an application, if required:

If no explicit SecurityProvider has been set for this object, the default system wide installed SecurityProvider will be used for the required cryptographic operations. However, this method will return null if it does not have its own SecurityProvider.

Returns:
the SecurityProvider explicitly installed for this object, or null if this object does not have its own SecurityProvider

decode

public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   CMSParsingException
Reads and decodes a BER encoded CompressedData from an input stream. The encoded CompressedData may (or may not) be wrapped into a ContentInfo.

Specified by:
decode in interface ContentStream
Parameters:
is - the InputStream holding a BER encoded CMS CompressedData 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

getContentType

public ObjectID getContentType()
Returns the content type this class implements.

Specified by:
getContentType in interface ContentStream
Returns:
ObjectID.cms_compressedData ("1.2..840.113549.1.9.16.1.9")

getEncapsulatedContentType

public ObjectID getEncapsulatedContentType()
Returns the content type the inherent EncapsulatetContentInfo represents.

Returns:
the content type the inherent EncapsulatetContentInfo represents

getVersion

public int getVersion()
Returns the version syntax number (0).

Returns:
the version syntax number

getCompressionAlgorithm

public AlgorithmID getCompressionAlgorithm()
Returns the compression algorithm used for data compression/decompression.

Returns:
the ID of the message-digest algorithm

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

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.

Specified by:
getBlockSize in interface ContentStream
Returns:
blockSize defining the encoding scheme and setting the octet string component length, if positive

getMode

public int getMode()
Returns the mode of this CompressedData.

Returns:
IMPLICIT or EXPLICIT

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.security.NoSuchAlgorithmException,
                                          java.io.IOException
Returns an input stream from which the compressed/decompressed data may be read.

Attention! The stream only may be read once.

When having created a new CompressedDataStream object to be encoded to a stream, this method should only be called in EXPLICT mode to get and read away the compressed content to be transmitted by other means. In IMPLICT mode this method shall not be called at all since the compressed content has to be included in the CompressedData message (and therefore should not be read "away").
When having decoded and parsed a received CompressedDataStream object coming from some stream, this method may be used for obtaining the raw (decompressed) content.

Returns:
an input stream with the compressed/decompressed content
Throws:
java.security.NoSuchAlgorithmException - if the compression algorithm is not supported
java.io.IOException - if an I/O error occurs

setInputStream

public void setInputStream(java.io.InputStream is)
                    throws java.security.NoSuchAlgorithmException,
                           java.io.IOException
Sets the content suppliyng input stream. When having created a new CompressedDataStream object to be encoded to a stream, this method may be used to supply the content to be compressed.
When having decoded and parsed a received CompressedDataStream object coming from some stream, this method may be used for supplying the compressed content transmitted by other means (EXPLICIT mode).

Parameters:
is - an input stream supplying the content to be compressed/decompressed
Throws:
java.security.NoSuchAlgorithmException - if the compression algorithm is not supported
java.io.IOException - if an I/O error occurs

toASN1Object

public ASN1Object toASN1Object()
                        throws CMSException
Returns the CompressedData as ASN1Object.

Specified by:
toASN1Object in interface ContentStream
Returns:
the CompressedData as ASN1Object
Throws:
CMSException - if the ASN1Object could not be created

toASN1Object

protected ASN1Object toASN1Object(int blockSize)
                           throws CMSException
Returns the CompressedData as ASN1Object where a constructed OCTET STRING is used for encoding the compressed content.

Parameters:
blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive
Throws:
CMSException - if the ASN1Object could not be created

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException
Writes the CompressedData BER encoded to the supplied output stream. If for the inherent content structure a positive blocksize has been specified, the compressed content is encoded as indefinite constructed octet string.

Parameters:
os - the output stream to which this CompressedData shall be written
Throws:
java.io.IOException - if an IOException occurs while writing to the stream

writeTo

public void writeTo(java.io.OutputStream os,
                    int blockSize)
             throws java.io.IOException
Writes this CompressedData to the supplied output stream where a constructed OCTET STRING is used for encoding the content. If block size has a value > 0, in implicit mode the inherent compressed data is encoded as constructed OCTET STRING. 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, the whole inherent data is encoded as one single primitive definite octet string:
 0x04 <length> <data>
 

Parameters:
os - the output stream to which this CompressedData shall be written
blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive
Throws:
java.io.IOException - if an error occurs during writing the object

toString

public java.lang.String toString()
Returns a string giving some information about this CompressedData 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 CompressedData 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