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

java.lang.Object
- iaik.asn1.ASN1Object

Direct Known Subclasses:

ASN1String, BIT_STRING, BOOLEAN, ConstructedType, ENUMERATED, GeneralizedTime, GraphicString, INTEGER, NULL, ObjectID, UTCTime
```
public abstract class ASN1Object
extends java.lang.Object
```
This abstract class defines the external interface for ASN.1 object, both primitive and constructed. The subclasses of this class are assumed to define the application specific methods for setting/accessing the contents of the particular ASN.1 data structure.
For DER en/decoding ASN.1 objects an application shall use the corresponding en/decode methods of the DerCoder class. For decoding large ASN.1 objects supplied from some stream, the DerInputStream utility may be used.
ASN.1 objects can be devided into simple types (e.g. BOOLEAN, INTEGER, ...), and structured types (e.g. SEQUENCE, SET, ...). Simple types always have to be encoded by using the primitive definite encoding method where the number of data octets explicitly has to be specified just behind the identifier octet. In this way, an encoding of, for instance, 0x04 0x03 will introduce an ASN.1 object of type OCTET_STRING (identifier field 0x04) containing three (length field 0x03) data octets. For stuctured types always the constructed encoding method is used, but the length field may by specified either in definite or indefinite form. Indefinite length encoding has to be used when the actual number of content octets to be transmitted is not known at the beginning of the data transfer.
Indefinite length encoding may be enforced by means of the setIndefiniteLength method.

See Also:

ASN

Field Summary

Fields
Modifier and Type	Field and Description
`protected ASN`	`asnType` The ASN.1 type of this ASN.1 object.
`protected boolean`	`constructed` Is this ASN1Object constructed or primitive?.
`protected iaik.asn1.EncodeListenerEntry[]`	`encode_listener` Objects which want to be notified when the encoding of an ASN1Object is performed.
`protected boolean`	`indefinite_length` Is the length of this ASN1Object encoded as indefinite or definite length?.
`protected boolean`	`isStringType` Is this ASN1Object a String type?
`protected boolean`	`stream_mode` In stream mode the components are written in correct order when the encoding is performed.

Constructor Summary

Constructors
Modifier Constructor and Description

protected ASN1Object()
Empty default constructor.

Constructors
Modifier	Constructor and Description
`protected`	`ASN1Object()` Empty default constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addComponent(ASN1Object component)` Throws a CodingException.
`void`	`addEncodeListener(EncodeListener encodeListener, int id)` Adds one EncodeListener which wants to be notified when the encoding of this ASN1Object has to be performed.
`int`	`countComponents()` Throws a CodingException.
`protected abstract void`	`decode(int length, java.io.InputStream is)` Decodes an ASN1Object represented by the next `length` bytes of the given input stream.
`protected abstract void`	`encode(java.io.OutputStream os)` DER encodes this ASN1Object and writes the result to the given output stream.
`protected void`	`encodeObject(java.io.OutputStream os, boolean streamMode)` DER encodes this ASN1Object and writes the output to the specified OutputStream.
`ASN`	`getAsnType()` Returns the ASN.1 type of this ASN.1 object.
`ASN1Object`	`getComponentAt(int index)` Throws a CodingException.
`abstract java.lang.Object`	`getValue()` Returns the value of this ASN1Object.
`boolean`	`indefiniteLength()` Returns whether this ASN1Object will be encoded by using the definite or indefinite encoding method.
`boolean`	`isA(ASN type)` Tests if this object is an instance of given ASN.1 type.
`boolean`	`isConstructed()` Returns whether this ASN1Object is constructed or primitive.
`boolean`	`isStringType()` Asks if this ASN1Object represents a String type.
`void`	`setAutomaticRepair(boolean repair)` Enables or disables the automatic repair of improperly DER encoded ASN.1 during encoding for this ASN.1 object.
`void`	`setAutomaticRepairRecursive(boolean repair)` Enables or disables the automatic repair of improperly DER encoded ASN.1 during encoding for this ASN.1 object and all other ASN.1 objects it may contain.
`void`	`setIndefiniteLength(boolean indefiniteLength)` Switches indefinite length encoding on or off for this ASN1Object.
`void`	`setIndefiniteRecursive(boolean indefinite)` Recursively changes the ASN.1 encoding of this object and all objects it contains to use indefinite length or definite length encoding.
`abstract void`	`setValue(java.lang.Object object)` Sets the value of this ASN1Object.
`java.lang.String`	`toString()` Returns a string that represents the contents of this ASN1Object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - constructed
```
protected boolean constructed
```
    Is this ASN1Object constructed or primitive?.
  - indefinite_length
```
protected boolean indefinite_length
```
    Is the length of this ASN1Object encoded as indefinite or definite length?.
  - asnType
```
protected ASN asnType
```
    The ASN.1 type of this ASN.1 object.
  - isStringType
```
protected boolean isStringType
```
    Is this ASN1Object a String type?
  - encode_listener
```
protected iaik.asn1.EncodeListenerEntry[] encode_listener
```
    Objects which want to be notified when the encoding of an ASN1Object is performed.
    EncodeListeners are instances of classes that implement the EncodeListener interface. Use the addEncodeListener method for registering an EncodeListener to be notified when the encoding of some particular ASN1Object has to be performed. The program execution then will jump to the encodeCalled method of the particular EncodeListener implementation.
  - stream_mode
```
protected boolean stream_mode
```
    In stream mode the components are written in correct order when the encoding is performed. If stream_mode is disabled the components are written in reverse order to simplify the calculation of the length. When dealing with large objects, the stream_mode shall be endabled and the indefinite length encoding method shall be used for allowing to split the encoding in small chunks that can be handled within the memory.
- Constructor Detail
  - ASN1Object
```
protected ASN1Object()
```
    Empty default constructor.
- Method Detail
  - getAsnType
```
public ASN getAsnType()
```
    Returns the ASN.1 type of this ASN.1 object.
    
    Returns:
    
    the ASN.1 type of this ASN.1 object
    
    See Also:
    
    ASN
  - indefiniteLength
```
public boolean indefiniteLength()
```
    Returns whether this ASN1Object will be encoded by using the definite or indefinite encoding method.
    Indefinite length encoding is indicated by the length octet 0x80, and the data octets are concluded by two consecutive octets of all zero (0x00 0x00). The indefinite length encoding method only can be used along with the encoding of contsructed ASN.1 objects. Primitive together with indefinite length encoding is forbidden since wrong encoding results would be prodruced anytime when two consecutive zero octets are included within the data stream.
    
    Returns:
    
    true, if indefinite length encoding is used, false otherwise
  - setIndefiniteLength
```
public void setIndefiniteLength(boolean indefiniteLength)
```
    Switches indefinite length encoding on or off for this ASN1Object.
    Indefinite length encoding is indicated by the length octet 0x80, and the data octets are concluded by two consecutive octets of all zero (0x00 0x00). The indefinite length encoding method only can be used along with the encoding of contsructed ASN.1 objects. Primitive together with indefinite length encoding is forbidden since wrong encoding results would be prodruced anytime when two consecutive zero octets are included within the data stream.
    When dealing with large amounts of data, the indefinite length method shall be used for allowing to split the encoding in small chunks that can be handled within the memory.
    
    Parameters:
    
    indefiniteLength - true, if this ASN1Object shall be encoded using the indefinite length encoding method, false if it shall be encoded with definite length
  - setIndefiniteRecursive
```
public void setIndefiniteRecursive(boolean indefinite)
```
    Recursively changes the ASN.1 encoding of this object and all objects it contains to use indefinite length or definite length encoding.
    
    Parameters:
    
    indefinite - if true this ASN1Object is encoded using indefinite length, if false, it is encoded using definite length
  - setAutomaticRepair
```
public void setAutomaticRepair(boolean repair)
```
    Enables or disables the automatic repair of improperly DER encoded ASN.1 during encoding for this ASN.1 object.
    Certain ASN.1 objects do not strictly enforce all the DER encoding rules outlined in ITU-T X.690. Instead, they will permit certain invalid DER encodings to be decoded, but then provide the ability to automatically repair the problem upon re-encoding. One example of such behaviour is the INTEGER which permits violation of ITU-T X.690 8.3.2 during decoding, and provides the ability to repair this violation during encoding.
    
    By default, automatic repair is enabled for all ASN.1 types
    
    Parameters:
    
    repair - true to enable automatic repair; false to disable automatic repair
  - setAutomaticRepairRecursive
```
public void setAutomaticRepairRecursive(boolean repair)
```
    Enables or disables the automatic repair of improperly DER encoded ASN.1 during encoding for this ASN.1 object and all other ASN.1 objects it may contain.
    For ASN.1 objects that represent structured types (SEQUENCE, SET, ...), this can be used to enable/disable automatic repair for every ASN.1 object it contains.
    
    Parameters:
    
    repair - true to enable automatic repair; false to disable automatic repair
  - isConstructed
```
public boolean isConstructed()
```
    Returns whether this ASN1Object is constructed or primitive.
    
    Returns:
    
    true, if constructed, false otherwise
  - addEncodeListener
```
public void addEncodeListener(EncodeListener encodeListener,
                              int id)
```
    Adds one EncodeListener which wants to be notified when the encoding of this ASN1Object has to be performed. A class that whishes to be registered as EncodeListener for a specific ASN1Object has to implement the EncodeListener interface. The actual registration for encoding notification is done when calling this addEncodeListener method on a particular ASN1Object. Later, when the encoding of the current ASN1Object is performed, the program execution jumps to the encodeCalled method of each registrated EncodeListener implementation for querying for information that is needed for the encoding procedure. After having executed the encodeCalled methods of all registered listeners, the particular encode method of the ASN1Object is executed.
    
    Parameters:
    
    encodeListener - the EncodeListener
    
    id - an id which lets listeners distinguish between objects
    
    See Also:
    
    EncodeListener
  - encodeObject
```
protected void encodeObject(java.io.OutputStream os,
                            boolean streamMode)
                     throws java.io.IOException
```
    DER encodes this ASN1Object and writes the output to the specified OutputStream. This method also calls any registered EncodeListener before the encode method of the sub-class is called.
    
    Parameters:
    
    os - the output stream to which to write the data
    
    streamMode - true, if the contents of this ASN1Object shall be written directly to the output stream and the encoding shall not built within memory in reverse order
    
    Throws:
    
    java.io.IOException - if there is a problem while writing to the output stream or an EncodeListener throws an exception
  - isA
```
public boolean isA(ASN type)
```
    Tests if this object is an instance of given ASN.1 type.
    
    Parameters:
    
    type - the ASN.1 type this object should be checked of being an instance of
    
    Returns:
    
    true if this object is an instance of the given ASN.1 type false otherwise
    
    See Also:
    
    ASN
  - getComponentAt
```
public ASN1Object getComponentAt(int index)
                          throws CodingException
```
    Throws a CodingException. Since querying for a particular component only is reasonable when dealing with a constructed ASN.1 object, and any constructed ASN.1 object has to extend the ConstructedType class, use the getComponentAt method of that class for obtaining some specific component of a constructed ASN.1 object.
    
    Parameters:
    
    index - the position of the component to be obtained from the constructed ASN.1 object; not used
    
    Returns:
    
    nothing, since this method only throws a CodingException
    
    Throws:
    
    CodingException - since not supported for this class
    
    See Also:
    
    ConstructedType
  - countComponents
```
public int countComponents()
                    throws CodingException
```
    Throws a CodingException. Since querying for the number of components only is reasonable when dealing with a constructed ASN.1 object, and any constructed ASN.1 object has to extend the ConstructedType class, use the countComponents() method of that class for obtaining the number of components included into a constructed ASN.1 object.
    
    Returns:
    
    nothing, since this method only throws a CodingException
    
    Throws:
    
    CodingException - since not supported for this class
    
    See Also:
    
    ConstructedType
  - addComponent
```
public void addComponent(ASN1Object component)
                  throws CodingException
```
    Throws a CodingException. Since adding a component only is reasonable when dealing with a constructed ASN.1 object, and any constructed ASN.1 object has to extend the ConstructedType class, use the addComponent method of that class for adding a component to a constructed ASN.1 object.
    
    Parameters:
    
    component - the ASN1Object component to be added; not used
    
    Throws:
    
    CodingException - since not supported for this class
    
    See Also:
    
    ConstructedType
  - getValue
```
public abstract java.lang.Object getValue()
```
    Returns the value of this ASN1Object. Implemented by any subclass.
    
    Returns:
    
    the value of this ASN1Object
  - setValue
```
public abstract void setValue(java.lang.Object object)
```
    Sets the value of this ASN1Object. Implemented by any subclass.
    
    Parameters:
    
    object - the value to be set for this ASN1Object
  - encode
```
protected abstract void encode(java.io.OutputStream os)
                        throws java.io.IOException
```
    DER encodes this ASN1Object and writes the result to the given output stream. Implemented by any subclass. This is a protected method and will not be used by an application for DER encoding an ASN1Object. An application will call one of the encode methods of the DerCoder class for performing the encoding. The corresponding encode method of the particular ASN1Object will be called internally from the DerCoder.
    
    Parameters:
    
    os - the output stream to which to write the DER encoded data
    
    Throws:
    
    java.io.IOException - if an I/O error occurs while writing to the stream
  - decode
```
protected abstract void decode(int length,
                               java.io.InputStream is)
                        throws CodingException,
                               java.io.IOException
```
    Decodes an ASN1Object represented by the next length bytes of the given input stream. Implemented by any subclass. The supplied input stream carries DER encoded data. The next length bytes represent the encoding of this ASN1Object to be decoded. If length < 0, the supplied ASN1Object has been encoded by means of the indefinite length encoding method, and so the encoding has to be parsed for two consecutive EOC octets of all zeros. Indefinite length encoding only is appropriate (and therefore allowed) for constructed ASN.1 types.
    This is a protected method and will not be used by an application for DER decoding an encoded ASN1Object. 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) obtained by the particular ASN1Object and internally calls the decode method of that ASN1Object.
    
    Parameters:
    
    length - the already decoded length, i.e. number of the bytes representing the ASN1Object to be decoded
    
    is - the InputStream supplying the encoded ASN1Object
    
    Throws:
    
    CodingException - if the ASN1Object can not be decoded
    
    java.io.IOException - if an error occurs while reading from the stream
  - isStringType
```
public boolean isStringType()
```
    Asks if this ASN1Object represents a String type.
    
    Returns:
    
    true if this ASN1Object is a String type, false if not
  - toString
```
public java.lang.String toString()
```
    Returns a string that represents the contents of this ASN1Object. All subclasses use this method for a common output form.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation

Class ASN1Object

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

constructed

indefinite_length

asnType

isStringType

encode_listener

stream_mode

Constructor Detail

ASN1Object

Method Detail

getAsnType

indefiniteLength

setIndefiniteLength

setIndefiniteRecursive

setAutomaticRepair

setAutomaticRepairRecursive

isConstructed

addEncodeListener

encodeObject

isA

getComponentAt

countComponents

addComponent

getValue

setValue

encode

decode

isStringType

toString