BIT_STRING ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.asn1.ASN1Object
- - iaik.asn1.BIT_STRING

```
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 represeantation 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.
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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`bitsNotValid()` Returns the number of bits which are not valid.
`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, setAutomaticRepair, setAutomaticRepairRecursive, setIndefiniteLength, setIndefiniteRecursive

Methods inherited from class java.lang.Object
clone, 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, forinstance, 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);
 
```
    Parameters:
    
    array - the bits in a byte array
    
    bitsNotValid - number of bits which are not valid in the last byte
  - 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
  - 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()

Class BIT_STRING

Field Summary

Fields inherited from class iaik.asn1.ASN1Object

Constructor Summary

Method Summary

Methods inherited from class iaik.asn1.ASN1Object

Methods inherited from class java.lang.Object

Field Detail

bits_not_valid

value

Constructor Detail

BIT_STRING

BIT_STRING

BIT_STRING

BIT_STRING

BIT_STRING

Method Detail

getValue

setValue

bitsNotValid

getBinaryString

encode

decode

toString