You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by hi...@apache.org on 2006/09/29 14:55:29 UTC
svn commit: r451271 [2/9] - in /incubator/harmony/standard/site: ./ docs/
docs/documentation/ docs/images/ docs/subcomponents/buildtest/
docs/subcomponents/classlibrary/ docs/subcomponents/drlvm/
docs/subcomponents/jchevm/ docs/subcomponents/stresstest...
Modified: incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html
URL: http://svn.apache.org/viewvc/incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html?view=diff&rev=451271&r1=451270&r2=451271
==============================================================================
--- incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html (original)
+++ incubator/harmony/standard/site/docs/subcomponents/classlibrary/asn1_framework.html Fri Sep 29 05:55:25 2006
@@ -204,1440 +204,1440 @@
<td width="80%" valign="top"><a name="top"></a>
<div>
-<!--
- Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
--->
-<!--
-Author: Nadezhda Morozova, Stepan M. Mishura
-Version: $Revision$
--->
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type"
- content="text/html; charset=windows-1252" />
- <title>
- ASN.1 Framework
- </title>
- <link rel="Stylesheet" type="text/css" media="all" href="harmony.css" />
- </head>
- <body>
- <h1 style="text-align: center">
- <a id="Top" name="Top"></a>ASN.1 Framework
- </h1>
- <p class="TOCHeading">
- <a href="#Revision_History">Revision History</a>
- </p>
- <p class="TOCHeading">
- <a href="#Disclaimer">Disclaimer</a>
- </p>
- <p class="TOCHeading">
- <a href="#About_this_document">About this Document</a>
- </p>
- <p class="TOC">
- <a href="#Purpose">Purpose</a>
- </p>
- <p class="TOC">
- <a href="#Intended_Audience">Intended Audience</a>
- </p>
- <p class="TOC">
- <a href="#Documentation_Conventions">Documentation Conventions</a>
- </p>
- <p class="TOCHeading">
- <a href="#Overview">Introduction to ASN.1</a>
- </p>
- <p class="TOC">
- <a href="#About">About</a>
- </p>
- <p class="TOC">
- <a href="#Basic_Types">ASN.1 Basic Types</a>
- </p>
- <p class="TOCHeading">
- <a href="#Implementation">ASN.1 Framework in Harmony</a>
- </p>
- <p class="TOC">
- <a href="#About_ASN_Framework">About</a>
- </p>
- <p class="TOC">
- <a href="#Mapping_ASN_Java">Mapping between ASN.1 and Java Types</a>
- </p>
- <p class="TOC">
- <a href="#Harmony_Classes">Harmony ASN.1 Classes</a>
- </p>
- <p class="TOC">
- <a href="#Encoding_Rules">Encoding Rules</a>
- </p>
- <p class="TOC">
- <a href="#Notations_Implementation">Implementing ASN.1 Notations</a>
- </p>
- <p class="TOCHeading">
- <a href="#Appendix">Appendix: Usage Examples</a>
- </p>
- <p class="TOCHeading">
- <a href="#References">References</a>
- </p>
- <h1>
- <a id="Revision_History" name="Revision_History"></a>Revision History
- </h1>
- <table width="100%">
- <tr>
- <th class="TableHeading" width="25%">
- Version
- </th>
- <th class="TableHeading" width="50%">
- Version Information
- </th>
- <th class="TableHeading">
- Date
- </th>
- </tr>
- <tr>
- <td class="TableCell" width="25%">
- Initial version
- </td>
- <td class="TableCell" width="25%">
- Nadya Morozova, Stepan Mishura: document created<br />
- Special thanks to Sergey Dmitriev for assistance
- </td>
- <td class="TableCell">
- November 16, 2005
- </td>
- </tr>
- <tr>
- <td class="TableCell" width="25%">
- Formatting update
- </td>
- <td class="TableCell" width="25%">
- Nadya Morozova
- </td>
- <td class="TableCell">
- September 21, 2006
- </td>
- </tr>
- </table>
- <h1>
- <a id="Disclaimer" name="Disclaimer"></a>Disclaimer and Legal
- Information
- </h1>
- <p>
- Copyright 2005 The Apache Software Foundation or its licensors, as
- applicable.
- </p>
- <p>
- Licensed under the Apache License, Version 2.0 (the "License"); you
- may not use this file except in compliance with the License. You may
- obtain a copy of the License at <a
- href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>.
- </p>
- <p>
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied. See the License for the specific language governing
- permissions and limitations under the License.
- </p>
- <h1>
- <a id="About_this_document" name="About_this_document"></a>About This
- Document
- </h1>
- <h2>
- <a id="Purpose" name="Purpose"></a>Purpose
- </h2>
- <p>
- This document introduces the ASN.1 (Abstract Syntax Notation)
- framework delivered as part of the Harmony classlibrary. This document
- provides an overview of ASN.1 types and encoding rules with focus on
- the characteristics of the current implementation. The document gives
- details on the framework design and provides an overall description of
- the ASN.1 package.
- </p>
- <h2>
- <a id="Intended_Audience" name="Intended_Audience"></a>Intended
- Audience
- </h2>
- <p>
- The target audience for the document includes a wide community of
- engineers interested in using ASN.1 and in further work with the
- product to contribute to its development. The document assumes that
- readers are familiar with the ASN.1 notation and the Java<a
- href="#*">*</a> programming language.
- </p>
- <h2>
- <a id="Documentation_Conventions"
- name="Documentation_Conventions"></a>Documentation Conventions
- </h2>
- <p>
- This document uses the <a href="conventions.htm">unified
- conventions</a> for the Harmony documentation kit.
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h1>
- <a id="Overview" name="Overview"></a>Introduction to ASN.1
- </h1>
- <h2>
- <a id="About" name="About"></a>About
- </h2>
- <p>
- ASN.1 (Abstract Syntax Notation One) is an international standard of
- notation used to specify data structures with a high level of
- abstraction, which is reflected in the ASN.1 specification [<a
- href="#ASN_SPEC">2</a>]. ASN.1 is fully platform- and
- language-independent. ASN.1 goes with the <i>encoding rules</i>, which
- determine how to represent a value of an abstract type as a string of
- octets [<a href="#RULES_SPEC">3</a>].
- </p>
- <p>
- The Java<a href="#*">*</a> API specification [<a
- href="#JAVA_API_SPEC">1</a>] employs ASN.1 in the following ways:
- </p>
- <ul>
- <li>
- <i>Directly</i>: by providing the ASN.1 notation for used data and
- by specifying its encoding rule
- </li>
- <li>
- <i>Indirectly</i>: by refereeing to another (external)
- specification that uses the ASN.1 notation
- </li>
- </ul>
- <p>
- To learn more about ASN.1, you can use online documentation [<a
- href="#INFO_SITE">4</a>], [<a href="#LAYMAN_GUIDE">5</a>], and
- publications [<a href="#EBOOK1">6</a>], [<a href="#EBOOK2">7</a>].
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h2>
- <a id="Basic_Types" name="Basic_Types"></a>ASN.1 Basic Types
- </h2>
- <p>
- ASN.1 has the following basic types:
- </p>
- <ul>
- <li>
- <a href="#String"><i>String</i></a> and <a
- href="#Primitive"><i>primitive</i></a> types represent raw data.
- </li>
- <li>
- <a href="#Constructed"><i>Constructed</i></a> types serve as
- containers for a number of type components, which can be optional
- or can have default values.
- </li>
- <li>
- <a href="#Tagged"><i>Tagged</i></a> types are used to derive one
- ASN.1 type from another.
- </li>
- <li>
- <a href="#Other"><i>Other</i></a> types are <code>ANY</code> and
- <code>CHOICE</code>.
- </li>
- </ul>
- <p>
- These types are used to specify a wide range of other abstract types,
- as shown in Example 1.
- </p>
- <p class="example">
- <a id="example1" name="example1"></a>Example 1
- </p>
- <p class="exampletext">
- This example is based on RFC 3280 [<a href="#RFC">8</a>].
- </p>
- <blockquote>
-<pre>
-Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
-
-Extension ::= SEQUENCE {
- extnID OBJECT IDENTIFIER,
- critical BOOLEAN DEFAULT FALSE,
- extnValue OCTET STRING
-}
-
-Version ::= INTEGER { v1(0), v2(1), v3(2) }
-</pre>
- </blockquote>
- <p>
- In this example, the basic ASN.1 types <code>SEQUENCE</code>,
- <code>OBJECT IDENTIFIER</code>, <code>BOOLEAN</code> and <code>OCTET
- STRING</code> are used to specify a new abstract type
- <code>Extension</code>. The newly created type is then used with
- another basic type <code>SEQUENCE OF</code> to describe the
- <code>Extensions</code> type. The ASN.1 <code>INTEGER</code> type is
- used to specify the <code>Version</code> abstract type and to provide
- constraints for this type.
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h1>
- <a id="Implementation" name="Implementation"></a>ASN.1 Framework in
- Harmony
- </h1>
- <p>
- This section part of the document describes the ASN.1 framework as a
- whole, defines the mapping principles to establish the correspondence
- between ASN.1 and Java<a href="#*">*</a> types, and represents the
- hierarchy of ASN.1 types representation in the current framework.
- </p>
- <h2>
- <a id="About_ASN_Framework" name="About_ASN_Framework"></a>About
- </h2>
- <p>
- The ASN.1 framework provides a common, easy and efficient approach for
- working with ASN.1 basic types, notations and encoding rules. This
- framework can be described as a layer between a Java<a href="#*">*</a>
- object and its ASN.1 encoded form, as shown in Figure 1.
- </p>
- <br />
- <br />
- <p style="text-align: center">
- <img src="images/ASN_framework.gif" alt="overview" />
- </p>
- <p class="special" style="text-align: center">
- Figure 1: ASN.1 Framework Layer
- </p>
- <p>
- The Harmony ASN.1 framework is characterized by:
- </p>
- <ul>
- <li>
- A clear API for decoding and encoding objects
- </li>
- <li>
- Low resource consuming
- </li>
- <li>
- Thread safety
- </li>
- </ul>
- <p>
- The framework enables the following:
- </p>
- <ul>
- <li>
- Create a Java<a href="#*">*</a> object instance from its encoded
- octet string
- </li>
- <li>
- Verify that an octet string is a valid encoded string
- </li>
- <li>
- Generate an encoded octet string for a particular object
- </li>
- </ul>
- <p class="note">
- Note
- </p>
- <p class="notetext">
- The current ASN.1 framework is a partial implementation of the ASN.1
- and encoding rules specifications. This framework covers certain ASN.1
- basic types and basic encoding rules (BER), and provides most
- restrictions employed by the distinguished encoding rules (DER).
- </p>
- <h2>
- <a id="Mapping_ASN_Java" name="Mapping_ASN_Java"></a>Mapping between
- ASN.1 and Java<a href="#*">*</a> Types
- </h2>
- <p>
- The framework maps all ASN.1 abstract types and notations to Java<a
- href="#*">*</a> primitive types or Java<a href="#*">*</a> classes.
- </p>
- <p class="example">
- <a id="example2" name="example2"></a>Example 2
- </p>
- <p class="exampletext">
- The notations in <a href="#example1">Example 1</a> can be represented
- as the following Java<a href="#*">*</a> classes:
- </p>
- <blockquote>
-<pre>
-public class Extension {
- private String extnID;
- private boolean critical;
- private byte extnValue[];
-}
-
-public class Extensions {
- // contains elements of Extension class
- private List extensions;
-}
-</pre>
- </blockquote>
- <p>
- The <code>Extension</code> notation corresponds to a Java<a
- href="#*">*</a> class with three fields, where every field corresponds
- to one entry in the <code>Extension</code> notation. For example, the
- <code>critical BOOLEAN DEFAULT FALSE</code> field in the
- <code>Extension</code> notation corresponds to the <code>boolean
- critical</code> field in the Java<a href="#*">*</a> class. The
- <code>Extensions</code> notation equals to a Java<a href="#*">*</a>
- class with a field that contains an ordered collection of the
- instances of the <code>Extension</code> class.
- </p>
- <p>
- The table below describes the default mapping ASN.1 types to Java<a
- href="#*">*</a> types, and indicates the class providing the specified
- mapping in the current framework.
- </p>
- <table cellspacing="0" cellpadding="0" align="center"
- width="60%">
- <tr>
- <th class="TableHeading" colspan="2">
- ASN.1 Type
- </th>
- <th class="TableHeading" style="text-align: center"
- width="25%">
- Java<a href="#*">*</a> Type
- </th>
- <th class="TableHeading" width="30%">
- Framework Class
- </th>
- </tr>
- <tr>
- <th class="TableHeading" rowspan="5" width="11%">
- <a id="Primitive" name="Primitive">Primitive</a>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>INTEGER</code>
- </td>
- <td align="center" width="25%">
- <code>byte[]</code>
- </td>
- <td width="25%">
- <code><a href="#ASN1Integer">ASN1Integer</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>ENUMERATED</code>
- </td>
- <td align="center" width="25%">
- <code>byte[]</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1Enumerated">ASN1Enumerated</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>OBJECT IDENTIFIER</code>
- </td>
- <td align="center" width="25%">
- <code>int[]</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1Oid">ASN1Oid</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>BOOLEAN</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.Boolean</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1Boolean">ASN1Boolean</a></code>
- </td>
- </tr>
- <tr>
- <th class="TableHeading" rowspan="12" width="11%">
- <a id="String" name="String">String</a>
- </th>
- <td width="30%">
- <code>BitString</code>
- </td>
- <td align="center" width="25%">
- <code>asn1.BitString</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1BitString">ASN1BitString</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>OctetString</code>
- </td>
- <td align="center" width="25%">
- <code>byte[]</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1OctetString">ASN1OctetString</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>PrintableString</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>T61String</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>IA5String</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>UTF8String</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>BMPString</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>GeneralString</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>TeletexString</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>UniversalString</code>
- </td>
- <td align="center" width="25%">
- <code>java.lang.String</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1StringType">ASN1StringType</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>UTCTime</code>
- </td>
- <td align="center" width="25%">
- <code>java.util.Date</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1UTCTime">ASN1UTCTime</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>GeneralizedTime</code>
- </td>
- <td align="center" width="25%">
- <code>java.util.Date</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1UTCTime">ASN1GeneralizedTime</a></code>
- </td>
- </tr>
- <tr>
- <th rowspan="3" class="TableHeading">
- <a id="Constructed" name="Constructed">Constructed</a>
- </th>
- <td width="30%">
- <code>SEQUENCE</code>
- </td>
- <td align="center" width="25%">
- <code>Object[]</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1Sequence">ASN1Sequence</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>SEQUENCE OF</code>
- </td>
- <td align="center" width="25%">
- <code>java.util.List</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1SequenceOf">ASN1SequenceOf</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>SET OF</code>
- </td>
- <td width="25%" align="center">
- <code>java.util.List</code>
- </td>
- <td width="30%">
- <code><a href="#ASN1SetOf">ASN1SetOf</a></code>
- </td>
- </tr>
- <tr>
- <th rowspan="2" width="11%" class="TableHeading">
- <a id="Tagged" name="Tagged">Tagged</a>
- </th>
- <td width="30%">
- <code>EXPLICIT</code>
- </td>
- <td width="25%" style="text-align: center">
- <i>based type</i>
- </td>
- <td width="30%">
- <a href="#ASN1Explicit"><code>ASN1Explicit</code></a>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>IMPLICIT</code>
- </td>
- <td align="center" width="25%" style="text-align: center">
- <i>based type</i>
- </td>
- <td width="30%">
- <a href="#Class_ASNImplicit"><code>ASN1Implicit</code></a>
- </td>
- </tr>
- <tr>
- <th rowspan="2" width="11%" class="TableHeading">
- <a id="Other" name="Other">Other</a>
- </th>
- <td width="30%">
- <code>ANY</code>
- </td>
- <td align="center" width="25%">
- <code>byte[]</code>
- </td>
- <td width="30%">
- <code><a href="#Class_ASNAny">ASN1Any</a></code>
- </td>
- </tr>
- <tr>
- <td width="30%">
- <code>CHOICE</code>
- </td>
- <td align="center" width="25%" style="text-align: center">
- <i>one of chosen types</i>
- </td>
- <td width="30%">
- <code><a href="#Class_ASNChoice">ASN1Choice</a></code>
- </td>
- </tr>
- </table>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h2>
- <a id="Harmony_Classes" name="Harmony_Classes"></a>Harmony ASN.1
- Classes
- </h2>
- <p>
- Basic ASN.1 types are in the
- <code>org.apache.harmony.security.asn1</code> package in accordance
- with the hierarchy shown in Figure 2.
- </p>
- <p style="text-align: center">
- <img src="images/package_content.gif" alt="package" width="469"
- height="352" />
- </p>
- <p class="special">
- Figure 2: Class Hierarchy
- </p>
- <p>
- The subsequent sections provide as short description of the classes
- included in the package.
- </p>
- <p class="class">
- <a id="Primitive_Types" name="Primitive_Types"></a>Primitive Types
- </p>
- <dl>
- <dt>
- <a id="ASN1Integer" name="ASN1Integer"></a>ASN1Integer
- </dt>
- <dd>
- This class represents the ASN.1 <code>INTEGER</code> type that
- denotes an arbitrary integer with positive, negative, or zero
- values and any magnitude. Because an integer value is not
- restricted, it is up to the application class to choose the Java<a
- href="#*">*</a> type for storing the integer value, for example, an
- instance of the <code>java.math.BigInteger</code> class. By
- default, an integer value is stored in an array of bytes.
- </dd>
- <dt>
- <a id="ASN1Enumerated" name="ASN1Enumerated"></a> ASN1Enumerated
- </dt>
- <dd>
- This class represents the ASN.1 <code>ENUMERATED</code> type that
- denotes a set of integer values. The implementation of this class
- is similar to that of the <code>ASN1Integer</code> class.
- </dd>
- <dt>
- <a id="ASN1Oid" name="ASN1Oid"></a>ASN1Oid
- </dt>
- <dd>
- This class implements the ASN.1 <code>OBJECT IDENTIFIER</code>
- type. This type is a sequence of integer components that identifies
- an entity, such as an organization or an algorithm. Integer
- components have no negative values. An <code>OBJECT
- IDENTIFIER</code> value includes at least two components. The
- corresponding Java<a href="#*">*</a> type is an array of integer
- values.
- </dd>
- <dt>
- <a id="ASN1Boolean" name="ASN1Boolean"></a> ASN1Boolean
- </dt>
- <dd>
- This class implements the ASN.1 <code>BOOLEAN</code> type, which
- corresponds to the <code>java.lang.Boolean</code> Java<a
- href="#*">*</a> class.
- </dd>
- </dl>
- <p class="class">
- <a id="String_Types" name="String_Types"></a>String Types
- </p>
- <dl>
- <dt>
- <a id="ASN1StringType" name="ASN1StringType"></a>ASN1StringType
- </dt>
- <dd>
- This is an abstract class that contains common functionality for
- all ASN.1 string types, and includes the implementation of the
- following types: <code>BMPString, IA5String, GeneralString,
- PrintableString, TeletexString, UniversalString,</code> and
- <code>UTF8String</code>. The class maps all these types to the
- <code>java.lang.String</code> object.
- <p class="note">
- Note
- </p>
- <p class="notetext">
- The current implementation does not verify allowed characters
- for any of ASN.1 restricted characters types. The class only
- stores and retrieves contents bytes to and from the
- <code>String</code> object.
- </p>
- </dd>
- </dl>
- <dl>
- <dt>
- <a id="ASN1BitString" name="ASN1BitString"></a>ASN1BitString
- </dt>
- <dd>
- This class represents the ASN.1 <code>BitString</code> type. The
- corresponding Java<a href="#*">*</a> class is
- <code>BitString</code> included in the <code>asn1</code> package.
- The class provides implementation for decoding or encoding
- <code>BitString</code> objects.
- <p class="note">
- Note
- </p>
- <p class="notetext">
- A special use case for this ASN.1 type exists, when the type is
- declared as <code>Named BitString</code>. For example:
- </p>
- <blockquote>
- <blockquote>
-<pre>
- Keys ::= BIT STRING {
- Key1 (0),
- Key2 (1),
- MyKey (2)
- }
-</pre>
- </blockquote>
- </blockquote>
- <p class="notetext">
- In this case, the BER specification [<a
- href="#RULES_SPEC">3</a>] enables adding and removing any number
- of trailing to and from the basic encoding. To provide a correct
- type implementation, use the
- <code>ASN1Bitstring.ASN1NamedBitList</code> class. By default,
- the class maps the ASN.1 <code>Named BitString</code> type to an
- array of primitive boolean values.
- </p>
- </dd>
- <dt>
- <a id="ASN1OctetString" name="ASN1OctetString"></a>ASN1OctetString
- </dt>
- <dd>
- This class implements the ASN.1 <code>OctetString</code> type,
- which corresponds to the Java<a href="#*">*</a> type of an array of
- bytes.
- </dd>
- </dl>
- <dl>
- <dt>
- <a id="ASN1UTCTime" name="ASN1UTCTime"></a> ASN1UTCTime
- </dt>
- <dd>
- This class represents the ASN.1 <code>UTCTime</code> type. The
- corresponding Java<a href="#*">*</a> class is
- <code>java.util.Date</code>.
- </dd>
- <dt>
- <a id="ASN1GeneralizedTime"
- name="ASN1GeneralizedTime"></a>ASN1GeneralizedTime
- </dt>
- <dd>
- This class represents the ASN.1 <code>GeneralizedTime</code> type.
- The corresponding Java<a href="#*">*</a> class is
- <code>java.util.Date</code>.
- </dd>
- </dl>
- <p class="class">
- <a id="Constructed_Types" name="Constructed_Types"></a>Constructed
- Types
- </p>
- <dl>
- <dt>
- <a id="ASN1Sequence" name="ASN1Sequence"></a> ASN1Sequence
- </dt>
- <dd>
- The class represents a ASN.1 type consisting of an ordered
- collection of more than one type. A type in the collection can be
- optional or can have default values. If a type in the collection is
- marked as optional or default, then its value may be absent in the
- encoding of the sequence type. If a default type is absent, then
- its default value is used.<br />
- An instance of the class is initialized with a Java<a
- href="#*">*</a> array of ASN.1 classes that corresponds to the
- notation of a sequence type. The order of ASN.1 classes in an
- initialization array must strictly correspond to the type.<br />
- For example, if a sequence type has the following types collection:
- <code>integer</code>, <code>boolean</code>, <code>ANY</code>, then
- an initialization array must contain three class instances in the
- same order: <code>ASN1Boolean</code>, <code>ASN1Integer</code>,
- <code>ASN1Any</code>.
- </dd>
- <dt>
- <a id="ASN1SequenceOf" name="ASN1SequenceOf"></a>ASN1SequenceOf
- </dt>
- <dd>
- The <code>SEQUENCE OF</code> type denotes an ordered collection of
- one or more values of the selected ASN.1 type. An instance of the
- class is initialized with an instance of the ASN.1 class according
- to the type notation. The passed instance is used to decode or
- encode all values in an collection.
- </dd>
- <dt>
- <a id="ASN1SetOf" name="ASN1SetOf"></a>ASN1SetOf
- </dt>
- <dd>
- The <code>SET OF</code> type denotes an unordered collection of one
- or more values of the selected ASN.1 type. This class is similar to
- the <code>ASN1SequenceOf</code> class.
- </dd>
- </dl>
- <p class="class">
- <a id="Tagged_Types" name="Tagged_Types"></a>Tagged Types
- </p>
- <dl>
- <dt>
- <a id="ASN1Explicit" name="ASN1Explicit"></a>ASN1Explicit
- </dt>
- <dd>
- The class implements the ASN.1 <code>EXPLICIT</code> type tagging.
- <em>Explicit tagging</em> denotes a type derived from another type
- by adding an outer tag to the base type. This type can be
- represented as a sequence type with only one component, so that the
- implementation class acts as a container for another ASN.1 type.
- </dd>
- <dt>
- <a id="Class_ASNImplicit" name="Class_ASNImplicit"></a>ASN1Implicit
- </dt>
- <dd>
- The class implements the ASN.1 <code>IMPLICIT</code> type tagging.
- An <em>implicitly tagged type</em> is a type derived from another
- type by changing a tag of the base type. The implementation class
- for this type changes only the tag when decoding or encoding the
- base type.
- </dd>
- </dl>
- <p class="class">
- <a id="Other_Types" name="Other_Types"></a>Other Types
- </p>
- <dl>
- <dt>
- <a id="Class_ASNAny" name="Class_ASNAny"></a>ASN1Any
- </dt>
- <dd>
- The class implements the ASN.1 <code>ANY</code> type. The type
- denotes any ASN.1 type that can be defined by a value of the
- <code>OBJECT IDENTIFIER</code> or by an integer index. The class
- handles only raw data represented as a Java<a href="#*">*</a> byte
- array. It is up to the application class to select the appropriate
- decoder or encoder for retrieving or storing the content
- respectively.
- </dd>
- <dt>
- <a id="Class_ASNChoice" name="Class_ASNChoice"></a>ASN1Choice
- </dt>
- <dd>
- The class implements the ASN.1 <code>CHOICE</code> type. The type
- represents a list of one more type alternatives with distinct tags.
- an instance of the class is initialized with the Java<a
- href="#*">*</a> array of ASN.1 classes, which corresponds to a type
- notation.<br />
- For example, if a <code>CHOICE</code> type is specified as a list
- of <code>boolean</code>, <code>OctetString</code> and
- <code>UTCTime</code>, then an initialization array contains
- instances of the <code>ASN1Boolean</code>,
- <code>ASN1OctetString</code> and <code>ASN1UTCTime</code> classes.
- During decoding or encoding, a required type alternative is
- selected.
- </dd>
- </dl>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h2>
- <a id="Encoding_Rules" name="Encoding_Rules"></a>Encoding Rules
- </h2>
- <p>
- Encoding rules specify how to represent an ASN.1 type as a sequence of
- octets. ASN.1 encoding rules are represented in the
- <code>org.apache.harmony.security.asn1</code> package, as follows:
- </p>
- <ul>
- <li>
- <code>BerInputStream</code> and <code>DerInputStream</code> provide
- decoding and verifying functionality for corresponding notation
- rules.
- </li>
- <li>
- <code>BerOutputStream</code> and <code>DerOutputStream</code>
- provide the encoding functionality.
- </li>
- </ul>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h3>
- <a id="Encoding" name="Encoding"></a>Encoding
- </h3>
- <p>
- <em>Encoding</em> an object is the process of extracting all required
- information from an object and storing it in a sequence of octets
- according to the specified ASN.1 notation and encoding rules. The
- common encoding functionality is implemented in the
- <code>BerOutputStream</code> class. Encoding for DER is represented by
- the <code>DEROutputStream</code> class.
- </p>
- <p>
- The encoding of data for each ASN.1 type includes:
- </p>
- <ul>
- <li>
- identifier octets (for example, tag)
- </li>
- <li>
- length octets
- </li>
- <li>
- content octets
- </li>
- <li>
- end-of-content octets
- </li>
- </ul>
- <p class="note">
- DER Encoding
- </p>
- <p class="notetext">
- In contrast to BER, DER enables using only the definite form of length
- encoding. That is why, before encoding an ASN.1 type value, the ASN.1
- framework must obtain the length of the value. This requirement
- determines the whole process of DER encoding: to calculate the length
- of a constructed ASN.1 type, the framework calculates lengths of its
- components, which can also be constructed, and so on. DER encoding
- goes in the following stages:
- </p>
- <ul class="notetext">
- <li>
- <em>Collection</em>: Step by step, the DER encoder extracts all
- data to be encoded, processes the data, calculates an encoding
- length for each item, and stores all calculations and processed
- data. Then, the encoder calculates the overall encoding length and
- allocates required space.
- </li>
- <li>
- <em>Encoding</em>: The DER encoder retrieves stored information,
- encodes it according to the rules and writes the encoding to the
- allocated byte array.
- </li>
- </ul>
- <h3>
- <a id="Decoding" name="Decoding"></a>Decoding
- </h3>
- <p>
- <em>Decoding</em> or verifying the provided encoded form is a
- sequential process of parsing strings of octets according to the
- specified ASN.1 notation and encoding rules.
- </p>
- <p>
- An iteration of decoding an ASN.1 type includes decoding its tag,
- length, and content octets. The class <code>BerInputStream</code>
- provides a common decoding implementation for all basic ASN.1 types.
- To provide specific decoding for a basic ASN.1 type, a derived class
- must override one of the corresponding methods. For example,
- <code>DerInputStream</code> provides a custom implementation for
- decoding the <code>ASN.1 Boolean</code> type by overriding the method
- <code>readBoolean()</code>.
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h2>
- <a id="Notations_Implementation"
- name="Notations_Implementation"></a>Implementing ASN.1 Notations
- </h2>
- <h3>
- <a id="Basic_Classes" name="Basic_Classes"></a>Basic Classes
- </h3>
- <p>
- In the current framework, the basic classes meet the following
- requirements:
- </p>
- <ul>
- <li>
- All basic classes are thread-safe classes.<br />
- This means that an instance of an ASN.1 class can be used by many
- threads simultaneously for decoding or encoding a particular class
- of Java<a href="#*">*</a> objects. An instance of an ASN.1 class
- does not keep any specific data for a selected object. It only
- provides a way for a decoder stream to store decoded data in a
- Java<a href="#*">*</a> object, and a way for an encoder stream to
- extract a data to be encoded from a Java<a href="#*">*</a> object.
- </li>
- <li>
- All classes for string and primitive ASN.1 types provide access to
- a reusable class instance via the static <code>getInstance()</code>
- method.<br />
- If a separate instance of an ASN.1 class is not required, this
- method is used instead of a constructor. A constructor is provided
- for inheritance purposes only.
- </li>
- </ul>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h3>
- <a id="Custom_classes" name="Custom_classes"></a>Custom Classes
- </h3>
- <p>
- Classes from the <code>asn1</code> package that represent ASN.1 basic
- types are used as building blocks for implementing a <em>custom</em>
- ASN.1 encoding or decoding class. A custom ASN.1 class provides
- mapping of an abstract ASN.1 type to a definite Java<a href="#*">*</a>
- class.
- </p>
- <p>
- Two approaches for implementing custom ASN.1 classes are available.
- Custom classes can be designed as singleton Java<a href="#*">*</a>
- classes or not. The choice depends on further use of the class
- decoder. The singleton approach is not efficient when decoding only
- one Java<a href="#*">*</a> object. However, for decoding a series of
- encodings (for example, with an application server), the singleton
- approach is rather effective because only one reusable decoder
- instance exists. Creating a new decoder object for each decoded or
- encoded Java<a href="#*">*</a> object leads to performance penalties.
- </p>
- <p>
- To implement the singleton approach, a custom ASN.1 class must meet
- the following requirements:
- </p>
- <ul>
- <li>
- Class has only one reusable instance and provides a way to access
- it.
- </li>
- <li>
- Class is thread-safe. Thread safety is provided by passing all
- required data via parameters of methods. All data specific for a
- Java<a href="#*">*</a> object is stored in the decoding or encoding
- stream.
- </li>
- </ul>
- <p class="example">
- Example 3
- </p>
- <p class="exampletext">
- This example illustrates the singleton approach to static instances of
- ASN.1 custom classes for the <code>Extensions</code> and
- <code>Extension</code> classes used in <a href="#example2">Example
- 2</a> . For this, create an instance of a custom ASN.1 class as an
- instance of an anonymous class as shown below.
- </p>
- <blockquote>
-<pre>
-class Extensions {
- // instance of decoder/encoder
- public static final ASN1SequenceOf ASN1 =
- new ASN1SequenceOf(Extension.ASN1);
-
- private List extensions;
-}
-
-class Extension {
- // instance of decoder/encoder
- public static final ASN1Sequence ASN1 =
- new ASN1Sequence(new ASN1Type[] {
- ASN1Oid.getInstance(), // extnID
- ASN1Boolean.getInstance(), // critical
- ASN1OctetString.getInstance()}) { // extnValue
- // replace constructor
- {
- // set default value for critical field
- // first parameter - a default value
- // second parameter - an index of ASN.1 type in a sequence starting with 0
- setDefault(Boolean.FALSE, 1);
- }
- };
-
- private String extnID;
- private boolean critical;
- private byte extnValue[];
-
-}
-</pre>
- </blockquote>
- <p>
- The <code>static final ASN1</code> field instance provides a mapping
- between the Java<a href="#*">*</a> <code>Extension</code> class and
- its ASN.1 notation. The field is initialized so that it reflects the
- ASN.1 notation of the class: it is the instance of the
- <code>ASN1Sequence</code> class that is initialized with instances of
- the <code>ASN1Oid</code>, <code>ASN1Boolean</code> and
- <code>ASN1OctetString</code> classes.
- </p>
- <p>
- The <code>Extensions</code> class has a similar field. The field also
- reflects the ASN.1 notation: it is the instance of the
- <code>ASN1SequenceOf</code> class and it is initialized by the
- <code>ASN1</code> field from the <code>Extension</code> class.
- </p>
- <p>
- Figure 3 displays the correspondence between the application object
- tree and the object tree of ASN.1 custom classes.
- </p>
- <p style="text-align: center">
- <img src="images/example3.gif" alt="Tree" />
- </p>
- <p class="special">
- Figure 3: Java Object and ASN.1 Custom Class Trees
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h1>
- Appendix: <a id="Appendix" name="Appendix"></a>Usage Examples
- </h1>
- <p>
- This section demonstrates the usage of the ASN.1 framework.
- </p>
- <h3>
- ASN.1 Boolean
- </h3>
- <p>
- An abstract type can be defined as <code>ASN.1 Boolean</code>, for
- example:
- </p>
- <blockquote>
-<pre>
-MyBooleanType ::= BOOLEAN;
-</pre>
- </blockquote>
- <p>
- Then the following code can be used to decode and encode values of
- this type:
- </p>
- <blockquote>
-<pre>
-// represents encoded ASN.1 Boolean type: false value
-byte encoding[] = new byte[] {0x01, 0x01, 0x00};
-
-// get instance of ASN.1 Boolean decoder/encoder
-ASN1Type asn1 = ASN1Boolean.getInstance();
-
-// decoded value is Boolean.FALSE
-Boolean value = (Boolean)asn1.decode(encoding);
-
-// encode Boolean.TRUE value
-
-// an array value equals to {0x01, 0x01, 0xFF}
-byte enc[] = asn1.encode(Boolean.TRUE);
-</pre>
- </blockquote>
- <h3>
- ASN.1 Tagged Types
- </h3>
- <p>
- The following ASN.1 notation can be used to define a tagged type:
- </p>
- <blockquote>
-<pre>
-MyTaggedType ::= [APPLICATION 0] EXPLICIT BOOLEAN;
-</pre>
- </blockquote>
- <p>
- By default, a tagged type, <code>MyTaggedType</code>, is mapped to the
- same Java<a href="#*">*</a> type as a basic type, see ASN.1
- <code>BOOLEAN</code> above.
- </p>
- <p>
- Then the following code can be used to decode and encode the values of
- this type:
- </p>
- <blockquote>
-<pre>
-// represents encoded explicitly tagged ASN.1 Boolean type: false value
-byte encoding[] = new byte[] {0x60, 0x03, 0x01, 0x01, 0x00};
-
-// create an instance of custom decoder/encoder for tagged type
-ASN1Type asn1 = new ASN1Explicit(
- ASN1Constants.CLASS_APPLICATION, // tagging class
- 0, // tag number
- ASN1Boolean.getInstance() // type to be tagged
-);
-
-// decoded value is Boolean.FALSE
-Boolean value = (Boolean)asn1.decode(encoding);
-
-// encode Boolean.TRUE value as explicitly tagged
-
-// an array value equals to {0x60, 0x03,0x01, 0x01, 0xFF}
-byte enc[] = asn1.encode(Boolean.TRUE);
-</pre>
- </blockquote>
- <h3>
- ASN.1 Sequence Type
- </h3>
- <p>
- A constructed ASN.1 type notation can go as follows.
- </p>
- <blockquote>
-<pre>
-MyConstructedType ::= SEQUENCE {
- classVersion INTEGER,
- isExtendable BOOLEAN DEFAULT FALSE
-}
-</pre>
- </blockquote>
- <p>
- By default, a sequence type is mapped to an array of objects. In the
- example, it is an array of two objects: the first object represents
- <code>classVersion</code> and the second object represents the
- <code>isExtendable</code> flag.
- </p>
- <p>
- The following code can be used to decode and encode the values of this
- type:
- </p>
- <blockquote>
-<pre>
-// create an instance custom decoder/encoder
-ASN1Type asn1 =
- new ASN1Sequence(new ASN1Type[] {ASN1Integer.getInstance(), // classVersion
- ASN1Boolean.getInstance()}) { // isExtendable
- // replace constructor
- {
- // set default value for isExtendable field
- // first parameter - a default value
- // second parameter - an index of ASN.1 type in a sequence starting with 0
- setDefault(Boolean.FALSE, 1);
- }
- };
-
-// decoded sequence value is mapped to array of objects
-Object value[] = (Object[])asn1.decode(someEncoding);
-
-// first value (ASN.1 Integer) is mapped by default to an array of bytes
-byte version[] = (byte[])value[0];
-
-// second value (ASN.1 Boolean) is mapped by default to a Boolean object
-Boolean isCritical = (Boolean)value[1];
-</pre>
- </blockquote>
- <p>
- When it is necessary to change the default mapping of an array of
- objects for the ASN.1 <code>Sequence</code> type to a custom Java<a
- href="#*">*</a> class, two methods are overridden.
- </p>
- <blockquote>
-<pre>
-// class for storing MyConstructedType values
-class A {
- int version;
- boolean isExtendable;
-}
-
-// create an instance custom decoder/encoder
-ASN1Type asn1 =
- new ASN1Sequence(new ASN1Type[] {ASN1Integer.getInstance(), // classVersion
- ASN1Boolean.getInstance()}) { // isExtendable
- // replace constructor
- {
- // set default value for isExtendable field
- // first parameter - a default value
- // second parameter - an index of ASN.1 type in a sequence starting with 0
- setDefault(Boolean.FALSE, 1);
- }
-
- // for decoding
- public Object getDecodedObject(BerInputStream in) throws IOException {
- Object values[] = (Object[])in.content;
-
- A a = new A();
-
- // array of bytes to primitive int value
- a.version = (new BigInteger((byte[])value[0])).intValue;
-
- // Boolean object to primitive boolean
- a.isExtendable = ((Boolean)value[1]).booleanValue();
-
- return a;
- }
-
- // for encoding
- public void getValues(Object object, Object values[]) {
- A a = (A)object;
-
- // primitive int value to array of bytes
- values[0] = BigInteger.valueOf(a.version).toByteArray();
-
- // primitive boolean value to Boolean object
- values[1] = Boolean.valueOf(a.isCritical);
- }
- };
-
-// decoded sequence value is mapped to custom A class
-A a1 = (A)asn1.decode(someEncoding);
-
-// encode an instance of A class
-A a2 = new A();
-a2.version = 5;
-a2.isExtendable = true;
-byte enc[] = asn1.encode(a);
-</pre>
- </blockquote>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <h1>
- <a id="References" name="References"></a>References
- </h1>
- <p>
- [<a id="JAVA_API_SPEC" name="JAVA_API_SPEC"></a>1] Java API
- Specification, <a href="http://java.sun.com/j2se/1.5.0/docs/api/"
- target="_blank">http://java.sun.com/j2se/1.5.0/docs/api/</a>
- </p>
- <p>
- [<a id="ASN_SPEC" name="ASN_SPEC"></a>2] Abstract Syntax Notation One
- (ASN.1) Specification of Basic Notation ITU-T Rec. X.680 (2002) |
- ISO/IEC 8824-1:2002
- </p>
- <p>
- [<a id="RULES_SPEC" name="RULES_SPEC"></a>3] Specification of Basic
- Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished
- Encoding Rules (DER) ITU-T Rec. X.690 (2002) | ISO/IEC 8825-1:2002
- </p>
- <p>
- [<a id="INFO_SITE" name="INFO_SITE"></a>4] ASN.1 Information Site, <a
- href="http://asn1.elibel.tm.fr/en/standards/index.htm"
- target="_blank">http://asn1.elibel.tm.fr/en/standards/index.htm</a>
- </p>
- <p>
- [<a id="LAYMAN_GUIDE" name="LAYMAN_GUIDE"></a>5] <em>A Layman's Guide
- to a Subset of ASN.1, BER, and DER,</em> <a
- href="http://luca.ntop.org/Teaching/Appunti/asn1.html"
- target="_blank">http://luca.ntop.org/Teaching/Appunti/asn1.html</a>
- </p>
- <p>
- [<a id="EBOOK1" name="EBOOK1"></a>6] Olivier Dubuisson, translated by
- Philippe Fouquart, <em>ASN.1 - Communication between heterogeneous
- systems</em>, <a href="http://www.oss.com/asn1/dubuisson.html"
- target="_blank">http://www.oss.com/asn1/dubuisson.html</a>
- </p>
- <p>
- [<a id="EBOOK2" name="EBOOK2"></a>7] Professor John Larmouth,
- <em>ASN.1 Complete</em>, <a
- href="http://www.oss.com/asn1/larmouth.html"
- target="_blank">http://www.oss.com/asn1/larmouth.html</a>
- </p>
- <p>
- [<a id="RFC" name="RFC"></a>8] The Internet Engineering Task Force,
- Requests for Comments, <a href="http://www.ietf.org/"
- target="_blank">http://www.ietf.org/</a>
- </p>
- <p class="backtotop">
- <a href="#Top">Back to Top</a>
- </p>
- <br />
- <br />
- <br />
- <br />
- <p>
- <a id="*" name="*">*</a> Other brands and names are the property of
- their respective owners.
- </p>
- </body>
-</html>
-
+<!--
+ Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+<!--
+Author: Nadezhda Morozova, Stepan M. Mishura
+Version: $Revision$
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=windows-1252" />
+ <title>
+ ASN.1 Framework
+ </title>
+ <link rel="Stylesheet" type="text/css" media="all" href="harmony.css" />
+ </head>
+ <body>
+ <h1 style="text-align: center">
+ <a id="Top" name="Top"></a>ASN.1 Framework
+ </h1>
+ <p class="TOCHeading">
+ <a href="#Revision_History">Revision History</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Disclaimer">Disclaimer</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#About_this_document">About this Document</a>
+ </p>
+ <p class="TOC">
+ <a href="#Purpose">Purpose</a>
+ </p>
+ <p class="TOC">
+ <a href="#Intended_Audience">Intended Audience</a>
+ </p>
+ <p class="TOC">
+ <a href="#Documentation_Conventions">Documentation Conventions</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Overview">Introduction to ASN.1</a>
+ </p>
+ <p class="TOC">
+ <a href="#About">About</a>
+ </p>
+ <p class="TOC">
+ <a href="#Basic_Types">ASN.1 Basic Types</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Implementation">ASN.1 Framework in Harmony</a>
+ </p>
+ <p class="TOC">
+ <a href="#About_ASN_Framework">About</a>
+ </p>
+ <p class="TOC">
+ <a href="#Mapping_ASN_Java">Mapping between ASN.1 and Java Types</a>
+ </p>
+ <p class="TOC">
+ <a href="#Harmony_Classes">Harmony ASN.1 Classes</a>
+ </p>
+ <p class="TOC">
+ <a href="#Encoding_Rules">Encoding Rules</a>
+ </p>
+ <p class="TOC">
+ <a href="#Notations_Implementation">Implementing ASN.1 Notations</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#Appendix">Appendix: Usage Examples</a>
+ </p>
+ <p class="TOCHeading">
+ <a href="#References">References</a>
+ </p>
+ <h1>
+ <a id="Revision_History" name="Revision_History"></a>Revision History
+ </h1>
+ <table width="100%">
+ <tr>
+ <th class="TableHeading" width="25%">
+ Version
+ </th>
+ <th class="TableHeading" width="50%">
+ Version Information
+ </th>
+ <th class="TableHeading">
+ Date
+ </th>
+ </tr>
+ <tr>
+ <td class="TableCell" width="25%">
+ Initial version
+ </td>
+ <td class="TableCell" width="25%">
+ Nadya Morozova, Stepan Mishura: document created<br />
+ Special thanks to Sergey Dmitriev for assistance
+ </td>
+ <td class="TableCell">
+ November 16, 2005
+ </td>
+ </tr>
+ <tr>
+ <td class="TableCell" width="25%">
+ Formatting update
+ </td>
+ <td class="TableCell" width="25%">
+ Nadya Morozova
+ </td>
+ <td class="TableCell">
+ September 21, 2006
+ </td>
+ </tr>
+ </table>
+ <h1>
+ <a id="Disclaimer" name="Disclaimer"></a>Disclaimer and Legal
+ Information
+ </h1>
+ <p>
+ Copyright 2005 The Apache Software Foundation or its licensors, as
+ applicable.
+ </p>
+ <p>
+ Licensed under the Apache License, Version 2.0 (the "License"); you
+ may not use this file except in compliance with the License. You may
+ obtain a copy of the License at <a
+ href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>.
+ </p>
+ <p>
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
+ permissions and limitations under the License.
+ </p>
+ <h1>
+ <a id="About_this_document" name="About_this_document"></a>About This
+ Document
+ </h1>
+ <h2>
+ <a id="Purpose" name="Purpose"></a>Purpose
+ </h2>
+ <p>
+ This document introduces the ASN.1 (Abstract Syntax Notation)
+ framework delivered as part of the Harmony classlibrary. This document
+ provides an overview of ASN.1 types and encoding rules with focus on
+ the characteristics of the current implementation. The document gives
+ details on the framework design and provides an overall description of
+ the ASN.1 package.
+ </p>
+ <h2>
+ <a id="Intended_Audience" name="Intended_Audience"></a>Intended
+ Audience
+ </h2>
+ <p>
+ The target audience for the document includes a wide community of
+ engineers interested in using ASN.1 and in further work with the
+ product to contribute to its development. The document assumes that
+ readers are familiar with the ASN.1 notation and the Java<a
+ href="#*">*</a> programming language.
+ </p>
+ <h2>
+ <a id="Documentation_Conventions"
+ name="Documentation_Conventions"></a>Documentation Conventions
+ </h2>
+ <p>
+ This document uses the <a href="conventions.htm">unified
+ conventions</a> for the Harmony documentation kit.
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ <a id="Overview" name="Overview"></a>Introduction to ASN.1
+ </h1>
+ <h2>
+ <a id="About" name="About"></a>About
+ </h2>
+ <p>
+ ASN.1 (Abstract Syntax Notation One) is an international standard of
+ notation used to specify data structures with a high level of
+ abstraction, which is reflected in the ASN.1 specification [<a
+ href="#ASN_SPEC">2</a>]. ASN.1 is fully platform- and
+ language-independent. ASN.1 goes with the <i>encoding rules</i>, which
+ determine how to represent a value of an abstract type as a string of
+ octets [<a href="#RULES_SPEC">3</a>].
+ </p>
+ <p>
+ The Java<a href="#*">*</a> API specification [<a
+ href="#JAVA_API_SPEC">1</a>] employs ASN.1 in the following ways:
+ </p>
+ <ul>
+ <li>
+ <i>Directly</i>: by providing the ASN.1 notation for used data and
+ by specifying its encoding rule
+ </li>
+ <li>
+ <i>Indirectly</i>: by refereeing to another (external)
+ specification that uses the ASN.1 notation
+ </li>
+ </ul>
+ <p>
+ To learn more about ASN.1, you can use online documentation [<a
+ href="#INFO_SITE">4</a>], [<a href="#LAYMAN_GUIDE">5</a>], and
+ publications [<a href="#EBOOK1">6</a>], [<a href="#EBOOK2">7</a>].
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Basic_Types" name="Basic_Types"></a>ASN.1 Basic Types
+ </h2>
+ <p>
+ ASN.1 has the following basic types:
+ </p>
+ <ul>
+ <li>
+ <a href="#String"><i>String</i></a> and <a
+ href="#Primitive"><i>primitive</i></a> types represent raw data.
+ </li>
+ <li>
+ <a href="#Constructed"><i>Constructed</i></a> types serve as
+ containers for a number of type components, which can be optional
+ or can have default values.
+ </li>
+ <li>
+ <a href="#Tagged"><i>Tagged</i></a> types are used to derive one
+ ASN.1 type from another.
+ </li>
+ <li>
+ <a href="#Other"><i>Other</i></a> types are <code>ANY</code> and
+ <code>CHOICE</code>.
+ </li>
+ </ul>
+ <p>
+ These types are used to specify a wide range of other abstract types,
+ as shown in Example 1.
+ </p>
+ <p class="example">
+ <a id="example1" name="example1"></a>Example 1
+ </p>
+ <p class="exampletext">
+ This example is based on RFC 3280 [<a href="#RFC">8</a>].
+ </p>
+ <blockquote>
+<pre>
+Extensions ::= SEQUENCE SIZE (1..MAX) OF Extension
+
+Extension ::= SEQUENCE {
+ extnID OBJECT IDENTIFIER,
+ critical BOOLEAN DEFAULT FALSE,
+ extnValue OCTET STRING
+}
+
+Version ::= INTEGER { v1(0), v2(1), v3(2) }
+</pre>
+ </blockquote>
+ <p>
+ In this example, the basic ASN.1 types <code>SEQUENCE</code>,
+ <code>OBJECT IDENTIFIER</code>, <code>BOOLEAN</code> and <code>OCTET
+ STRING</code> are used to specify a new abstract type
+ <code>Extension</code>. The newly created type is then used with
+ another basic type <code>SEQUENCE OF</code> to describe the
+ <code>Extensions</code> type. The ASN.1 <code>INTEGER</code> type is
+ used to specify the <code>Version</code> abstract type and to provide
+ constraints for this type.
+ </p>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h1>
+ <a id="Implementation" name="Implementation"></a>ASN.1 Framework in
+ Harmony
+ </h1>
+ <p>
+ This section part of the document describes the ASN.1 framework as a
+ whole, defines the mapping principles to establish the correspondence
+ between ASN.1 and Java<a href="#*">*</a> types, and represents the
+ hierarchy of ASN.1 types representation in the current framework.
+ </p>
+ <h2>
+ <a id="About_ASN_Framework" name="About_ASN_Framework"></a>About
+ </h2>
+ <p>
+ The ASN.1 framework provides a common, easy and efficient approach for
+ working with ASN.1 basic types, notations and encoding rules. This
+ framework can be described as a layer between a Java<a href="#*">*</a>
+ object and its ASN.1 encoded form, as shown in Figure 1.
+ </p>
+ <br />
+ <br />
+ <p style="text-align: center">
+ <img src="images/ASN_framework.gif" alt="overview" />
+ </p>
+ <p class="special" style="text-align: center">
+ Figure 1: ASN.1 Framework Layer
+ </p>
+ <p>
+ The Harmony ASN.1 framework is characterized by:
+ </p>
+ <ul>
+ <li>
+ A clear API for decoding and encoding objects
+ </li>
+ <li>
+ Low resource consuming
+ </li>
+ <li>
+ Thread safety
+ </li>
+ </ul>
+ <p>
+ The framework enables the following:
+ </p>
+ <ul>
+ <li>
+ Create a Java<a href="#*">*</a> object instance from its encoded
+ octet string
+ </li>
+ <li>
+ Verify that an octet string is a valid encoded string
+ </li>
+ <li>
+ Generate an encoded octet string for a particular object
+ </li>
+ </ul>
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ The current ASN.1 framework is a partial implementation of the ASN.1
+ and encoding rules specifications. This framework covers certain ASN.1
+ basic types and basic encoding rules (BER), and provides most
+ restrictions employed by the distinguished encoding rules (DER).
+ </p>
+ <h2>
+ <a id="Mapping_ASN_Java" name="Mapping_ASN_Java"></a>Mapping between
+ ASN.1 and Java<a href="#*">*</a> Types
+ </h2>
+ <p>
+ The framework maps all ASN.1 abstract types and notations to Java<a
+ href="#*">*</a> primitive types or Java<a href="#*">*</a> classes.
+ </p>
+ <p class="example">
+ <a id="example2" name="example2"></a>Example 2
+ </p>
+ <p class="exampletext">
+ The notations in <a href="#example1">Example 1</a> can be represented
+ as the following Java<a href="#*">*</a> classes:
+ </p>
+ <blockquote>
+<pre>
+public class Extension {
+ private String extnID;
+ private boolean critical;
+ private byte extnValue[];
+}
+
+public class Extensions {
+ // contains elements of Extension class
+ private List extensions;
+}
+</pre>
+ </blockquote>
+ <p>
+ The <code>Extension</code> notation corresponds to a Java<a
+ href="#*">*</a> class with three fields, where every field corresponds
+ to one entry in the <code>Extension</code> notation. For example, the
+ <code>critical BOOLEAN DEFAULT FALSE</code> field in the
+ <code>Extension</code> notation corresponds to the <code>boolean
+ critical</code> field in the Java<a href="#*">*</a> class. The
+ <code>Extensions</code> notation equals to a Java<a href="#*">*</a>
+ class with a field that contains an ordered collection of the
+ instances of the <code>Extension</code> class.
+ </p>
+ <p>
+ The table below describes the default mapping ASN.1 types to Java<a
+ href="#*">*</a> types, and indicates the class providing the specified
+ mapping in the current framework.
+ </p>
+ <table cellspacing="0" cellpadding="0" align="center"
+ width="60%">
+ <tr>
+ <th class="TableHeading" colspan="2">
+ ASN.1 Type
+ </th>
+ <th class="TableHeading" style="text-align: center"
+ width="25%">
+ Java<a href="#*">*</a> Type
+ </th>
+ <th class="TableHeading" width="30%">
+ Framework Class
+ </th>
+ </tr>
+ <tr>
+ <th class="TableHeading" rowspan="5" width="11%">
+ <a id="Primitive" name="Primitive">Primitive</a>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>INTEGER</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="25%">
+ <code><a href="#ASN1Integer">ASN1Integer</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>ENUMERATED</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Enumerated">ASN1Enumerated</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>OBJECT IDENTIFIER</code>
+ </td>
+ <td align="center" width="25%">
+ <code>int[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Oid">ASN1Oid</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>BOOLEAN</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.Boolean</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Boolean">ASN1Boolean</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th class="TableHeading" rowspan="12" width="11%">
+ <a id="String" name="String">String</a>
+ </th>
+ <td width="30%">
+ <code>BitString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>asn1.BitString</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1BitString">ASN1BitString</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>OctetString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1OctetString">ASN1OctetString</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>PrintableString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>T61String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>IA5String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UTF8String</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>BMPString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>GeneralString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>TeletexString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UniversalString</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.lang.String</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1StringType">ASN1StringType</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>UTCTime</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.Date</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1UTCTime">ASN1UTCTime</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>GeneralizedTime</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.Date</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1UTCTime">ASN1GeneralizedTime</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="3" class="TableHeading">
+ <a id="Constructed" name="Constructed">Constructed</a>
+ </th>
+ <td width="30%">
+ <code>SEQUENCE</code>
+ </td>
+ <td align="center" width="25%">
+ <code>Object[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1Sequence">ASN1Sequence</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>SEQUENCE OF</code>
+ </td>
+ <td align="center" width="25%">
+ <code>java.util.List</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1SequenceOf">ASN1SequenceOf</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>SET OF</code>
+ </td>
+ <td width="25%" align="center">
+ <code>java.util.List</code>
+ </td>
+ <td width="30%">
+ <code><a href="#ASN1SetOf">ASN1SetOf</a></code>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="2" width="11%" class="TableHeading">
+ <a id="Tagged" name="Tagged">Tagged</a>
+ </th>
+ <td width="30%">
+ <code>EXPLICIT</code>
+ </td>
+ <td width="25%" style="text-align: center">
+ <i>based type</i>
+ </td>
+ <td width="30%">
+ <a href="#ASN1Explicit"><code>ASN1Explicit</code></a>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>IMPLICIT</code>
+ </td>
+ <td align="center" width="25%" style="text-align: center">
+ <i>based type</i>
+ </td>
+ <td width="30%">
+ <a href="#Class_ASNImplicit"><code>ASN1Implicit</code></a>
+ </td>
+ </tr>
+ <tr>
+ <th rowspan="2" width="11%" class="TableHeading">
+ <a id="Other" name="Other">Other</a>
+ </th>
+ <td width="30%">
+ <code>ANY</code>
+ </td>
+ <td align="center" width="25%">
+ <code>byte[]</code>
+ </td>
+ <td width="30%">
+ <code><a href="#Class_ASNAny">ASN1Any</a></code>
+ </td>
+ </tr>
+ <tr>
+ <td width="30%">
+ <code>CHOICE</code>
+ </td>
+ <td align="center" width="25%" style="text-align: center">
+ <i>one of chosen types</i>
+ </td>
+ <td width="30%">
+ <code><a href="#Class_ASNChoice">ASN1Choice</a></code>
+ </td>
+ </tr>
+ </table>
+ <p class="backtotop">
+ <a href="#Top">Back to Top</a>
+ </p>
+ <h2>
+ <a id="Harmony_Classes" name="Harmony_Classes"></a>Harmony ASN.1
+ Classes
+ </h2>
+ <p>
+ Basic ASN.1 types are in the
+ <code>org.apache.harmony.security.asn1</code> package in accordance
+ with the hierarchy shown in Figure 2.
+ </p>
+ <p style="text-align: center">
+ <img src="images/package_content.gif" alt="package" width="469"
+ height="352" />
+ </p>
+ <p class="special">
+ Figure 2: Class Hierarchy
+ </p>
+ <p>
+ The subsequent sections provide as short description of the classes
+ included in the package.
+ </p>
+ <p class="class">
+ <a id="Primitive_Types" name="Primitive_Types"></a>Primitive Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Integer" name="ASN1Integer"></a>ASN1Integer
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>INTEGER</code> type that
+ denotes an arbitrary integer with positive, negative, or zero
+ values and any magnitude. Because an integer value is not
+ restricted, it is up to the application class to choose the Java<a
+ href="#*">*</a> type for storing the integer value, for example, an
+ instance of the <code>java.math.BigInteger</code> class. By
+ default, an integer value is stored in an array of bytes.
+ </dd>
+ <dt>
+ <a id="ASN1Enumerated" name="ASN1Enumerated"></a> ASN1Enumerated
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>ENUMERATED</code> type that
+ denotes a set of integer values. The implementation of this class
+ is similar to that of the <code>ASN1Integer</code> class.
+ </dd>
+ <dt>
+ <a id="ASN1Oid" name="ASN1Oid"></a>ASN1Oid
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>OBJECT IDENTIFIER</code>
+ type. This type is a sequence of integer components that identifies
+ an entity, such as an organization or an algorithm. Integer
+ components have no negative values. An <code>OBJECT
+ IDENTIFIER</code> value includes at least two components. The
+ corresponding Java<a href="#*">*</a> type is an array of integer
+ values.
+ </dd>
+ <dt>
+ <a id="ASN1Boolean" name="ASN1Boolean"></a> ASN1Boolean
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>BOOLEAN</code> type, which
+ corresponds to the <code>java.lang.Boolean</code> Java<a
+ href="#*">*</a> class.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="String_Types" name="String_Types"></a>String Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1StringType" name="ASN1StringType"></a>ASN1StringType
+ </dt>
+ <dd>
+ This is an abstract class that contains common functionality for
+ all ASN.1 string types, and includes the implementation of the
+ following types: <code>BMPString, IA5String, GeneralString,
+ PrintableString, TeletexString, UniversalString,</code> and
+ <code>UTF8String</code>. The class maps all these types to the
+ <code>java.lang.String</code> object.
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ The current implementation does not verify allowed characters
+ for any of ASN.1 restricted characters types. The class only
+ stores and retrieves contents bytes to and from the
+ <code>String</code> object.
+ </p>
+ </dd>
+ </dl>
+ <dl>
+ <dt>
+ <a id="ASN1BitString" name="ASN1BitString"></a>ASN1BitString
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>BitString</code> type. The
+ corresponding Java<a href="#*">*</a> class is
+ <code>BitString</code> included in the <code>asn1</code> package.
+ The class provides implementation for decoding or encoding
+ <code>BitString</code> objects.
+ <p class="note">
+ Note
+ </p>
+ <p class="notetext">
+ A special use case for this ASN.1 type exists, when the type is
+ declared as <code>Named BitString</code>. For example:
+ </p>
+ <blockquote>
+ <blockquote>
+<pre>
+ Keys ::= BIT STRING {
+ Key1 (0),
+ Key2 (1),
+ MyKey (2)
+ }
+</pre>
+ </blockquote>
+ </blockquote>
+ <p class="notetext">
+ In this case, the BER specification [<a
+ href="#RULES_SPEC">3</a>] enables adding and removing any number
+ of trailing to and from the basic encoding. To provide a correct
+ type implementation, use the
+ <code>ASN1Bitstring.ASN1NamedBitList</code> class. By default,
+ the class maps the ASN.1 <code>Named BitString</code> type to an
+ array of primitive boolean values.
+ </p>
+ </dd>
+ <dt>
+ <a id="ASN1OctetString" name="ASN1OctetString"></a>ASN1OctetString
+ </dt>
+ <dd>
+ This class implements the ASN.1 <code>OctetString</code> type,
+ which corresponds to the Java<a href="#*">*</a> type of an array of
+ bytes.
+ </dd>
+ </dl>
+ <dl>
+ <dt>
+ <a id="ASN1UTCTime" name="ASN1UTCTime"></a> ASN1UTCTime
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>UTCTime</code> type. The
+ corresponding Java<a href="#*">*</a> class is
+ <code>java.util.Date</code>.
+ </dd>
+ <dt>
+ <a id="ASN1GeneralizedTime"
+ name="ASN1GeneralizedTime"></a>ASN1GeneralizedTime
+ </dt>
+ <dd>
+ This class represents the ASN.1 <code>GeneralizedTime</code> type.
+ The corresponding Java<a href="#*">*</a> class is
+ <code>java.util.Date</code>.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Constructed_Types" name="Constructed_Types"></a>Constructed
+ Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Sequence" name="ASN1Sequence"></a> ASN1Sequence
+ </dt>
+ <dd>
+ The class represents a ASN.1 type consisting of an ordered
+ collection of more than one type. A type in the collection can be
+ optional or can have default values. If a type in the collection is
+ marked as optional or default, then its value may be absent in the
+ encoding of the sequence type. If a default type is absent, then
+ its default value is used.<br />
+ An instance of the class is initialized with a Java<a
+ href="#*">*</a> array of ASN.1 classes that corresponds to the
+ notation of a sequence type. The order of ASN.1 classes in an
+ initialization array must strictly correspond to the type.<br />
+ For example, if a sequence type has the following types collection:
+ <code>integer</code>, <code>boolean</code>, <code>ANY</code>, then
+ an initialization array must contain three class instances in the
+ same order: <code>ASN1Boolean</code>, <code>ASN1Integer</code>,
+ <code>ASN1Any</code>.
+ </dd>
+ <dt>
+ <a id="ASN1SequenceOf" name="ASN1SequenceOf"></a>ASN1SequenceOf
+ </dt>
+ <dd>
+ The <code>SEQUENCE OF</code> type denotes an ordered collection of
+ one or more values of the selected ASN.1 type. An instance of the
+ class is initialized with an instance of the ASN.1 class according
+ to the type notation. The passed instance is used to decode or
+ encode all values in an collection.
+ </dd>
+ <dt>
+ <a id="ASN1SetOf" name="ASN1SetOf"></a>ASN1SetOf
+ </dt>
+ <dd>
+ The <code>SET OF</code> type denotes an unordered collection of one
+ or more values of the selected ASN.1 type. This class is similar to
+ the <code>ASN1SequenceOf</code> class.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Tagged_Types" name="Tagged_Types"></a>Tagged Types
+ </p>
+ <dl>
+ <dt>
+ <a id="ASN1Explicit" name="ASN1Explicit"></a>ASN1Explicit
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>EXPLICIT</code> type tagging.
+ <em>Explicit tagging</em> denotes a type derived from another type
+ by adding an outer tag to the base type. This type can be
+ represented as a sequence type with only one component, so that the
+ implementation class acts as a container for another ASN.1 type.
+ </dd>
+ <dt>
+ <a id="Class_ASNImplicit" name="Class_ASNImplicit"></a>ASN1Implicit
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>IMPLICIT</code> type tagging.
+ An <em>implicitly tagged type</em> is a type derived from another
+ type by changing a tag of the base type. The implementation class
+ for this type changes only the tag when decoding or encoding the
+ base type.
+ </dd>
+ </dl>
+ <p class="class">
+ <a id="Other_Types" name="Other_Types"></a>Other Types
+ </p>
+ <dl>
+ <dt>
+ <a id="Class_ASNAny" name="Class_ASNAny"></a>ASN1Any
+ </dt>
+ <dd>
+ The class implements the ASN.1 <code>ANY</code> type. The type
+ denotes any ASN.1 type that can be defined by a value of the
+ <code>OBJECT IDENTIFIER</code> or by an integer index. The class
+ handles only raw data represented as a Java<a href="#*">*</a> byte
+ array. It is up to the application class to select the appropriate
+ decoder or encoder for retrieving or storing the content
+ respectively.
+ </dd>
+ <dt>
+ <a id="Class_ASNChoice" name="Class_ASNChoice"></a>ASN1Choice
[... 516 lines stripped ...]