ASN1 (6.0 API Documentation)

java.lang.Object
- iaik.asn1.ASN1

All Implemented Interfaces:

java.lang.Cloneable
```
public class ASN1
extends java.lang.Object
implements java.lang.Cloneable
```
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 40

See Also:
ASN1Object, DerCoder, DerInputStream, Base64InputStream, Base64OutputStream

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DER` Global value for ASN.1 coding format DER.
`static int`	`PEM` Global value for ASN.1 coding format PEM.
`static java.lang.String`	`startLine` First line of a file in PEM format.

Constructor Summary

Constructors
Constructor and Description
`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(java.io.InputStream is)` Creates an ASN1 object from an InputStream.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearASN1Object()` Clear the stored ASN1 object to save memory.
`void`	`clearByteArray()` Clear the stored encoding to save memory.
`java.lang.Object`	`clone()` Returns a clone of this ASN1 object.
`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 java.lang.String`	`print(ASN1Object o)` Returns a string that represents the contents of the supplied ASN1Object.
`static byte[]`	`readEncoded(java.io.InputStream is)` Reads the encoding of an ASN.1 object from the given stream.
`ASN1Object`	`toASN1Object()` Returns the ASN1Object represented by this ASN1 object.
`byte[]`	`toByteArray()` Returns the ASN1Object represented by this class as DER encoded byte array.
`byte[]`	`toByteArray(boolean createClone)` Returns the ASN1Object represented by this class as DER encoded byte array.
`java.lang.String`	`toString()` Returns a string that represents the contents of this ASN1Object.
`void`	`writeTo(java.io.OutputStream os)` DER encodes and writes the ASN1Object represented by this class to an OutputStream.

Methods inherited from class java.lang.Object
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.
    
    See Also:
    Constant Field Values
  - PEM
```
public static final int PEM
```
    Global value for ASN.1 coding format PEM.
    
    See Also:
    Constant Field Values
  - startLine
```
public static final java.lang.String startLine
```
    First line of a file in PEM format.
    
    See Also:
    Constant Field Values
- 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(java.io.InputStream is)
     throws java.io.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:
    
    java.io.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
  - readEncoded
```
public static byte[] readEncoded(java.io.InputStream is)
                          throws java.io.IOException,
                                 CodingException
```
    Reads the encoding of an ASN.1 object from the given stream.
    This methods allows to parse an ASN.1 object without keeping the internal ASN.1 structure in memory.
    
    Parameters:
    is - the stream from which to read the encoding
    
    Returns:
    the encoding of the ASN.1 object
    
    Throws:
    
    java.io.IOException - if an error occurs when reading from the stream
    
    CodingException - if a coding error occurs
  - 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(java.io.OutputStream os)
             throws java.io.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:
    
    java.io.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 java.lang.String toString()
```
    Returns a string that represents the contents of this ASN1Object.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    the string representation
  - print
```
public static java.lang.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:
 if (der_array != null) {
   byte[] pem_array = Util.Base64Encode(der_array);
 }  
 
```
    Note that the byte array returned by this method is not cloned! If you need a clone you must clone the array after calling this method or may use method toByteArray(true).
    Returns:
    the ASN1Object as DER encoded byte array or null if internal ASN1Object and ASN1 array have been cleared
  - toByteArray
```
public byte[] toByteArray(boolean createClone)
```
    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:
 if (der_array != null) {
   byte[] pem_array = Util.Base64Encode(der_array);
 }  
 
```
    Returns:
    the ASN1Object as DER encoded byte array or null if internal ASN1Object and ASN1 array have been cleared
  - 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.
  - clone
```
public java.lang.Object clone()
```
    Returns a clone of this ASN1 object.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    a clone of this ASN1 object
  - fingerprint
```
public byte[] fingerprint()
```
    Returns a fingerprint (MD5 Hash of the whole ASN1Object).
    
    Returns:
    the fingerprint

Class ASN1

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DER

PEM

startLine

Constructor Detail

ASN1

ASN1

ASN1

ASN1

Method Detail

readEncoded

getComponentAt

countComponents

getFirstObject

writeTo

getFormat

toString

print

toByteArray

toByteArray

toASN1Object

clearASN1Object

clearByteArray

clone

fingerprint