iaik.asn1

Class ASN1Object

java.lang.Object

iaik.asn1.ASN1Object

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

ASN1String, BIT_STRING, BOOLEAN, ConstructedType, EncodedASN1Object, ENUMERATED, GeneralizedTime, INTEGER, NULL, ObjectID, UTCTime

public abstract class ASN1Object
extends java.lang.Object
implements java.lang.Cloneable

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 divided 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.

Version:

File Revision 25

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.

Method Summary

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.
java.lang.Object	clone() Returns a clone of this ASN1Object.
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	setIndefiniteLength(boolean indefiniteLength) Switches indefinite length encoding on or off for this ASN1Object.
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

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

clone

public java.lang.Object clone()

Returns a clone of this ASN1Object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this ASN1Object

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

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