Google Git
Sign in
apache / harmony-classlib / 16a7ff87a45d2a161581f0a8797c0a582c5ee343 / . / doc / security / ASN1Framework.htm
blob: b59eabf2f001f1945966f8bacccc13bcef97e87f [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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
-->
<!DOCTYPE html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<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 align="center"><A 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 name="Revision_History"></A>Revision History</H1>
<TABLE width="100%">
<TR>
<TD class="TableHeading" width="25%"> Version </TD>
<TD class="TableHeading" width="50%"> Version Information </TD>
<TD class="TableHeading"> Date </TD>
</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%"> </TD>
<TD class="TableCell" width="25%"> </TD>
<TD class="TableCell"> </TD>
</TR>
</TABLE>
<H1><A 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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 name="About_this_document"></A>About This Document</H1>
<H2><A 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 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 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 name="Overview"></A>Introduction to ASN.1</H1>
<H2><A 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><I>Indirectly</I>: by refereeing to another (external) specification that uses the ASN.1 notation
</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 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><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><A href="#Tagged"><I>Tagged</I></A> types are used to derive one ASN.1 type from another.
<LI><A href="#Other"><I>Other</I></A> types are <CODE>ANY</CODE> and <CODE>CHOICE</CODE>.
</UL>
<P>These types are used to specify a wide range of other abstract types, as shown in Example 1. </P>
<H3><a name="example1"></a>Example 1</H3>
<p>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 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 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>
<P></P>
<P 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>Low resource consuming
<LI>Thread safety
</UL>
<P>The framework enables the following:</P>
<UL>
<LI>Create a Java<A href="#*">*</A> object instance from its encoded octet string
<LI>Verify that an octet string is a valid encoded string
<LI>Generate an encoded octet string for a particular object
</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 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>
<H3><a name="example2"></a>Example 2 </H3>
<P>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 border="1" cellspacing="0" cellpaDDing="0" align="center" width="60%">
<TR>
<TD valign="top" class="TableHeading" colspan="2"> ASN.1
Type </TD>
<TD valign="top" class="TableHeading" style="text-align: center" width="25%">
Java<A href="#*">*</A> Type </TD>
<TD valign="top" class="TableHeading" width="30%">
Framework Class </TD>
</TR>
<TR>
<TD rowspan="5" class="TableCell" width="11%"><A 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>
<TD class="TableCell" rowspan="12" width="11%"><A name="String">String</A>
</TD>
<TD valign="top" width="30%"> <CODE>BitString</CODE></TD>
<TD valign="top" align="center" width="25%"> <CODE>asn1.BitString</CODE> </TD>
<TD valign="top" 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>
<TD rowspan="3" class="TableCell"> <A name="Constructed">Constructed</A>
</TD>
<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>
<TD rowspan="2" width="11%" class="TableCell"><A name="Tagged">Tagged</A>
</TD>
<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>
<TD rowspan="2" width="11%" class="TableCell"><A name="Other">Other</A> </TD>
<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 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 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 name="Primitive_Types"></A>Primitive Types</P>
<DL>
<DT><A 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 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 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 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 name="String_Types"></A>String Types</p>
<DL>
<DT><a 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 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 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 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 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 name="Constructed_Types"></A>Constructed Types</p>
<DL>
<dt><A 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 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 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 name="Tagged_Types"></a>Tagged Types</p>
<DL>
<dt><A 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 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 name="Other_Types"></a>Other Types</p>
<DL>
<dt><A 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 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 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> <CODE>BerOutputStream</CODE> and <CODE>DerOutputStream</CODE> provide the
encoding functionality.
</UL>
<P class="backtotop"><A href="#Top">Back to Top</A></P>
<H3><A 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>length octets
<LI>content octets
<LI>end-of-content octets
</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> <em>Encoding</em>: The DER encoder retrieves stored information,
encodes it according to the rules and writes the encoding to the allocated byte array.
</UL>
<H3><A 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 name="Notations_Implementation"></A>Implementing ASN.1 Notations</H2>
<H3><A 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>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.
</UL>
<P class="backtotop"><A href="#Top">Back to Top</A></P>
<H3><A 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>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.
</ul>
<H3>Example 3</H3>
<P>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 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 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 name="References"></A>References</H1>
<P>[<a 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 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 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 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 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 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 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 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>
<P></P>
<P></P>
<P><A name="*">*</A> Other brands and names are the property of their respective
owners.</P>
</BODY>
</HTML>