iaik.asn1

Class DerCoder

java.lang.Object

iaik.asn1.DerCoder

public final class DerCoder
extends java.lang.Object

This class provides DER en/decoding utility for arbitrary ASN.1 structures. Since this class only contains static methods it never will be directly instantiated.
This class provides two methods to be used for DER encoding ASN.1 objects ( encode respectively encodeTo(ASN1Object, OutputStream)) and two methods for performing the reverse procedure of decoding DER encoded ASN.1 objects ( decode(byte[]) respectively decode(InputStream)). Regardless of having to encode an ASN.1 object or decoding a given encoding, an application has to decide whether to write/read the encoding to/from a byte array or to/from a stream.

• Encoding procedure The DerCoder class provides two static methods for DER encoding an ASN.1 object. The first one, to facilitate length determination internally performs the encoding in reverse order and returns the encoding result as byte array:

  public static byte[] encode(ASN1Object object)

  Since this method performs whole the DER encoding within the memory, it shall not be used for the encoding of very large ASN.1 structures.

  The second encoding method performs the encoding in the right order and writes the encoding immediately to an output stream:

  public static void encodeTo(ASN1Object object, OutputStream os)

  This method shall be used for encoding large ASN.1 structures. Since this method writes the encoded data to the stream immediately as it is encoded, the length of the encoding result is not known in advance, and therefore the indefinite length encoding method has to be used:

  • first the identifier tag of the ASN.1 object to be encoded has to be written to the stream
  • indefinite length encoding is denoted by writing the indefinite length encoding tag 0x80
  • now the content of the ASN.1 object is written to the stream
  • indefinite length encoding is closed by two consecutive EOC octets: 0x00:0x00
  In general, large ASN.1 objects that have to be encoded to a stream will contain one (or more) ASN.1 OCTET_STRING component(s) carrying (a) large data volume(s). There are two different ways an octet string may be encoded:
  • If the length of the raw data to be encoded is known in advance the definite primitive method is used for DER encoding an octet string. In this way, the encoding is initialized by the primitive octet string identifier tag 0x04, followed by the length encoding, and concluded by the data bytes:

     0x04 <length> <data>
     

    Consider, for example the five data bytes 0x01 0xAB 0x23 0x7F 0xCA and their primitive definite encoding to:

     0x04 0x05 0x01 0xAB 0x23 0x7F 0xCA
     

  • However, the first method may not be suitable for large data volumes when the data length is not known in advance. Since an octet string is not allowed to be indefinite primitive encoded (how to distinguish EOC octets from two adjacent 0x00 0x00 data bytes?), a BER encoding variant has to be used where whole the octet string is encoded as indefinite constructed octet string, being composed of a certain number of rather small primitive definite encoded octet string components. The length of each primitive component shall be set to a predefined blocksize:

     0x24 0x80
               0x04 <blocksize> <data>
               0x04 <blocksize> <data>
               0x04 <blocksize> <data>
                    ...
     0x00 0x00
     

    Of course, the last block may be shorter than the defined blocksize!
    So, the example from above may be encoded as:

     0x24 0x80
               0x04 0x02 0x01 0xAB
               0x04 0x02 0x23 0x7F
               0x04 0x01 0xCA
     0x00 0x00
     

  For realizing the first (definite primitive) method to encode an octet string, either the encode or the encodeTo method may be used, depending on whether the encoding shall be written to byte array or to an output stream. The second (indefinite primitive) octet string encoding method only can be realized when using the encodeTo method. The blockSize already has to be specified when creating the OCTET_STRING, e.g. for blocksize 1000:

   OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
   DerCoder.encodeTo(seq, new FileOutputStream("large.der");
   

  When using an OCTET_STRING to be indefinite constructed encoded as component of another structured ASN.1 object (e.g. SEQUENCE, SET), this wrapping object also has to be enforced to be indefinite encode by setting the indefiniteLength qualifier to true:

   SEQUENCE seq = new SEQUENCE();
   OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
   seq.addComponent(os);
   seq.setIndefiniteLength(true);
   DerCoder.encodeTo(seq, new FileOutputStream("large.der");
   

  In the same way, when context specific tagging an OCTET_STRING to be indefinite constructed encoded, the superior CON_SPEC has to be forced to be indefinite encoded, too, e.g.:

   SEQUENCE seq = new SEQUENCE();
   OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
   CON_SPEC con_spec = new CON_SPEC(0, os, implicitlyTagged);
   seq.addComponent(con_spec);
   con_spec.setIndefiniteLength(true);
   seq.setIndefiniteLength(true);
   ...
   DerCoder.encodeTo(seq, new FileOutputStream("large.der");
   

  Note that, of course, also the encode method may be used for encoding structured ASN.1 objects like sequences or sets with the indefinite length encoding variant. However, for indefinite constructed encoding an octet string, the encodeTo method has to be used.

• Decoding procedure The DerCoder class provides two static methods for decoding an DER encoded ASN.1 object, either supplied as byte array or from an input stream:

  public static ASN1Object decode(byte[] coding)

  public static ASN1Object decode(InputStream in)

Both methods are able to decode arbitrary DER encoded data as long as the appertaining ASN.1 structure can be parsed within the memory. For decoding pre-known structures of any length, use the DerInputStream decoding utility.

Version:

File Revision 42

See Also:

ASN1Object, DerInputStream

Method Summary

Methods

Modifier and Type	Method and Description
static ASN1Object	decode(byte[] coding) Creates an ASN.1 object from the DER encoded version.
static ASN1Object	decode(byte[] coding, boolean ensureDER) Creates an ASN.1 object from the DER encoded version.
static ASN1Object	decode(java.io.InputStream is) Creates an ASN.1 object from the DER encoded version.
static ASN1Object	decode(java.io.InputStream is, boolean ensureDER) Creates an ASN.1 object from the DER encoded version.
static byte[]	encode(ASN1Object object) DER encodes the given ASN.1 object and returns the coding as a byte array.
static void	encodeTo(ASN1Object object, java.io.OutputStream os) Encodes the given ASN1Object and writes the coding directly to the specified OutputStream.
protected static void	encodeTo(ASN1Object object, java.io.OutputStream os, boolean implicitlyTagged) The internal method additionally allows to specify whether the supplied ASN1Object has to be implicitly tagged.

Methods inherited from class java.lang.Object

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

Method Detail

encodeTo

public static void encodeTo(ASN1Object object,
            java.io.OutputStream os)
                     throws java.io.IOException

Encodes the given ASN1Object and writes the coding directly to the specified OutputStream. This method avoids building up the coding in the memory because large OCTET STRINGs often cause problems. For that reason, the indefinite constructed encoding method shall be used for BER - not DER - encoding octet strings that carry large amounts of data.

Indefinite length encoding works this way:

• write the tag
• write 0x80 : indefinite length encoding
• write content : the content of the object
• write 0x00:0x00 : to mark the end of indefinite length

Since an octet string is not allowed to be indefinite primitive encoded (how to distinguish EOC octets from two adjacent 0x00 0x00 data bytes?), a BER encoding variant has to be used where whole the octet string is encoded as indefinite constructed octet string, being composed of a certain number of rather small primitive definite encoded octet string components. The length of each primitive component shall be set to a predefined blocksize. Following this, the data bytes are read block by block according to the specified block size. When actually reading some block it immediately is encoded and written to the given output stream. In this way, the number of bytes actually handled within the memory can be kept within reasonable bounds. The whole encoding would be indefinite and constructed giving an octet string that consists of a certain number of definite primitive encoded octet strings:

 0x24 0x80
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
           0x04 <blocksize> <data>
                ...
 0x00 0x00
 

Of course, the last block may be shorter than the defined blocksize!
For example, the five data bytes 0x01 0xAB 0x23 0x7F 0xCA may be encoded as:

 0x24 0x80
           0x04 0x02 0x01 0xAB
           0x04 0x02 0x23 0x7F
           0x04 0x01 0xCA
 0x00 0x00
 

The blockSize already has to be specified when creating the OCTET_STRING, e.g. for blocksize 1000:

 OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
 DerCoder.encodeTo(seq, new FileOutputStream("large.der");
 

When using an OCTET_STRING to be indefinite constructed encoded as component of another structured ASN.1 object (e.g. SEQUENCE, SET), this wrapping object also has to be enforced to be indefinite encode by setting the indefiniteLength qualifier to true:

 SEQUENCE seq = new SEQUENCE();
 OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
 seq.addComponent(os);
 seq.setIndefiniteLength(true);
 DerCoder.encodeTo(seq, new FileOutputStream("large.der");
 

In the same way, when context specific tagging an OCTET_STRING to be indefinite constructed encoded, the superior CON_SPEC has to be forced to be indefinite encoded, too, e.g.:

 SEQUENCE seq = new SEQUENCE();
 OCTET_STRING os = new OCTET_STRING(new FileInputStream("large.object", 1000);
 CON_SPEC con_spec = new CON_SPEC(0, os, implicitlyTagged);
 seq.addComponent(con_spec);
 con_spec.setIndefiniteLength(true);
 seq.setIndefiniteLength(true);
 ...
 DerCoder.encodeTo(seq, new FileOutputStream("large.der");
 

For decoding pre-known large ASN.1 objects you may use the DerInputStream utility.

Of course, this encodeTo method also can be used for encoding ASN.1 objects according to the definite primitive encoding practice. Indefinite encoding only will be enforced if the indefiniteLength qualifier of the ASN.1 object to be encoded, is set to true, which may be done by means of the setIndefiniteLength method of the ASN1Object class.

Parameters:

object - the ASN1Object to be DER encoded

os - the OutputStream where the encoding shall be written to

Throws:

java.io.IOException - if an I/O or encoding error occurs

See Also:

OCTET_STRING, SEQUENCE, SET, CON_SPEC, DerInputStream

encodeTo

protected static void encodeTo(ASN1Object object,
            java.io.OutputStream os,
            boolean implicitlyTagged)
                        throws java.io.IOException

The internal method additionally allows to specify whether the supplied ASN1Object has to be implicitly tagged. If implicit tagging shall be used, the tag and length of the underlying ASN.1 object are not encoded.

Parameters:

object - the ASN1Object to be DER encoded

os - the OutputStream where the encoding shall be written to

implicitlyTagged - whether to enforce implicit tagging or not; only can be true if the supplied ASN1Object belongs to a CON_SPEC

Throws:

java.io.IOException - if an I/O or encoding error occurs

encode

public static byte[] encode(ASN1Object object)

DER encodes the given ASN.1 object and returns the coding as a byte array. To facilitate length determination, the encoding algorithm encodes the values in tail recursive order, starting from the last lower level object. For each object - when encoding a structured type, any number of objects may be included - first the inherent value is written to a temporary stream in reverse order. The number of bytes actually written gives the length octet(s) which is(are) written to the temporary stream just behind the content bytes. Finally the identifier octet is written and the stream data is "turned around" to give the right order before returning it as a byte array. Because whole the encoding is done in memory a lot of memory will be needed for encoding large objects. For that reason, the encodeTo method shall be used for encoding large ASN.1 objects.

For enforcing indefinite length encoding, enable the indefiniteLength parameter by means of the setIndefiniteLength method of the ASN1Object class.

Parameters:

object - the ASN1Object to be DER encoded

Returns:

the DER encoded version of the ASN.1 object as byte array

See Also:

ASN1Object

decode

public static ASN1Object decode(byte[] coding)
                         throws CodingException

Creates an ASN.1 object from the DER encoded version. The DER encoded ASN.1 object has to be supplied as a byte array. This method decodes the given encoding and returns the recovered ASN.1 object.

Parameters:

coding - the array containing the DER encoded ASN.1 object

Returns:

the ASN1Object created from the DER encoded ASN.1 object, derived from the given byte array

Throws:

CodingException - if there is an error while decoding

See Also:

ASN1Object

decode

public static ASN1Object decode(byte[] coding,
                boolean ensureDER)
                         throws CodingException

Creates an ASN.1 object from the DER encoded version. The DER encoded ASN.1 object has to be supplied as a byte array. This method decodes the given encoding and returns the recovered ASN.1 object.

If ensureDER is set to true the encoding is checked for compliance with the Distinguished Encoding Rules (DER) according to ITU-T Rec. X.690 (07/2002), sections 10 and 11. Setting ensureDER to true may be done only if absolutely required since checking for DER compliance will cost both, performance and memory.

Parameters:

coding - the array containing the DER encoded ASN.1 object

ensureDER - whether to check the encoding against the Distinguished Encoding Rules (DER) or to accept BER encoding, too

Returns:

the ASN1Object created from the DER encoded ASN.1 object, derived from the given byte array

Throws:

CodingException - if there is an error while decoding

See Also:

ASN1Object

decode

public static ASN1Object decode(java.io.InputStream is)
                         throws CodingException,
                                java.io.IOException

Creates an ASN.1 object from the DER encoded version. The DER encoded ASN.1 object has to be supplied from an InputStream. This method decodes the given encoding and returns the recovered ASN.1 object. This method is able to decode any arbitrary ASN.1 structure, given in its DER encoded format. However, since whole the decoding is performed within the memory, this method may not be suitable for decoding very large ASN.1 object. An application may use the DerInputStream utility for decoding large ASN.1 objects. However, when using the DerInputStream class, the structure of the DER encoded ASN.1 object to be encoded has to be known in advance.

Parameters:

is - the InputStream with the DER encoded ASN.1 object

Returns:

the ASN1Object created from the DER encoded ASN.1 object, derived from the given input stream

Throws:

CodingException - if there occurs an error while decoding

java.io.IOException - if there is an error with the InputStream

See Also:

ASN1Object, DerInputStream

decode

public static ASN1Object decode(java.io.InputStream is,
                boolean ensureDER)
                         throws CodingException,
                                java.io.IOException

Creates an ASN.1 object from the DER encoded version. The DER encoded ASN.1 object has to be supplied from an InputStream. This method decodes the given encoding and returns the recovered ASN.1 object. This method is able to decode any arbitrary ASN.1 structure, given in its DER encoded format. However, since whole the decoding is performed within the memory, this method may not be suitable for decoding very large ASN.1 object. An application may use the DerInputStream utility for decoding large ASN.1 objects. However, when using the DerInputStream class, the structure of the DER encoded ASN.1 object to be encoded has to be known in advance.

If ensureDER is set to true the encoding is checked for compliance with the Distinguished Encoding Rules (DER) according to ITU-T Rec. X.690 (07/2002), sections 10 and 11. Setting ensureDER to true may be done only if absolutely required since checking for DER compliance will cost both, performance and memory.

Parameters:

is - the InputStream with the DER encoded ASN.1 object

ensureDER - whether to check the encoding against the Distinguished Encoding Rules (DER) or to accept BER encoding, too

Returns:

the ASN1Object created from the DER encoded ASN.1 object, derived from the given input stream

Throws:

CodingException - if there occurs an error while decoding

java.io.IOException - if there is an error with the InputStream

See Also:

ASN1Object, DerInputStream