iaik.cms
Class CompressedDataStream

java.lang.Object
  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[2048];
   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 positive 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[2048];
 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:

• getInputStreamCompressEngine() to get an InputStreamCompressEngine through which the data is to be piped for data compression/decompression

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:

• getInputStreamCompressEngine() to get an InputStreamCompressEngine through which the data is to be piped for data compression/decompression

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