org.jasn
Interface Asn1Encoder

All Known Implementing Classes:

BaseBerEncoder, DerEncoder

public interface Asn1Encoder

This interface defines a generic encoder for the marshalling of ASN.1 values.

It provides encoding methods for all the ASN.1 primitive values.

The encoding of a constructed value (SET, SEQUENCE or explicit tagged value) must begin with a call to the encodeSet, encodeSequence or encodeExplicit method that returns an identifier; then, the elements contained in the constructed value must be encoded with their corresponding encode methods. Finally, the endOf method must be invoked with the identifier to terminate the encoding of the constructed value.

All the encoding methods may throw an EncodingException if invalid values are being encoded or if some internal state is not correct. An IOException may also be thrown if an I/O error occured during writing into an output stream specified by some implementation (as it is the case for BER encoders but not for DER encoders).

Author:

Nicolas Vraux

Method Summary

void	encodeAny(byte[] encoded) Encodes an ASN.1 ANY value.
void	encodeBitString(BitString bits) Encodes an ASN.1 BIT STRING value.
void	encodeBitString(byte[] bits) Encodes the specified bytes as an ASN.1 BIT STRING value.
void	encodeBMPString(String s) Encodes an ASN.1 BMPString value.
void	encodeBoolean(boolean b) Encodes an ASN.1 BOOLEAN value.
void	encodeEnumerated(BigInteger e) Encodes an ASN.1 ENUMERATED value.
void	encodeEnumerated(int e) Encodes an ASN.1 ENUMERATED value.
void	encodeEnumerated(long e) Encodes an ASN.1 ENUMERATED value.
int	encodeExplicit(int tag) Indicates that the next ASN.1 value must be encoded with an explicit tag equals to the specified tag value.
void	encodeGeneralizedTime(Calendar date) Encodes the specified date as an ASN.1 GeneralizedTime.
void	encodeGeneralString(String s) Encodes an ASN.1 GeneralString value.
void	encodeGraphicString(String s) Encodes an ASN.1 GraphicString value.
void	encodeIA5String(String s) Encodes an ASN.1 IA5String value.
void	encodeImplicit(int tag) Signals that the next ASN.1 value must be encoded with the specified implicit tag.
void	encodeInteger(BigInteger i) Encodes an ASN.1 INTEGER value.
void	encodeInteger(int i) Encodes an ASN.1 INTEGER value.
void	encodeInteger(long l) Encodes an ASN.1 INTEGER value.
void	encodeNull() Encodes an ASN.1 NULL value.
void	encodeNumericString(String s) Encodes an ASN.1 NumericString value.
void	encodeObjectIdentifier(ObjectIdentifier oid) Encodes an ASN.1 OBJECT IDENTIFIER value.
void	encodeOctetString(byte[] b) Encodes the b.length bytes from the specified byte array as an ASN.1 OCTET STRING.
void	encodeOctetString(byte[] b, int off, int len) Encodes an ASN.1 OCTET STRING consisting of len bytes of the specified byte array starting at offset off.
void	encodePrintableString(String s) Encodes an ASN.1 PrintableString value.
void	encodeReal(double value) Encodes an ASN.1 REAL value.
int	encodeSequence() Starts the encoding of an ASN.1 SEQUENCE.
int	encodeSequenceOf() Starts the encoding of an ASN.1 SEQUENCE OF.
int	encodeSet() Starts the encoding of an ASN.1 SET.
int	encodeSetOf() Starts the encoding of an ASN.1 SET OF.
void	encodeTeletexString(String s) Encodes an ASN.1 TeletexString value.
void	encodeUniversalString(String s) Encodes an ASN.1 UniversalString value.
void	encodeUTCTime(Calendar date) Encodes the specified date as an ASN.1 UTCTime.
void	encodeUTF8String(String s) Encodes an ASN.1 UTF8String value.
void	encodeVideotexString(String s) Encodes an ASN.1 VideotexString value.
void	encodeVisibleString(String s) Encodes an ASN.1 VisibleString value.
void	endOf(int id) Terminates the encoding of the constructed value identified by id.
boolean	isDefaultEncoded() Indicates wether this encoder encodes DEFAULT values.
void	reset() Resets the state of this encoder.

Method Detail

encodeAny

public void encodeAny(byte[] encoded)
               throws IOException

Encodes an ASN.1 ANY value. The specified array of bytes should contains a valid encoded ASN.1 value compatible with this encoder, i.e. if this encoder is a DER encoder, the specified bytes should represent a value that has been DER encoded.

A NullPointerException is thrown if the array is null.

Parameters:

encoded - the array of bytes

Throws:

IOException

encodeBoolean

public void encodeBoolean(boolean b)
                   throws IOException

Encodes an ASN.1 BOOLEAN value.

Parameters:

b - the boolean value to be encoded.

Throws:

IOException

encodeInteger

public void encodeInteger(BigInteger i)
                   throws IOException

Encodes an ASN.1 INTEGER value.

Note: For performance reason, it is recommanded to use the other encodeInteger methods with int or long as parameter (if the value to encode may be represented by a int or a long).

If i is null, a NullPointerException is thrown.

Parameters:

i - the arbitrary-precision integer to be encoded.

Throws:

IOException

See Also:

encodeInteger(int), encodeInteger(long)

encodeInteger

public void encodeInteger(long l)
                   throws IOException

Encodes an ASN.1 INTEGER value.

Parameters:

l - the number to be encoded.

Throws:

IOException

encodeInteger

public void encodeInteger(int i)
                   throws IOException

Encodes an ASN.1 INTEGER value.

Parameters:

i - the number to be encoded.

Throws:

IOException

encodeBitString

public void encodeBitString(BitString bits)
                     throws IOException

Encodes an ASN.1 BIT STRING value.

If bits is null, a NullPointerException is thrown.

Parameters:

bits - a BitString representing the sequence of bits to be encoded.

Throws:

IOException

encodeBitString

public void encodeBitString(byte[] bits)
                     throws IOException

Encodes the specified bytes as an ASN.1 BIT STRING value.

If bits is null, a NullPointerException is thrown.

Parameters:

bits - an array of bytes representing the sequence of bits to be encoded.

Throws:

IOException

encodeOctetString

public void encodeOctetString(byte[] b,
                              int off,
                              int len)
                       throws IOException

Encodes an ASN.1 OCTET STRING consisting of len bytes of the specified byte array starting at offset off.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Parameters:

b - the byte array containing the bytes to be encoded.

off - the start offset in the byte array.

len - the number of bytes to encode.

Throws:

IOException

encodeOctetString

public void encodeOctetString(byte[] b)
                       throws IOException

Encodes the b.length bytes from the specified byte array as an ASN.1 OCTET STRING.

If b is null, a NullPointerException is thrown.

Parameters:

b - the byte array to be encoded.

Throws:

IOException

See Also:

encodeOctetString(byte[],int,int)

encodeNull

public void encodeNull()
                throws IOException

Encodes an ASN.1 NULL value.

Throws:

IOException

encodeObjectIdentifier

public void encodeObjectIdentifier(ObjectIdentifier oid)
                            throws IOException

Encodes an ASN.1 OBJECT IDENTIFIER value.

If oid is null, a NullPointerException is thrown.

Parameters:

oid - the ObjectIdentifier to encode.

Throws:

IOException

encodeReal

public void encodeReal(double value)
                throws IOException

Encodes an ASN.1 REAL value.

Parameters:

value - the number to be encoded.

Throws:

IOException

encodeEnumerated

public void encodeEnumerated(BigInteger e)
                      throws IOException

Encodes an ASN.1 ENUMERATED value.

Note: This method should be only used in the rare case where the ENUMERATED value to encode cannot be hold in a int or a long. Otherwise the encodeEnumerated methods with int or long parameter should be used.

Parameters:

e - the ENUMERATED value represented as a abitrary-precision integer.

Throws:

IOException

See Also:

encodeEnumerated(int), encodeEnumerated(long)

encodeEnumerated

public void encodeEnumerated(int e)
                      throws IOException

Encodes an ASN.1 ENUMERATED value.

Parameters:

e - the ENUMERATED value to encode.

Throws:

IOException

encodeEnumerated

public void encodeEnumerated(long e)
                      throws IOException

Encodes an ASN.1 ENUMERATED value.

Parameters:

e - the ENUMERATED value to encode.

Throws:

IOException

encodeUTF8String

public void encodeUTF8String(String s)
                      throws IOException

Encodes an ASN.1 UTF8String value.

UTF8String is synonymous with UniversalString but the encoding uses the UTF-8 transformation format described in the RFC 2279.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeNumericString

public void encodeNumericString(String s)
                         throws IOException

Encodes an ASN.1 NumericString value.

The only characters that can appear in a NumericString are the digits (0,1,...,9) and the space character(ASCII code 32).

Parameters:

s - the string value to encode.

Throws:

IOException

encodePrintableString

public void encodePrintableString(String s)
                           throws IOException

Encodes an ASN.1 PrintableString value.

The authorized characters in a PrintableString are listed below:

 Name              Graphic
 ---------------   -----------
 Capital letters   A, B, ... Z
 Small letters     a, b, ... z
 Digits            0, 1, ... 9
 Space             (space)
 Apostrophe        '
 Left Parenthesis  (
 Right Parenthesis )
 Plus sign         +
 Comma             ,
 Hyphen            -
 Full stop         .
 Solidus           /
 Colon             :
 Equal sign        =
 Question mark     ?
 

Parameters:

s - the string value to encode.

Throws:

IOException

encodeTeletexString

public void encodeTeletexString(String s)
                         throws IOException

Encodes an ASN.1 TeletexString value.

A TeletexString (or T.61) is a string of multibyte character primarily used for European languages. It uses combining diacritical marks and base characters to represent accented characters, e.g. "a with accute accent" is represented as "accute accent" followed by "a". This is similar to Unicode, except that in Unicode, the accents come after the base character. Also unlike Unicode, the possible combinations of base characters and diacritics is fixed.

A TeletexString must contains characters from the following character sets defined in the ISO 2375:

87, 102, 103, 106, 107 + SPACE + DELETE.

The ITU-T Rec. X.680 has added the following character sets:
6, 126, 144, 150, 153, 156, 164, 165, 168

Parameters:

s - the string value to encode.

Throws:

IOException

encodeVideotexString

public void encodeVideotexString(String s)
                          throws IOException

Encodes an ASN.1 VideotexString value.

The ASN.1 VideotexString type is support multibyte characters used by video text system like the french minitel. VideotextString is deprecated and should not be used anymore.

A VideotexString must contains characters from the following character sets defined in the ISO 2375:

1, 13, 72, 73, 87, 89, 102, 108, 126, 128, 129, 144, 150, 153, 164, 165, 168 + SPACE + DELETE.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeIA5String

public void encodeIA5String(String s)
                     throws IOException

Encodes an ASN.1 IA5String value.

The characters allowed in an IA5String are:
SPACE + DELETE + all characters defined in the register 6 and all control characters defined in the register 1 (i.e. the the ASCII zone of Unicode).

Parameters:

s - the string value to encode.

Throws:

IOException

encodeUTCTime

public void encodeUTCTime(Calendar date)
                   throws IOException

Encodes the specified date as an ASN.1 UTCTime.

Parameters:

date - the date to encode.

Throws:

IOException

encodeGeneralizedTime

public void encodeGeneralizedTime(Calendar date)
                           throws IOException

Encodes the specified date as an ASN.1 GeneralizedTime.

Parameters:

date - the date to encode.

Throws:

IOException

encodeGraphicString

public void encodeGraphicString(String s)
                         throws IOException

Encodes an ASN.1 GraphicString value.

The characters allowed in a GraphicString are SPACE + all characters defined in all G sets.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeVisibleString

public void encodeVisibleString(String s)
                         throws IOException

Encodes an ASN.1 VisibleString value.

The characters allowed in a VisibleString are:
SPACE + all characters defined in the register 6 (i.e. the visible characters in the ASCII zone of Unicode).

Note: The CCITT Rec. X.208 (ancestor of X.680) referenced the register 2. The main difference is that the register 2 defines some diaresis characters that may be combined with BACKSPACE and letter to create accents.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeGeneralString

public void encodeGeneralString(String s)
                         throws IOException

Encodes an ASN.1 GeneralString value.

The characters allowed in a GeneralString are SPACE + DELETE + all characters defined in all G sets and all C sets.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeUniversalString

public void encodeUniversalString(String s)
                           throws IOException

Encodes an ASN.1 UniversalString value.

A UniversalString comprises the characters defined in the ISO10646-1 standard or in the Unicode Standard. It is a set of fixed-length characters: each character of the UniversalString type encoded on 4 bytes has only one possible interpretation.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeBMPString

public void encodeBMPString(String s)
                     throws IOException

Encodes an ASN.1 BMPString value.

BMPString is a subtype of UniversalString that models the Basic Multilingual Plane (the first 64K-2 cells) of ISO/IEC 10646-1.

Parameters:

s - the string value to encode.

Throws:

IOException

encodeImplicit

public void encodeImplicit(int tag)
                    throws IOException

Signals that the next ASN.1 value must be encoded with the specified implicit tag.

This method may be invoked many time with different implicit tags before invoking the subsequent encoding method, but only the first encodeImplicit method has an effect and all the other tags will be ignored. In other words, the following statements

 enc.encodeImplicit(Tags.makeTag(Tags.CONTEXT, 5));
 ...
 enc.encodeImplicit(Tags.makeTag(Tags.CONTEXT, 7));
 enc.encodeInteger(124);
 

are equivalent to

 enc.encodeImplicit(Tags.makeTag(Tags.CONTEXT, 5));
 enc.encodeInteger(124);
 

This tag reduction mechanism is useful for encoding ASN.1 type like

 Type1 ::= [APPLICATION 2] IMPLICIT INTEGER
 Type2 ::= [APPLICATION 5] IMPLICIT Type1
 

where the code used to encode value of type Type2 looks like

 enc.encodeImplicit(Tags.makeTag(Tags.APPLICATION, 5));
 enc.encodeImplicit(Tags.makeTag(Tags.APPLICATION, 2));
 enc.encodeInteger();
 

Parameters:

tag - the implicit tag used to encode the next ASN.1 value.

Throws:

IOException

encodeExplicit

public int encodeExplicit(int tag)
                   throws IOException

Indicates that the next ASN.1 value must be encoded with an explicit tag equals to the specified tag value.

Explicit tags create a separate (tag, length, value) triplet where the tagged element is encoded as value.
This method must be called before the ASN.1 value is encoded; then the value itself is handled as usual. Finally, the endOf method must be invoked to terminate the explicitly encoding.

The encoding of the following ASN.1 type

 version [0] EXPLICIT Version
 

looks like:

 int id = enc.encodeExplicit(Tags.makeTag(Tags.CONTEXT, 0));
    enc.encodeInteger(version);
 dec.endOf(id);
 

Parameters:

tag - the explicit tag of the next encoded ASN.1 value. The tag must be a valid tag such as one that has been created with the Tags.createTag(int, int) method.

Returns:

a sequence identifier that must be passed to the endOf method to terminate the encoding of the explicit tagging.

Throws:

IOException

See Also:

endOf(int), Tags.createTag(int, int)

encodeSequence

public int encodeSequence()
                   throws IOException

Starts the encoding of an ASN.1 SEQUENCE.

An ASN.1 SEQUENCE is an ordered collection of various data element. The decoding of a SEQUENCE must always start with this method; then the elements defined in the SEQUENCE should be decoded with their corresponding decode methods. Finally, the endOf method must be invoked to terminate the decoding of the SEQUENCE.

The returned int value must be passed to the endOf method that then checks if the current nesting and the passed int do match.

The code samples below show the decoding of two nested sequences. The corresponding ASN.1 definition is:

 SEQUENCE {
    s IA5String,
    a SEQUENCE {
        i INTEGER
    }
 }
 

 int id1 = enc.encodeSequence();
     enc.decodeIA5String("Organization");
     int id2 = enc.encodeSequence();
         enc.encodeInteger(124);
     enc.endOf(id2);
 enc.endOf(id1);
 

Returns:

an identifier for the SEQUENCE that must be passed to the endOf method to terminate the encoding of the SEQUENCE.

Throws:

IOException

encodeSequenceOf

public int encodeSequenceOf()
                     throws IOException

Starts the encoding of an ASN.1 SEQUENCE OF.

An ASN.1 SEQUENCE OF is an ordered collection of data element of the same type. The encoding of a SEQUENCE OF must always start with this method; then the elements defined in the SEQUENCE OF should be encoded with their corresponding encode methods. Finally, the endOf method must be invoked to terminate the encoding of the SEQUENCE OF.

The returned int value must be passed to the endOf method that then checks if the current nesting and the passed int do match.

The code samples below show the encoding of SEQUENCE OF. The corresponding ASN.1 definition is:

 MySequence ::= SEQUENCE OF PrintableString
 

 List mySequence = ...; // contains a list of String
 

 int id = enc.encodeSequenceOf();
 Iterator it = mySequence.iterator();
 while (it.hasNext()) {
     enc.encodePrintableString((String)it.next());
 }
 

 enc.endOf(id);
 

Returns:

a identifier that must be passed to the endOf method to terminate the decoding of the SEQUENCE OF.

Throws:

IOException

encodeSet

public int encodeSet()
              throws IOException

Starts the encoding of an ASN.1 SET.

An ASN.1 SET is an unordered collection of various data element. The encoding of a SET must always start with this method; then the elements defined in the SET should be encoded with their corresponding encode methods. Finally, the endOf method must be invoked to terminate the encoding of the SET.

The returned int value must be passed to the endOf method that then checks if the current nesting and the passed int do match.

The code samples below show the decoding of two nested sequences. The corresponding ASN.1 definition is:

 SET {
    s IA5String,
    a SET {
        i INTEGER
    }
 }
 

 int id1 = enc.encodeSet();
     enc.decodeIA5String("Organization");
     int id2 = enc.encodeSet();
         enc.encodeInteger(124);
     enc.endOf(id2);
 enc.endOf(id1);
 

Returns:

a identifier that must be passed to the endOf method to terminate the decoding of the SET.

Throws:

IOException

encodeSetOf

public int encodeSetOf()
                throws IOException

Starts the encoding of an ASN.1 SET OF.

An ASN.1 SET OF is an unordered collection of data element of the same type. The encoding of a SET OF must always start with this method; then the elements defined in the SET OF should be encoded with their corresponding encode methods. Finally, the endOf method must be invoked to terminate the encoding of the SET OF.

The returned int value must be passed to the endOf method that then checks if the current nesting and the passed int do match.

The code samples below show the encoding of SET OF. The corresponding ASN.1 definition is:

 MySet ::= SET OF PrintableString
 

 Set mySet = ...; // contains a set of String
 

 int id = enc.encodeSetOf();
 Iterator it = mySet.iterator();
 while (it.hasNext()) {
     enc.encodePrintableString((String)it.next());
 }
 

 enc.endOf(id);
 

Returns:

a identifier that must be passed to the endOf method to terminate the decoding of the SET OF.

Throws:

IOException

endOf

public void endOf(int id)
           throws IOException

Terminates the encoding of the constructed value identified by id.

Parameters:

id - the reference to a constructed value.

Throws:

EncodingException - if the specified identifier doesn't refer any constructed value.

IOException

isDefaultEncoded

public boolean isDefaultEncoded()

Indicates wether this encoder encodes DEFAULT values.

DEFAULT values are optional values in

Returns:

true if this encoder encodes DEFAULT values.

reset

public void reset()

Resets the state of this encoder. This method should normally be called if some error have been thrown during encoding.