iaik.asn1

Class BIT_STRING

java.lang.Object

iaik.asn1.ASN1Object

iaik.asn1.BIT_STRING

All Implemented Interfaces:

java.lang.Cloneable

public class BIT_STRING
extends ASN1Object

This class implements the native ASN.1 type "BIT STRING".

BIT STRING is a simple ASN.1 string type identified by the UNIVERSAL TAG number 3. An ASN.1 BIT STRING object may represent any arbitrary string of bits.

The value of a BIT STRING object is DER encoded by first specifying the number of bits not used in the last of the following contents octets.

For instance: DER encoding the bit string '011010001'B will need two content octets: 01101000 10000000 (hexadecimal 68 80); seven bits of the last octet are not used leading to the following DER encoding (hexadecimal):

 03 03 07 68 80
 

where the first octet is the identifier octet: <03> for BIT STRING; the following length octet indicates the number (3) of content octets: <03>; and the first of the final contents octets indicates that seven bits of the last content octet will not be used: <07> <68> <80>

When creating a new ASN.1 BIT_STRING object, the value to be represented may be supplied in one of three formats:

• as binary string, e.g. "011010001"
• as boolean array, e.g. {false,true,true,false,true,false,false,false,true}
• as byte array, e.g. { (byte)0x68, (byte)0x80}

When using a binary string or an array of boolean values, the number of invalid bits automatically is calculated for giving a proper encoding. However, when specifying the value as a byte array, the number of invalid bits explicitly has to be set by means of the BIT_STRING(byte[] array, int bitsNotValid) constructor. Otherwise the encoding only will give the expected result when there are no unused bits in the last content octet.

Consider, for instance, the bit string '011010001'B example from above: when supplying the value as binary string or boolean array, the number (7) of unused bits automatically is calculated giving the right encoding of 03 03 07 68 80:

 BIT_STRING bit_string = new BIT_STRING("011010001");
 //or
 BIT_STRING bit_string = new BIT_STRING(new boolean[] {false,true,true,false,true
                                                       false,false,false,true };
 

As stated above, the content representation of the bit string '011010001'B will give two content octets of values 0x68 0x80 (hexadecimal). Now, when using these two bytes for supplying the value of a new BIT_STRING object, explicitly the number of unused bits (7) of the last content octet has to be specified:

 byte[] value = { (byte) 0x68, (byte) 0x80 };
 BIT_STRING bit_string = new BIT_STRING(value, 7);
 

Otherwise it would be assumed, that all bits of the last content octet are significant (number of invalid bits = 0), and the encoding will be a different one.

When calling the getValue method for getting the inherent value from an ASN.1 BIT_STRING instance, a byte array is returned. For getting a "binary string" representation of the value, use the getBinaryString() method.

DER en/decoding generally is done by means of the several methods of the DerCoder class; decoding alternatively may be performed by using the DerInputStream utility.

Version:

File Revision 21

See Also:

ASN1Object, ASN

Field Summary

Fields

Modifier and Type	Field and Description
protected int	bits_not_valid Number of bits not valid in the byte array of bits.
protected byte[]	value The bits of the BIT STRING in a byte array, initialized with null.

Fields inherited from class iaik.asn1.ASN1Object

asnType, constructed, encode_listener, indefinite_length, isStringType, stream_mode

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BIT_STRING() Creates a new BIT STRING object.
	BIT_STRING(boolean[] array) Creates a new BIT STRING from a boolean array.
	BIT_STRING(byte[] array) Creates a new BIT STRING object where all bits of the byte array are valid.
	BIT_STRING(byte[] array, int bitsNotValid) Creates a new BIT STRING object from a byte array and an integer.
	BIT_STRING(java.lang.String binaryString) Creates a new BIT STRING from a binary string (e.g.

Method Summary

Methods

Modifier and Type	Method and Description
int	bitsNotValid() Returns the number of bits which are not valid.
java.lang.Object	clone() Returns a clone of this ASN1String.
protected void	decode(int length, java.io.InputStream is) Decodes a BIT_STRING value from the given InputStream.
protected void	encode(java.io.OutputStream os) DER encodes this BIT STRING ASN1Object and writes the result to the given output stream.
java.lang.String	getBinaryString() Returns the value of this BIT_STRING as a binary string.
java.lang.Object	getValue() Returns the value of this BIT_STRING as a byte array.
void	setValue(java.lang.Object object) Sets the value of this object to value.
java.lang.String	toString() Returns a string that represents the contents of this BIT STRING ASN1Object.

Methods inherited from class iaik.asn1.ASN1Object

addComponent, addEncodeListener, countComponents, encodeObject, getAsnType, getComponentAt, indefiniteLength, isA, isConstructed, isStringType, setIndefiniteLength

Methods inherited from class java.lang.Object

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

Field Detail

bits_not_valid

protected int bits_not_valid

Number of bits not valid in the byte array of bits. Specified the number of bits that are not used in the last content octet.

value

protected byte[] value

The bits of the BIT STRING in a byte array, initialized with null.

Constructor Detail

BIT_STRING

protected BIT_STRING()

Creates a new BIT STRING object. Called by the OBJECTFactory.

BIT_STRING

public BIT_STRING(byte[] array,
          int bitsNotValid)

Creates a new BIT STRING object from a byte array and an integer. The byte array supplies the value of the BIT_STRING object to be created, and int parameter explicitly specifies the number of bits not used in the last content octet.

The, for instance, bit string '011010001'B can be represented by two content octets of values 0x68 0x80 (hexadecimal). Now, when using these two bytes for supplying the value of a new BIT_STRING object, explicitly the number of unused bits (7) of the last content octet has to be specified:

 byte[] value = { (byte) 0x68, (byte) 0x80 };
 BIT_STRING bit_string = new BIT_STRING(value, 7);
 

If bitsNotValid is -1, the bits that are not valid are automatically counted from the end of value.

Parameters:

array - the bits in a byte array

bitsNotValid - number of bits which are not valid in the last byte

Throws:

java.lang.IllegalArgumentException - if bitsNotValid is out of range (%lt; -1 or > 7)

BIT_STRING

public BIT_STRING(byte[] array)

Creates a new BIT STRING object where all bits of the byte array are valid.

Parameters:

array - the byte array containing the bits

BIT_STRING

public BIT_STRING(java.lang.String binaryString)

Creates a new BIT STRING from a binary string (e.g. "11100101"). The number of bits not used in the last content octet automatically will be calculated, e.g.:

 BIT_STRING bit_string = new BIT_STRING("011010001");
 

Parameters:

binaryString - the String containing the bits

BIT_STRING

public BIT_STRING(boolean[] array)

Creates a new BIT STRING from a boolean array. The number of bits not used in the last content octet automatically will be calculated, e.g.:

 BIT_STRING bit_string = new BIT_STRING(new boolean[] {false,true,true,false,true
                                                       false,false,false,true };
 

Parameters:

array - the boolean array representing the bit string value

Method Detail

clone

public java.lang.Object clone()

Returns a clone of this ASN1String.

Overrides:

clone in class ASN1Object

Returns:

a clone of this ASN1String

getValue

public java.lang.Object getValue()

Returns the value of this BIT_STRING as a byte array.

Specified by:

getValue in class ASN1Object

Returns:

the bits of this BIT_STRING in a byte array

setValue

public void setValue(java.lang.Object object)

Sets the value of this object to value. Attention! Since the supplied value has to be a byte array, it is assumed that all bits are valid. So use the BIT_STRING(byte[] array, int bitsNotValid) constructor for supplying a byte array value and explicitly setting the number of invalid bits.

Specified by:

setValue in class ASN1Object

Parameters:

object - the byte array value to be set for this BIT STRING object

bitsNotValid

public int bitsNotValid()

Returns the number of bits which are not valid.

Returns:

the number of bits which are not valid

getBinaryString

public java.lang.String getBinaryString()

Returns the value of this BIT_STRING as a binary string.

Returns:

the string (e.g. "101010011")

encode

protected void encode(java.io.OutputStream os)
               throws java.io.IOException

DER encodes this BIT 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 a BIT_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.

Specified by:

encode in class ASN1Object

Parameters:

os - the output stream to which to write the data

Throws:

java.io.IOException - if an I/O error occurs while writing to the stream

decode

protected void decode(int length,
          java.io.InputStream is)
               throws java.io.IOException

Decodes a BIT_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 (content octets including bitsNotValid specification) of an ASN.1 object of type BIT_STRING.

This is a protected method and will not be used by an application for decoding a DER encoded BIT_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 BIT_STRING object and internally calls this decode method for actually reading the value.

Specified by:

decode in class ASN1Object

Parameters:

length - the already decoded length, i.e. number of the bytes representing the value of the BIT_STRING to be decoded

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

Throws:

java.io.IOException - if there is a problem with the InputStream

toString

public java.lang.String toString()

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

Overrides:

toString in class ASN1Object

Returns:

the string representation

See Also:

ASN1Object.toString()