iaik.asn1
Class ASN1

java.lang.Object
  |
  +--iaik.asn1.ASN1

public class ASN1

extends Object

This class is responsible for converting ASN.1 objects between internal (ASN1Object) and external (PEM, DER encoded arrays) representation.

When creating an encoded ASN.1 object from an input stream or from a byte array, the given input data automatically is decoded properly depending on whether it is supplied in DER or PEM encoding format. Supposing, for instance, some DER encoded ASN.1 object supplied as a byte array, first use the ASN1(byte[] array) constructor for obtaining and decoding the data, and subsequently call the toASN1Object method for getting the delivered ASN1Object, e.g.:

 //the byte array supplying the encoding
 byte[] encoding = ...;
 ASN1 asn1 = new ASN1(encoding);
 ASN1Object asn1_object = asn1.toASN1Object();
 

If you are already aware to receive DER encoded data you alternatively may use one of the static decode methods of the DerCoder class. If you expect to deal with large amounts of data, it may be preferable to take advantage of the DerInputStream utility for parsing the incoming data.
When expecting data in PEM format alternatively combinations of the Base64InputStream/Base64Encode and DerInputStream/DerCoder utilities may be used for first Base64 decoding the PEM data, and subsequently DER decoding the result from the first step.

When writing an ASN.1 Object to a byte array by calling the toByteArray method, the data is returned in DER encoded format. It may be preferable to use one of the encode methods of the DerCoder class for performing the DER encoding of some ASN1Object.
For PEM (Base64 DER) encoding DER encoded data, use the Base64Encode method of the iaik.utils.Util class, e.g.:

 //create an ASN1 object from a byte array supplying the data in DER or
 //PEM encoded format:
 ASN1 asn1 = new ASN1(array);
 //Get the internal representation:
 ASN1Object asn1_obj = asn1.toASN1Object();
 //DER encode the ASN1 object
 byte[] der_array = asn1.toByteArray();
 //Base64 encode the DER encoded byte array just created to get the
 //PEM encoding:
 byte[] pem_array = Util.Base64Encode(der_array);
 

Donīt forget the BEGIN - END clauses when writing a PEM message, e.g.:

 PrintWriter pw = new PrintWriter(new FileOutputStream("test.pem"));
 pw.println("-----BEGIN PRIVACY-ENHANCED MESSAGE-----");
 pw.println(new String(pem_array));
 pw.println("-----END PRIVACY-ENHANCED MESSAGE-----");
 

For writing DER encoded data Base64 encoded to a stream, use the Base64OutputStream class.

Version:

File Revision 33

See Also:

ASN1Object, DerCoder, DerInputStream, Base64InputStream, Base64OutputStream

Field Summary

static int	DER Global value for ASN.1 coding format DER.
static int	PEM Global value for ASN.1 coding format PEM.
static String	startLine First line of a file in PEM format.

Constructor Summary

ASN1()
Default constructor.

ASN1(ASN1Object obj)
Creates an ASN1 object from the supplied ASN1Object.

ASN1(byte[] array)
Creates an ASN1 object from a byte array.

ASN1(InputStream is)
Creates an ASN1 object from an InputStream.

Method Summary

void	clearASN1Object() Clear the stored ASN1 object to save memory.
void	clearByteArray() Clear the stored encoding to save memory.
int	countComponents() Returns the number of components in this ASN1 Object.
byte[]	fingerprint() Returns a fingerprint (MD5 Hash of the whole ASN1Object).
ASN1Object	getComponentAt(int index) Returns the ASN1Object at the given index if the ASN1Object represented by this ASN1 object is of constructed type (e.g.
byte[]	getFirstObject() Returns the first SEQUENCE of a SEQUENCE ASN1 object as DER encoded byte array.
int	getFormat() Returns the format: ASN1.DER, ASN1.PEM.
static String	print(ASN1Object o) Returns a string that represents the contents of the supplied ASN1Object.
ASN1Object	toASN1Object() Returns the ASN1Object represented by this ASN1 object.
byte[]	toByteArray() Returns the ASN1Object represented by this class as DER encoded byte array.
String	toString() Returns a string that represents the contents of this ASN1Object.
void	writeTo(OutputStream os) DER encodes and writes the ASN1Object represented by this class to an OutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

DER

public static final int DER

Global value for ASN.1 coding format DER.

PEM

public static final int PEM

Global value for ASN.1 coding format PEM.

startLine

public static final String startLine

First line of a file in PEM format.

Constructor Detail

ASN1

public ASN1()

Default constructor. Creates an empty object.

ASN1

public ASN1(ASN1Object obj)
     throws CodingException

Creates an ASN1 object from the supplied ASN1Object. Use this constructor for preparing the supplied ASN1Object for DER encoding. This constructor already performs the DER encoding of the supplied ASN1Object and will raise a CodingException if the encoding procedure fails. The encoding may be obtained by calling the toByteArray or writeTo(OutputStream os) method.

You alternatively may use one of the encode methods of the DerCoder class for DER encoding an ASN1Object.

Parameters:

obj - the ASN1Object to be DER encoded

Throws:

CodingException - if the ASN1Object could not be DER encoded

ASN1

public ASN1(InputStream is)
     throws IOException,
            CodingException

Creates an ASN1 object from an InputStream.

The data can be in DER or PEM format. To decide if the data is DER or PEM encoded this method uses the first byte of data: If the first byte has the value: 65-77, 103-122 the format is PEM. Otherwise the format is DER. DER uses the tags 1-24, 48, 49, and 128-. These values PEM encoded result in (65-77, 103-122) and thatīs why the algorithm should work :).

Use the toASN1Object() method for obtaining the ASN1Object decoded from the supplied input stream data.

Parameters:

is - the InputStream containing the encoded data

Throws:

IOException - if there is a problem with the InputStream

CodingException - if the object could not be decoded

ASN1

public ASN1(byte[] array)
     throws CodingException

Creates an ASN1 object from a byte array. The data can be in DER or PEM format.

Use the toASN1Object() method for obtaining the ASN1Object decoded from the supplied byte array data.

Parameters:

array - the byte array containing encoded ASN.1 object

Throws:

CodingException - if the object could not be decoded

Method Detail

getComponentAt

public ASN1Object getComponentAt(int index)
                          throws CodingException

Returns the ASN1Object at the given index if the ASN1Object represented by this ASN1 object is of constructed type (e.g. SEQUENCE, SET).

Parameters:

index - the position of the component to be obtained from the constructed ASN.1 object

Returns:

the ASN1Object at that position

Throws:

CodingException - if this ASN1Object is not of constructed type or the index is illegal

See Also:

ConstructedType

countComponents

public int countComponents()
                    throws CodingException

Returns the number of components in this ASN1 Object. Only useful if the ASN1Object represented by this ASN1 object is of constructed type (e.g. SEQUENCE, SET).

Returns:

the number of components in this ASN1Object

Throws:

CodingException - if this ASN1Object does not support countComponents()

getFirstObject

public byte[] getFirstObject()
                      throws CodingException

Returns the first SEQUENCE of a SEQUENCE ASN1 object as DER encoded byte array.

This method only may be used for a SEQUENCE ASN1 object which contains some other SEQUENCE, e.g:

 asn1SEQ ::=  SEQUENCE  {
   field1  subSEQ,
     ...
 }

 subSEQ ::= SEQUENCE {
     ...
 }
 

The first sub-sequence is returned as DER encoded byte array. Note that this method searches the raw encoding for the first sub-sequence. This may be useful in situations when doing some cryptographic operation where it is essential that the original encoding format is preserved (e.g. verifying a hash, signature).

A X.509 certificate, for instance, holds the tbsCertificate structure to be verified in its first component:

 Certificate  ::=  SEQUENCE  {
   tbsCertificate       TBSCertificate,
   signatureAlgorithm   AlgorithmIdentifier,
   signature            BIT STRING  }
 

Using getFistObject for extracting the tbsStructure will give the raw DER bytes parsed from the original encoding.

Returns:

the first sub-SEQUENCE as DER encoded byte array

Throws:

CodingException - if there is no sub-SEQUENCE in this SEQUENCE

writeTo

public void writeTo(OutputStream os)
             throws IOException

DER encodes and writes the ASN1Object represented by this class to an OutputStream.

The data written to the given output stream is DER encoded.

Parameters:

os - the output stream to which to write the data

Throws:

IOException - if there an I/O error occurs

getFormat

public int getFormat()

Returns the format: ASN1.DER, ASN1.PEM.

Returns:

the file format

toString

public String toString()

Returns a string that represents the contents of this ASN1Object.

Overrides:

toString in class Object

Returns:

the string representation

print

public static String print(ASN1Object o)

Returns a string that represents the contents of the supplied ASN1Object.

Parameters:

o - the ASN1Object about which information shall be printed

Returns:

the string representation

toByteArray

public byte[] toByteArray()

Returns the ASN1Object represented by this class as DER encoded byte array.

If you want to get a PEM (Base64 DER) encoding of the ASN1 object, call Base64Encode thereby supplying the DER encoded data returned by this method as parameter value, e.g.:

 ASN1 asn1 = ...;
 byte[] der_array = asn1.toByteArray();
 //Base64 encode the DER encoded byte array just created to get the
 //PEM encoding:
 byte[] pem_array = Util.Base64Encode(der_array);
 

Returns:

the ASN1Object as DER encoded byte array

toASN1Object

public ASN1Object toASN1Object()

Returns the ASN1Object represented by this ASN1 object.

Returns:

the ASN1Object

clearASN1Object

public void clearASN1Object()

Clear the stored ASN1 object to save memory. It is recreated from the encoding when required.

clearByteArray

public void clearByteArray()

Clear the stored encoding to save memory. It is recreated from the ASN1 object when required.

fingerprint

public byte[] fingerprint()

Returns a fingerprint (MD5 Hash of the whole ASN1Object).

Returns:

the fingerprint