iaik.asn1
Class OCTET_STRING

java.lang.Object
  |
  +--iaik.asn1.ASN1Object
        |
        +--iaik.asn1.ConstructedType
              |
              +--iaik.asn1.OCTET_STRING

All Implemented Interfaces:

Cloneable

public class OCTET_STRING

extends ConstructedType

This class implements the native ASN.1 type "OCTET STRING". OCTET STRING is a simple ASN.1 string type identified by the UNIVERSAL TAG number 4. An ASN.1 OCTET STRING object may represent any arbitrary string of octets (bytes).

An OCTET STRING object often is BER encoded using the constructed indefinite encoding method by splitting the value into separately definite primitive encoded OCTET STRING components, which may be preferable when dealing with large amounts of data and/or intending to be compatible to the encoding practice of some particular application (for instance some versions of Netscape Navigator).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 data bytes 0x01 0xAB 0x23 0x7F 0xCA.

Therefore the OCTET STRING class is extended to be a subclass of the ConstructedType class. Each component can be added to the current OCTET STRING object by using the addComponent method. However, when using the addComponent method to build nested octet string structures, the data shall be small enough to be handled within the memory. For properly handling large amounts of data by splitting the encoding as above, use the OCTET_STRING(InputStream is, int blockSize) construtor for defining the length of each definite primitive encoded octet string component. Note that indefinite constructed encoding only will work when performing the encoding with the encodeTo method of the DerCoder class:

 //the raw data supplying input stream:
 InputStream data = ...;
 int blockSize = ...;
 OCTET_STRING oct = new OCTET_STRING(data, blockSize);
 OutputStream encoded_stream = ...;
 DerCoder.encodeTo(oct, encoded_stream);
 

In this way, the general proceeding for using the indefinite constructed method to encode large-data carrying octet strings can be summarized as follows:

• the data is read from the input stream not before the encoding actually is performed
• during the encoding the data is read from the input stream block by block according to a predefined block size; immediately when reading a block it is definite primitive encoded and written to the encoding output stream, which previously has been initialized for the data encoding by writing the constructed indefinite identifier and length tags 0x24 0x80
• after actually processing the last data block the encoding output stream is closed by writing the EOC tags 0x00 0x00

This procedure makes it possible to limit the data volumes actually processed within the memory to a reasonable small size!

Version:

File Revision 36

See Also:

ASN1Object, ASN, ConstructedType, DerCoder

Fields inherited from class iaik.asn1.ConstructedType

content_count, content_data

Fields inherited from class iaik.asn1.ASN1Object

asnType, constructed, encode_listener, indefinite_length, isStringType, stream_mode

Constructor Summary

OCTET_STRING()
Creates an empty OCTET_STRING.

OCTET_STRING(byte[] array)
Creates a primitive OCTET_STRING object for the given byte value.

OCTET_STRING(byte[] array, int blockSize)
Creates a constructed OCTET STRING which reads the content data from a byte array and splits the data into blocks of blockSize bytes.

OCTET_STRING(InputStream in)
Creates a primitive OCTET STRING which reads the content data from an InputStream.

OCTET_STRING(InputStream in, int blockSize)
Creates a constructed OCTET STRING which reads the content data from an InputStream and splits the data into blocks of blockSize bytes.

Method Summary

void	addComponent(ASN1Object component, int index) Inserts a new OCTET_STRING component to a given location within this OCTET_STRING.
Object	clone() Returns a clone of this OCTET_STRING.
protected void	decode(int length, InputStream is) Decodes an OCTET_STRING value from the given InputStream.
protected void	encode(OutputStream os) DER encodes this OCTET_STRING ASN1Object and writes the result to the given output stream.
void	encodeAsIndefiniteConstructedOctetString(OutputStream os, int blocksize) Writes this OCTET_STRING as indefinite encoded octet string to the given output stream.
int	getBlockSize() Returns the blockSize defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive.
OCTET_STRING	getSimpleOctetString() Returns this OCTET_STRING as simple OCTET_STRING.
Object	getValue() Returns the value of this OCTET_STRING as byte array.
byte[]	getWholeValue() Returns the whole value of this OCTET_STRING as a byte array.
void	setIndefiniteLength(boolean indefiniteLength) Switches indefinite length encoding on or off for this OCTET_STRING.
void	setValue(Object object) Sets the value (or input stream) of this object to value.
String	toString() Returns a string that represents the contents of this OCTET STRING ASN1Object.
String	toString(boolean allBytes) Returns a string that represents the contents of this OCTET STRING ASN1Object.
void	writeWholeValueToStream(OutputStream os) Writes the value of this OCTET_STRING to the given output stream.

Methods inherited from class iaik.asn1.ConstructedType

addComponent, addEncodeListener, countComponents, getComponentAt, getComponents, removeComponent, removeComponent, setComponent

Methods inherited from class iaik.asn1.ASN1Object

addEncodeListener, encodeObject, getAsnType, indefiniteLength, isA, isConstructed, isStringType

Methods inherited from class java.lang.Object

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

Constructor Detail

OCTET_STRING

public OCTET_STRING()

Creates an empty OCTET_STRING. Data later may be supplied by means of the setValue method or by using the addComponent method.

When using the setValue method, the data has to be supplied as byte array or input stream. The resulting octet string will be recognized as primitive octet string.

When using the addComponent method for building a constructed octet string, any supplied component has to be an OCTET_STRING instance itself.

OCTET_STRING

public OCTET_STRING(byte[] array)

Creates a primitive OCTET_STRING object for the given byte value.

Parameters:

array - the byte value this OCTET STRING object should be represent

OCTET_STRING

public OCTET_STRING(byte[] array,
                    int blockSize)

Creates a constructed OCTET STRING which reads the content data from a byte array and splits the data into blocks of blockSize bytes.

Example: OCTET_STRING(content, 2) with {1,2,3,4,5} as content of the will result in the following BER encoding:

 24               constructed
  80              indefinite length encoding
   04 02 01 02    first OCTET STRING with length 2
   04 02 03 04    second OCTET STRING with length 2
   04 01 05       third OCTET STRING with length 1
 00 00            end of indefinite length encoding
 

Parameters:

array - the byte array supplying the raw data

blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive

OCTET_STRING

public OCTET_STRING(InputStream in)

Creates a primitive OCTET STRING which reads the content data from an InputStream. The data is read from the InputStream not before actually performing the encoding by calling one of the corresponding methods of the DerCoder class. The whole data available from the InputStream will be encoded as definite primitive OCTET_STRING:

 0x04 <length> <data>
 

Parameters:

in - the input stream supplying the raw data

OCTET_STRING

public OCTET_STRING(InputStream in,
                    int blockSize)

Creates a constructed OCTET STRING which reads the content data from an InputStream and splits the data into blocks of blockSize bytes. The data is read from the InputStream not before actually performing the encoding by calling one of the corresponding methods of the DerCoder class. This constructor shall be used for dealing with big amounts of data.

Example: OCTET_STRING(in, 2) with {1,2,3,4,5} as content of the InputStream will result in the following BER encoding:

 24               constructed
  80              indefinite length encoding
   04 02 01:02    first OCTET STRING with length 2
   04 02 03:04    second OCTET STRING with length 2
   04 01 05       third OCTET STRING with length 1
 00 00            end of indefinite length encoding
 

The splitting into blockSize blocks only works if DerCoder#encodeTo(ASN1Object, OutputStream) is used to encode the octet string. If DerCoder.encode(ASN1Object) is used, the whole OCTET_STRING will be encoded as definite primitive octet string, which alternatively may be done when no blocksize has been specified by using the OCTET_STRING(InputStream) constructor.

Parameters:

in - the input stream supplying the raw data

blockSize - the block size defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive

Method Detail

clone

public Object clone()

Returns a clone of this OCTET_STRING. Attention! If this OCTET_STRING uses an input stream for its data instead of a byte array, this clone method will read this stream until EOF and store the result as its new byte array value. This does not only apply to the clone but also to the original OCTET_STRING. This means that this method has a side effect if it is based on a stream. Thus, the applcation should not use this method if it wants to do good streaming operation.

Overrides:

clone in class ConstructedType

Returns:

a clone of this OCTET_STRING

getValue

public Object getValue()

Returns the value of this OCTET_STRING as byte array.

If this OCTET_STRING is constructed, this method recursively steps through all included OCTET_STRING components and concatenates all participated values; use writeWholeValueToStream for expected large objects!

Overrides:

getValue in class ConstructedType

Returns:

the value of this OCTET_STRING as byte array

getWholeValue

public byte[] getWholeValue()
                     throws IOException

Returns the whole value of this OCTET_STRING as a byte array. If this OCTET_STRING is constructed, this method recursively steps through all included OCTET_STRING components and concatenates all participated values. Since any sub octet srting may contribute to the final value either by supplying its sub-value immediately or by reading from its sub-inputstream, use writeWholeValueToStream for expected large objects!

Returns:

the value of this OCTET_STRING as byte array

Throws:

IOException - if any of the participated input streams already has been read, or an IO Error occurs while stream reading/writing

writeWholeValueToStream

public void writeWholeValueToStream(OutputStream os)
                             throws IOException

Writes the value of this OCTET_STRING to the given output stream. If this OCTET_STRING is constructed, this method recursively steps through all included OCTET_STRING components and concatenates all participated values. Any sub octet srting may contribute to the final value either by supplying its sub-value immediately or by reading from its sub-inputstream.

Parameters:

os - the output stream to which to write the value of this OCTET_STRING

Throws:

IOException - if any of the participated input streams already has been read, or an IO Error occurs while stream reading/writing

encodeAsIndefiniteConstructedOctetString

public void encodeAsIndefiniteConstructedOctetString(OutputStream os,
                                                     int blocksize)
                                              throws IOException

Writes this OCTET_STRING as indefinite encoded octet string to the given output stream.

If this OCTET_STRING is constructed, this method recursively steps through all included OCTET_STRING components and concatenates all participated values. Any sub octet string may contribute to the final value either by supplying its sub-value immediately or by reading from its sub-inputstream.

If blocksize is set to a positive value, this method encodes the data in chunks of definite encoded octet strings of the given blocksize:

 24 80
       04  
       04  
       ...
 00 00
 

If this octet string has been created by means of the OCTET_STRING(InputStream in, int blockSize) constructor, this method will take the block size specified there if no blocksize is specified by this method. If a blocksize explicitly is specified, the encoding will be splitted according to this blocksize, regardless of the blocksize that has been specified in the constructor.

If no blocksize is specified and no inherent blocksize is set, a default blocksize of 1024 is taken.

If the number of data bytes represented by this octet sring is shorter than the defined blocksize, the resulting structured encoding only will contain one primitive octet string component containing all data bytes, e.g. (supposing that the octet string holds five data bytes, and the specified blocksize is 1024):

 24 80
       04 05 13 07 01 AB 47
 00 00
 

Note that this method also will encode a simple octet string by splitting it according to the specified block size. For that reason it is recommended to use this method only for simplifying the encoding of a deeply nested octet string structure, or for properly handling big data quantities carrying sub-components. Simple octet strings and constructed octet strings created with the block size specifying constructor shall be encoded by the encoding methods of the DerCoder class. The DerCoder class also has to be used when the structure of the actual octet string exactly (1:1) has to be rebuilt within the encoding - which sometimes unfortunately may exceed the memory capacity.

Parameters:

os - the output stream to which to write the encoding

blocksize - the size of the definite encoded data blocks; if value <= 0 is specified, the blocksize is set to 1024

Throws:

IOException - if any of the participated input streams already has been read, or an IO Error occurs while stream reading/writing

setValue

public void setValue(Object object)

Sets the value (or input stream) of this object to value. Be carefully by using this method for supplying a new value. This method will overwrite any exisiting value and clear any existing content_data.

This method is inherited from the ConstructedType class but has a somewhat different meaning for the OCTET_STRING class. Whereas in ConstructedType the given object is expected to be an array of ASN1Objects for setting the components of the ConstructedType object, now the object is expected to be a byte array or an InputStream supplying the raw data for a simple OCTET_STRING object. Components for a constructed OCTET_STRING only may be supplied by means of the addComponent methods.

Generally there should be no need for using this method since data immediately can be supplied when creating a new simple OCTET_STRING object by means of a proper constructor. However, when actually using this method, be aware about the following issues:

• The supplied object either has to be a byte array value or an InputStream instance.
• If a byte value is supplied, an already existing byte value will be replaced by the new one, and any existing input_stream or content_data will be set to null; the encoding will be definite and primitive.
• If an input stream is supplied, an already existing input stream will be replaced by the new one, and any existing byte value or content_data will be set to null; if block_size is -1, the encoding will be definite and primitive

Overrides:

setValue in class ConstructedType

Parameters:

object - the new value for this OCTET_STRING, as byte array or input stream

setIndefiniteLength

public void setIndefiniteLength(boolean indefiniteLength)

Switches indefinite length encoding on or off for this OCTET_STRING. If a blocksize is specified for this OCTET_STRING, indefinite length encoding always will be set to true and cannot be changed by this method.

If this is a primitive octet string, indefinite length encoding always will be set to false and cannot be changed by this method.

Overrides:

setIndefiniteLength in class ASN1Object

Parameters:

indefiniteLength - true, if this OCTET_STRING shall be encoded using indefinite length, false if shall be encoded as definite length

addComponent

public void addComponent(ASN1Object component,
                         int index)

Inserts a new OCTET_STRING component to a given location within this OCTET_STRING. Attention! Components to be added have to be instances of OCTET_STRING! Components only can be added to octet strings which do not contain a not-null value or input_stream

Overrides:

addComponent in class ConstructedType

Parameters:

component - the component (OCTET_STRING) to insert

index - where to insert the new component

Throws:

ArrayIndexOutOfBoundsException - If the index is invalid

InternalErrorException - if the component to be added is no instance of OCTET_STRING, or if this OCTET_STRING contains a not-null value or data carrying input_stream

encode

protected void encode(OutputStream os)
               throws IOException

DER encodes this OCTET_STRING ASN1Object and writes the result to the given output stream. This is a protected method and will not be used by an application for DER encoding an OCTET_STRING object. An application will call one of the encode methods of the DerCoder class for performing the encoding, and the DerCoder internally will call this encode method.

Overrides:

encode in class ConstructedType

Parameters:

os - the output stream to which to write the encoding

Throws:

IOException - if an error occurs during writing to the stream

decode

protected void decode(int length,
                      InputStream is)
               throws IOException,
                      CodingException

Decodes an OCTET_STRING value from the given InputStream. The given input stream carries DER encoded data, and the next length bytes to be read represent the value of an ASN.1 object of type OCTET_STRING.

This method only parses the value from the stream, if the supplied DER encoding represents a primitive octet string; if it represents a constructed octet string, the decoding task is passed to the corresponding method of the ConstructedType super class.

This is a protected method and will not be used by an application for decoding a DER encoded OCTET_STRING. An application will call one of the decode methods of the DerCoder class for performing the decoding. The DerCoder then determines the number of bytes (length) occupied by the value of this (primitive) OCTET_STRING object and internally calls this decode method for actually reading the value.

Overrides:

decode in class ConstructedType

Parameters:

length - the already decoded length, i.e. number of the bytes representing the value of the (primitive) OCTET_STRING to be decoded;

is - the input stream from which the DER encoded data is read in

Throws:

IOException - if there is a problem with the InputStream

CodingException - if an decoding error occurs; e.g. a simple octet string has been indefinite encoded

getSimpleOctetString

public OCTET_STRING getSimpleOctetString()
                                  throws IOException

Returns this OCTET_STRING as simple OCTET_STRING. If this OCTET_STRING already is a simple OCTET_STRING, a new instance of this octet string is returned. If this OCTET_STRING is a constructed OCTET_STRING composed of an arbitrary nested structure of OCTET_STRINGs, all included byte values - either directly supported or read from an input stream - are concatenated to form a simple OCTET_STRING.

For instance: The constructed OCTET_STRING below would be transformed by this method as follows (DER encoding, hexadecimal output):

 24 80 -- constructed, indefinite length
       04 03 01 23 AB
       04 05 0C 34 05 06 07
       04 02 45 01
       04 01 12
 00 00 -- end of constructed, indefinite
 

After calling getSimpleOctetString the new OCTET_STRING would look like:

 04 0B 01 23 AB 0C 34 05 06 07 45 01 12
 

(Note that hexadecimal 0B is decimal 11, the number of octets in the content field of the resulting OCTET_STRING.)

Since this method builds up the final simple octet string within the memory, use encodeAsIndefiniteConstructedOctetString for immediately indefinite encoding this octet string to a stream.

Throws:

IOException - if any of the participated input streams already has been read, or an IO Error occurs while reading from a stream

getBlockSize

public int getBlockSize()

Returns the blockSize defining the encoding scheme - and specifying the length of each primitive encoded octet string component, if positive.

Returns:

the block size for splitting the encoding

toString

public String toString()

Returns a string that represents the contents of this OCTET STRING ASN1Object.

Overrides:

toString in class ASN1Object

Returns:

the string representation

See Also:

ASN1Object.toString()

toString

public String toString(boolean allBytes)

Returns a string that represents the contents of this OCTET STRING ASN1Object.

Parameters:

allBytes - whether to print all bytes of the octet string, or only the first 5 bytes

Returns:

the string representation

See Also:

ASN1Object.toString()