ASN1 ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- iaik.asn1.ASN1

```
public class ASN1
extends java.lang.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.
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(byte[] array, boolean strict)` Creates an ASN1 object from a byte array.
`ASN1(java.io.InputStream is)` Creates an ASN1 object from an InputStream.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`countComponents()` Returns the number of components in this ASN1 Object.
`static byte[]`	`extractFirstEncodedComponent(byte[] ba)` Extracts the DER encoded first component from a DER encoded ASN.1 structure (must be a Constructed type).
`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.
`ASN1Object`	`toASN1Object()` Returns the ASN1Object represented by this ASN1 object.
`byte[]`	`toByteArray()` 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
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.
    
    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 java.lang.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(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
  - ASN1
```
public ASN1(byte[] array,
            boolean strict)
     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
    
    strict - ASN.1 parsing when enabled will validate the array length against the actual parsed length for the 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. TODO no other way ???????
    Returns:
    
    the first sub-SEQUENCE as DER encoded byte array
    
    Throws:
    
    CodingException - if there is no sub-SEQUENCE in this SEQUENCE
  - extractFirstEncodedComponent
```
public static byte[] extractFirstEncodedComponent(byte[] ba)
                                           throws CodingException
```
    Extracts the DER encoded first component from a DER encoded ASN.1 structure (must be a Constructed type).
    This is useful when dealing with signed data structures where the signature is calculated over the DER encoding of the first component in the ASN.1 structure. For example, X.509 Certificate and CRLs use this type of structure. When dealing with signed data, it is essential that the signed data is not modified (otherwise signature verification would fail). This API will provide access to the raw bytes over which the signature was calculated without needing to decode then re-encode (doing so could result in unintended modifications to the signed data by the encoding routine).
    
    Parameters:
    
    ba - a DER encoded ASN.1 structure
    
    Returns:
    
    the DER encoded first component
    
    Throws:
    
    CodingException - if the encoding is invalid (does not represent an DER encoded ASN structure of a Constructed type)
    
    Since:
    
    7.2 SP1
  - 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
  - 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
  - toASN1Object
```
public ASN1Object toASN1Object()
```
    Returns the ASN1Object represented by this ASN1 object.
    
    Returns:
    
    the ASN1Object
  - 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

ASN1

Method Detail

getComponentAt

countComponents

getFirstObject

extractFirstEncodedComponent

toByteArray

writeTo

getFormat

toString

print

toASN1Object

fingerprint