<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Asn1</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/asn1-1.8.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>ASN.1</strong><br><strong>User's Guide</strong><br><small>Version 1.8</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="loadscrollpos" title="Asn1" expanded="true">Asn1<ul>
<li><a href="asn1_ug.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="asn1_ug.html#id65278">Introduction</a></li>
<li title="Getting Started with Asn1"><a href="asn1_ug.html#id59140">Getting Started with Asn1</a></li>
<li title="The Asn1 Application User Interface"><a href="asn1_ug.html#id59751">The Asn1 Application User Interface</a></li>
<li title="Multi File Compilation"><a href="asn1_ug.html#id64500">Multi File Compilation</a></li>
<li title="The ASN.1 Types"><a href="asn1_ug.html#id64631">The ASN.1 Types</a></li>
<li title="Naming of Records in .hrl Files"><a href="asn1_ug.html#id70609">Naming of Records in .hrl Files</a></li>
<li title="ASN.1 Values"><a href="asn1_ug.html#id70752">ASN.1 Values</a></li>
<li title="Macros"><a href="asn1_ug.html#id70833">Macros</a></li>
<li title="ASN.1 Information Objects (X.681)"><a href="asn1_ug.html#id70849">ASN.1 Information Objects (X.681)</a></li>
<li title="Parameterization (X.683)"><a href="asn1_ug.html#id70992">Parameterization (X.683)</a></li>
<li title="Tags"><a href="asn1_ug.html#id71035">Tags</a></li>
<li title="Encoding Rules"><a href="asn1_ug.html#id71184">Encoding Rules</a></li>
</ul>
</li>
<li id="no" title="Specialized Decodes" expanded="false">Specialized Decodes<ul>
<li><a href="asn1_spec.html">
Top of chapter
</a></li>
<li title="Exclusive Decode"><a href="asn1_spec.html#id71372">Exclusive Decode</a></li>
<li title="Selective Decode"><a href="asn1_spec.html#id71731">Selective Decode</a></li>
<li title="Performance"><a href="asn1_spec.html#id72116">Performance</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 Asn1</h1>
<h3><a name="id65278">1.1
Introduction</a></h3>
<h4>Features</h4>
<p>The Asn1 application provides:
</p>
<ul>
<li>An ASN.1 compiler for Erlang, which generates encode and
decode functions to be used by Erlang programs sending and
receiving ASN.1 specified data.</li>
<li>Run-time functions used by the generated code.</li>
<li>The supported encoding rules are:
<ul>
<li>
Basic Encoding Rules (<strong>BER</strong>)
</li>
<li>
Distinguished Encoding Rules (<strong>DER</strong>), a specialized form of BER that is used in security-conscious applications.
</li>
<li>
Packed Encoding Rules (<strong>PER</strong>) both the aligned and unaligned variant.
</li>
</ul>
</li>
</ul>
<h4>Overview</h4>
<p>ASN.1 (Abstract Syntax Notation 1) is a formal language for describing data structures to be exchanged between distributed computer systems.
The purpose of ASN.1 is to have
a platform and programming language independent notation to express
types using a
standardized set of rules for the transformation of values of
a defined type, into a stream of bytes. This stream of bytes
can then be sent on a communication channel set up by the
lower layers in the stack of communication protocols e.g.
TCP/IP or encapsulated within UDP packets. This way, two
different applications written in two completely different
programming languages running on different computers with
different internal representation of data can exchange
instances of structured data types (instead of exchanging
bytes or bits). This makes programming faster and easier since no code
has to be written to process the transport format of the
data.
</p>
<p>To write a network application which processes ASN.1 encoded
messages, it is prudent and sometimes essential to have a set
of off-line development tools such as an ASN.1 compiler which
can generate the encode and decode logic for the specific ASN.1
data types. It is also necessary to combine this with some
general language-specific runtime support for ASN.1 encoding and
decoding.
</p>
<p>The ASN.1 compiler must be directed towards a target language
or a set of closely related languages. This manual describes a
compiler which is directed towards the functional language
Erlang. In order to use this compiler, familiarity with the
language Erlang is essential. Therefore, the runtime support for ASN.1 is
also closely related to the language Erlang and
consist of a number of functions, which the
compiler uses. The types in ASN.1 and how to represent
values of those types in Erlang are described in this manual.
</p>
<p>The following document is structured so that the first part describes
how to use ASN.1 compiler, and then there are descriptions of all
the primitive and constructed ASN.1 types and their representation
in Erlang,
</p>
<h4>Prerequisites</h4>
<p>It is assumed that the reader is familiar with the ASN.1 notation
as documented in the standard definition [X.680] which is
the primary text. It may also be helpful, but not necessary,
to read the standard definitions
[X.681] [X.682] [X.683]
[X.690] [X.691]. </p>
<p>A very good book explaining those reference texts is
[DUBUISSON], free to download at
<span class="bold_code"><a href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html </a></span>.
</p>
<h4>Capability</h4>
<p>This application covers all features of ASN.1 up to the 1997
edition of the specification. In the 2002 edition of ASN.1 a number of
new features where introduced of which some are supported while
others are not. For example the
ECN (Encoding Control Notation) and XML notation are still
unsupported. Though, the other features of the 2002 edition are
fully or partly supported as shown below:</p>
<ul>
<li>
<p>Decimal notation (e.g., "1.5e3") for REAL values. The
NR1, NR2 and NR3 formats as explained in ISO6093 are
supported.</p>
</li>
<li>
<p>The RELATIVE-OID type for relative object identifiers are
fully supported.</p>
</li>
<li>
<p>The subtype constraint (CONTAINING/ENCODED BY) to
constrain the content of an octet string or a bit string is
parsed when compiling, but no further action is taken. This
constraint is not a PER-visible constraint.</p>
</li>
<li>
<p>The subtype constraint by regular expressions (PATTERN) for character string types is parsed when compiling, but no further action is taken. This constraint is not a PER-visible constraint.</p>
</li>
<li>
<p>Multiple-line comments as in C, <span class="code">/* ... */</span>, are
supported.</p>
</li>
</ul>
<p>It should also be added here that the encoding formats
supported are <strong>BER</strong>, <strong>DER</strong>, <strong>PER aligned
basic</strong> variant and <strong>PER unaligned basic</strong> variant.</p>
<h3><a name="id59140">1.2
Getting Started with Asn1</a></h3>
<h4>A First Example</h4>
<p>The following example demonstrates the basic functionality used to run
the Erlang ASN.1 compiler.</p>
<p>First, create a file called <span class="code">People.asn</span> containing the following:</p>
<div class="example"><pre>
People DEFINITIONS IMPLICIT TAGS ::=
BEGIN
EXPORTS Person;
Person ::= [PRIVATE 19] SEQUENCE {
name PrintableString,
location INTEGER {home(0),field(1),roving(2)},
age INTEGER OPTIONAL }
END </pre></div>
<p>This file (<span class="code">people.asn</span>) must be compiled before it can be
used.
The ASN.1 compiler checks that the syntax is correct and that the
text represents proper ASN.1 code before generating an abstract
syntax tree. The code-generator then uses the abstract syntax
tree in order to generate code.
</p>
<p>The generated Erlang files will be placed in the current directory or
in the directory specified with the <span class="code">{outdir,Dir}</span> option.
The following shows how the compiler
can be called from the Erlang shell:</p>
<div class="example"><pre>
1><span class="bold_code">asn1ct:compile("People",[ber_bin]).</span>
Erlang ASN.1 compiling "People.asn"
--{generated,"People.asn1db"}--
--{generated,"People.hrl"}--
--{generated,"People.erl"}--
ok
2> </pre></div>
<p>The ASN.1 module People is now accepted and the abstract syntax tree
is saved in the <span class="code">People.asn1db</span> file, the
generated Erlang code is compiled using the Erlang compiler and
loaded into the Erlang runtime system. Now there is a user interface
of encode/2 and decode/2 in the module People, which is invoked by:
<br>
<span class="code">'People':encode(<Type name>,<Value>),</span> <br>
or <br>
<span class="code">'People':decode(<Type name>,<Value>),</span> <br>
Alternatively one can use the <span class="code">asn1rt:encode(<Module name> ,<Type name>,<Value>)</span> and <span class="code">asn1rt:decode(< Module name>,<Type name>,<Value>)</span> calls.
However, they are not as efficient as the previous methods since they
result in an additional <span class="code">apply/3</span> call.</p>
<p>Assume there is a network
application which receives instances of the ASN.1 defined
type Person, modifies and sends them back again:</p>
<div class="example"><pre>
receive
{Port,{data,Bytes}} ->
case 'People':decode('Person',Bytes) of
{ok,P} ->
{ok,Answer} = 'People':encode('Person',mk_answer(P)),
Port ! {self(),{command,Answer}};
{error,Reason} ->
exit({error,Reason})
end
end, </pre></div>
<p>In the example above, a series of bytes is received from an
external source and the bytes are then decoded into a valid
Erlang term. This was achieved with the call
<span class="code">'People':decode('Person',Bytes)</span> which returned
an Erlang value of the ASN.1 type <span class="code">Person</span>. Then an answer was
constructed and encoded using
<span class="code">'People':encode('Person',Answer)</span> which takes an
instance of a defined ASN.1 type and transforms it to a
(possibly) nested list of bytes according to the BER or PER
encoding-rules.
<br>
The encoder and the decoder can also be run from
the shell. The following dialogue with the shell illustrates
how the functions
<span class="code">asn1rt:encode/3</span> and <span class="code">asn1rt:decode/3</span> are used.</p>
<div class="example"><pre>
2> <span class="bold_code">Rockstar = {'Person',"Some Name",roving,50}.</span>
{'Person',"Some Name",roving,50}
3> <span class="bold_code">{ok,Bytes} = asn1rt:encode('People','Person',Rockstar).</span>
{ok,[<<243>>,
[17],
[19,9,"Some Name"],
[2,1,[2]],
[2,1,"2"]]}
4> <span class="bold_code">Bin = list_to_binary(Bytes).</span>
<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,2,1,50>>
5> <span class="bold_code">{ok,Person} = asn1rt:decode('People','Person',Bin).</span>
{ok,{'Person',"Some Name",roving,50}}
6> </pre></div>
<p>Notice that the result from <span class="code">encode</span> is a nested list which
must be turned into a binary before the call to <span class="code">decode</span>. A
binary is necessary as input to decode since the module was compiled
with the <span class="code">ber_bin</span> option
The reason for returning a nested list is that it is faster to produce
and the <span class="code">list_to_binary</span> operation is
performed automatically when the list is sent via the Erlang port mechanism.</p>
<h4>Module dependencies</h4>
<p>It is common that asn1 modules import defined types, values and
other entities from another asn1 module.</p>
<p>Earlier versions of the asn1 compiler required that modules that
were imported from had to be compiled before the module that
imported. This caused problems when asn1 modules had circular
dependencies.</p>
<p>Now are referenced modules parsed when the compiler finds an
entity that is imported. There will not be any code generated for
the referenced module. However, the compiled module rely on
that the referenced modules also will be compiled.</p>
<h3><a name="id59751">1.3
The Asn1 Application User Interface</a></h3>
<p>The Asn1 application provides two separate user interfaces:</p>
<ul>
<li>
<p>The module <span class="code">asn1ct</span> which provides the compile-time functions
(including the compiler).</p>
</li>
<li>
<p>The module <span class="code">asn1rt</span> which provides the run-time functions.
However, it is preferable to use the generated <span class="code">encode/2</span> and
<span class="code">decode/2</span> functions in each module, ie.
Module:encode(Type,Value), in favor of the <span class="code">asn1rt</span>
interface.</p>
</li>
</ul>
<p>The reason for the division of the interface into compile-time
and run-time
is that only run-time modules (<span class="code">asn1rt*</span>) need to be loaded in
an embedded system.
</p>
<h4>Compile-time Functions</h4>
<p>The ASN.1 compiler can be invoked directly from the command-line
by means of the <span class="code">erlc</span> program. This is convenient when compiling
many ASN.1 files from the command-line or when using Makefiles.
Here are some examples of how the <span class="code">erlc</span> command can be used to invoke the
ASN.1 compiler:</p>
<div class="example"><pre>
erlc Person.asn
erlc -bper_bin Person.asn
erlc -bber_bin +optimize ../Example.asn
erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn </pre></div>
<p>The useful options for the ASN.1 compiler are:</p>
<dl>
<dt><strong><span class="code">-b[ber | per | ber_bin | per_bin | uper_bin]</span></strong></dt>
<dd>
<p>Choice of encoding rules, if omitted <span class="code">ber</span> is the
default. The <span class="code">ber_bin</span> and <span class="code">per_bin</span> options
allows for optimizations and are therefore recommended
instead of the <span class="code">ber</span> and <span class="code">per</span> options.</p>
</dd>
<dt><strong><span class="code">-o OutDirectory</span></strong></dt>
<dd>
<p>Where to put the generated files, default is the current
directory.</p>
</dd>
<dt><strong><span class="code">-I IncludeDir</span></strong></dt>
<dd>
<p>Where to search for <span class="code">.asn1db</span> files and asn1
source specs in order to resolve references to other
modules. This option can be repeated many times if there
are several places to search in. The compiler will always
search the current directory first.</p>
</dd>
<dt><strong><span class="code">+compact_bit_string</span></strong></dt>
<dd>
<p>Gives the user the option to use a compact format of the BIT
STRING type to save memory space, typing space and
increase encode/decode performance, for details see
<span class="bold_code"><a href="#BIT%20STRING">BIT STRING </a></span>type section.</p>
</dd>
<dt><strong><span class="code">+der</span></strong></dt>
<dd>
<p>DER encoding rule. Only when using <span class="code">-ber</span> or
<span class="code">-ber_bin</span> option.</p>
</dd>
<dt><strong><span class="code">+optimize</span></strong></dt>
<dd>
<p>This flag has effect only when used together with one of
<span class="code">per_bin</span> or <span class="code">ber_bin</span> flags. It gives time optimized
code in the generated modules and it uses another runtime module.
In the <span class="code">per_bin</span> case a nif is used. The
result from an encode is a binary.</p>
<p><strong>When this flag is used you cannot use the old format</strong><span class="code">{TypeName,Value}</span> when you encode values. Since it is
an unnecessary construct it has been removed in favor of
performance. It
is neither admitted to construct SEQUENCE or SET component values
with the format <span class="code">{ComponentName,Value}</span> since it also is
unnecessary. The only case were it is necessary is in a CHOICE,
were you have to pass values to the right component by specifying
<span class="code">{ComponentName,Value}</span>. See also about
<span class="bold_code"><a href="#TypeNameValue">{Typename,Value}</a></span> below
and in the sections for each type.</p>
</dd>
<dt><strong><span class="code">+driver</span></strong></dt>
<dd>
<p>As of R15B this means the same as the <span class="code">nif</span> option. Kept for
backwards compatability reasons.</p>
</dd>
<dt><strong><span class="code">+nif</span></strong></dt>
<dd>
<p>Together with the flags <span class="code">ber_bin</span>
and <span class="code">optimize</span> you choose to use a nif for considerable
faster encode and decode. </p>
</dd>
<dt><strong><span class="code">+asn1config</span></strong></dt>
<dd>
<p>This functionality works together with the flags
<span class="code">ber_bin</span> and <span class="code">optimize</span>. You enables the
specialized decodes, see the <span class="bold_code"><a href="asn1_spec.html">Specialized Decode</a></span> chapter.
</p>
</dd>
<dt><strong><span class="code">+undec_rest</span></strong></dt>
<dd>
<p>A buffer that holds a message, being decoded may
also have some following bytes. Now it is possible to get
those following bytes returned together with the decoded
value. If an asn1 spec is compiled with this option a tuple
<span class="code">{ok,Value,Rest}</span> is returned. <span class="code">Rest</span> may be a
list or a binary. Earlier versions of the compiler ignored
those following bytes.</p>
</dd>
<dt><strong><span class="code">{inline,OutputName}</span></strong></dt>
<dd>
<p>Compiling with this option gives one output module
containing all asn1 run-time functionality. The asn1 specs
are provided in a target module <span class="code">Module.set.asn</span> as
described in the <span class="bold_code"><a href="asn1ct.html#asn1set">reference manual</a></span>. The name of the resulting module
containing generated encode/decode functions and inlined
run-time functions will be <span class="code">OutputName.erl</span>. The
merging/inlining of code is done by the <span class="code">igor</span> module
of <span class="code">syntax_tools</span>. By default the functions generated
from the first asn1 spec in the <span class="code">.set.asn</span> are
exported, unless a <span class="code">{export,[atom()]}</span> or
<span class="code">{export_all,true}</span> option are provided. The list of
atoms are names of choosen asn1 specs from the
<span class="code">.set.asn</span> file. See further examples of usage <span class="bold_code"><a href="#inlineExamples">below</a></span></p>
</dd>
<dt><strong><span class="code">+'Any Erlc Option'</span></strong></dt>
<dd>
<p>You may add any option to the Erlang compiler when
compiling the generated Erlang files. Any option
unrecognised by the asn1 compiler will be passed to the
Erlang compiler.</p>
</dd>
</dl>
<p>For a complete description of <span class="code">erlc</span> see Erts Reference Manual.</p>
<p>For preferred option use see <span class="bold_code"><a href="#preferred%20option%20use">Preferred Option Use</a></span> section.</p>
<p>The compiler and other compile-time functions can also be invoked from
the Erlang shell. Below follows a brief
description of the primary functions, for a
complete description of each function see
<span class="bold_code"><a href="asn1ct.html">the Asn1 Reference Manual</a></span>, the
<span class="code">asn1ct</span> module.</p>
<p>The compiler is invoked by using <span class="code">asn1ct:compile/1</span> with
default options, or <span class="code">asn1ct:compile/2</span> if explicit options
are given.
Example:</p>
<div class="example"><pre>
asn1ct:compile("H323-MESSAGES.asn1"). </pre></div>
<p>which equals:</p>
<div class="example"><pre>
asn1ct:compile("H323-MESSAGES.asn1",[ber]). </pre></div>
<p>If one wants PER encoding with optimizations:</p>
<div class="example"><pre>
asn1ct:compile("H323-MESSAGES.asn1",[per_bin,optimize]). </pre></div>
<p>The generic encode and decode functions can be invoked like this:</p>
<div class="example"><pre>
asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre></div>
<p>Or, preferable like:</p>
<div class="example"><pre>
'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre></div>
<h4>Preferred Option Use</h4>
<a name="preferred%20option%20use"></a>
<p>
It may not be obvious which compile options best fit a
situation. This section describes the format of the result of
encode and decode. It also gives some performance statistics
when using certain options. Finally there is a recommendation
which option combinations should be used.
</p>
<p>
The default option is <span class="code">ber</span>. It is the same backend as
<span class="code">ber_bin</span> except that the result of encode is transformed
to a flat list. Below is a table that gives the different
formats of input and output of encode and decode using the
<strong>allowed combinations</strong> of coding and optimization
options: (EAVF stands for how ASN1 values are represented in
Erlang which is described in the <span class="bold_code"><a href="#ASN1Types">ASN1 Types chapter</a></span>)
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Encoding Rule</strong></td>
<td align="left" valign="middle"><strong>Compile options, allowed combinations</strong></td>
<td align="left" valign="middle"><strong>encode input</strong></td>
<td align="left" valign="middle"><strong>encode output</strong></td>
<td align="left" valign="middle"><strong>decode input</strong></td>
<td align="left" valign="middle"><strong>decode output</strong></td>
</tr>
<tr>
<td align="left" valign="middle">BER</td>
<td align="left" valign="middle">[ber] (default)</td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">flat list</td>
<td align="left" valign="middle">flat list / binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">BER</td>
<td align="left" valign="middle">[ber_bin]</td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">BER</td>
<td align="left" valign="middle"><strong>[ber_bin, optimize]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">BER</td>
<td align="left" valign="middle"><strong>[ber_bin, optimize, nif]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">iolist / binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">PER aligned variant</td>
<td align="left" valign="middle">[per]</td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">flat list</td>
<td align="left" valign="middle">flat list</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">PER aligned variant</td>
<td align="left" valign="middle"><strong>[per_bin]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist / binary</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">PER aligned variant</td>
<td align="left" valign="middle"><strong>[per_bin, optimize]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">PER unaligned variant</td>
<td align="left" valign="middle"><strong>[uper_bin]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">DER</td>
<td align="left" valign="middle">[(ber), der]</td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">flat list</td>
<td align="left" valign="middle">flat list / binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">DER</td>
<td align="left" valign="middle">[ber_bin, der]</td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">DER</td>
<td align="left" valign="middle"><strong>[ber_bin, optimize, der]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
<tr>
<td align="left" valign="middle">DER</td>
<td align="left" valign="middle"><strong>[ber_bin, optimize, nif, der]</strong></td>
<td align="left" valign="middle">EAVF</td>
<td align="left" valign="middle">iolist</td>
<td align="left" valign="middle">binary</td>
<td align="left" valign="middle">EAVF</td>
</tr>
</table>
<em>Table
1.1:
The output / input formats for different combinations of compile options.</em>
<p>
Encode / decode speed comparison in one user case for the above
alternatives (except <span class="code">DER</span>) is showed in the table below. The
<span class="code">DER</span> alternatives are slower than their corresponding
<span class="code">BER</span> alternative.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>compile options</strong></td>
<td align="left" valign="middle"><strong>encode time</strong></td>
<td align="left" valign="middle"><strong>decode time</strong></td>
</tr>
<tr>
<td align="left" valign="middle">[ber]</td>
<td align="left" valign="middle">120</td>
<td align="left" valign="middle">162</td>
</tr>
<tr>
<td align="left" valign="middle">[ber_bin]</td>
<td align="left" valign="middle">124</td>
<td align="left" valign="middle">154</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize]</strong></td>
<td align="left" valign="middle">50</td>
<td align="left" valign="middle">78</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize, driver]</strong></td>
<td align="left" valign="middle">50</td>
<td align="left" valign="middle">62</td>
</tr>
<tr>
<td align="left" valign="middle">[per]</td>
<td align="left" valign="middle">141</td>
<td align="left" valign="middle">133</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[per_bin]</strong></td>
<td align="left" valign="middle">125</td>
<td align="left" valign="middle">123</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[per_bin, optimize]</strong></td>
<td align="left" valign="middle">77</td>
<td align="left" valign="middle">72</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[uper_bin]</strong></td>
<td align="left" valign="middle">97</td>
<td align="left" valign="middle">104</td>
</tr>
</table>
<em>Table
1.2:
One example of difference in speed for the compile option alternatives.
</em>
<p>
The compile options <span class="code">ber</span>, <span class="code">per</span> and
<span class="code">driver</span> are kept for backwards compatibility and should not be
used in new code. The nif implementation which replaces the linked-in
driver has been shown to be about 5-15% faster.
</p>
<p>
You are strongly recommended to use the appropriate alternative
of the bold typed options. The <span class="code">optimize</span> and
<span class="code">nif</span> options does not affect the encode or decode
result, just the time spent in run-time. When <span class="code">ber_bin</span> and
<span class="code">nif</span> or <span class="code">per_bin</span> and <span class="code">optimize</span> is
combined the C-code nif is used in chosen parts of encode /
decode procedure.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Compile options, allowed combinations</strong></td>
<td align="left" valign="middle"><strong>use of nif</strong></td>
</tr>
<tr>
<td align="left" valign="middle">[ber]</td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle">[ber_bin]</td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize]</strong></td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize, nif]</strong></td>
<td align="left" valign="middle">yes</td>
</tr>
<tr>
<td align="left" valign="middle">[per]</td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[per_bin]</strong></td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[per_bin, optimize]</strong></td>
<td align="left" valign="middle">yes</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[uper_bin]</strong></td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle">[(ber), der]</td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle">[ber_bin, der]</td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize, der]</strong></td>
<td align="left" valign="middle">no</td>
</tr>
<tr>
<td align="left" valign="middle"><strong>[ber_bin, optimize, nif, der]</strong></td>
<td align="left" valign="middle">yes</td>
</tr>
</table>
<em>Table
1.3:
When the ASN1 nif is used.</em>
<h4>Run-time Functions</h4>
<p>A brief description of the major functions is given here. For a
complete description of each function see
<span class="bold_code"><a href="asn1rt.html"> the Asn1 Reference Manual</a></span>, the <span class="code">asn1rt</span> module.</p>
<p>The generic run-time encode and decode functions can be invoked as below:</p>
<div class="example"><pre>
asn1rt:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre></div>
<p>Or, preferable like:</p>
<div class="example"><pre>
'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre></div>
<p>The asn1 nif is enabled in two occasions: encoding of
asn1 values when the asn1 spec is compiled with <span class="code">per_bin</span> and
<span class="code">optimize</span> or decode of encoded asn1 values when the asn1 spec is
compiled with <span class="code">ber_bin</span>, <span class="code">optimize</span> and <span class="code">nif</span>. In
those cases the nif will be loaded automatically at the first call
to <span class="code">encode</span>/<span class="code">decode</span>. If one doesn't want the performance
overhead of the nif being loaded at the first call it is possible
to load the nif separately by loading the <span class="code">asn1rt_nif</span> module.</p>
<p>By invoking the function <span class="code">info/0</span> in a generated module, one
gets information about which compiler options were used.</p>
<h4>Errors</h4>
<p>Errors detected at
compile time appear on the screen together with
a line number indicating where in the source file the error
was detected. If no errors are found, an Erlang ASN.1 module will
be created as default.</p>
<p>The run-time encoders and decoders (in the <span class="code">asn1rt</span> module) do
execute within a catch and returns <span class="code">{ok, Data}</span> or
<span class="code">{error, {asn1, Description}}</span> where
<span class="code">Description</span> is
an Erlang term describing the error. </p>
<h3><a name="id64500">1.4
Multi File Compilation</a></h3>
<a name="inlineExamples"></a>
<p>There are various reasons for using a multi file compilation:</p>
<ul>
<li>You want to choose name for the generated module by
any reason. Maybe you need to compile the same specs for
different encoding/decoding standards.</li>
<li>You want only one resulting module.</li>
<li>If it is crucial to have a minimal system. Using
<span class="code">{inline,OutputModule}</span> includes all necessary run-time
functions of the asn1 application, but skips those modules not
used.</li>
<li>Upgrading issues: Even if you upgrade your Erlang system
you may want to continue running the old asn1 run-time
functionality.</li>
<li>Performance issues: If you have an asn1 system with a lot
of cross references you may gain in performance. Measurements
must be done for each case.</li>
</ul>
<p>You may choose either the plain multi file compilation that just
merges the chosen asn1 specs or the <span class="code">{inline,OutputModule}</span>
that also includes the used asn1 run-time functionality.</p>
<p>For both cases you need to specify which asn1 specs you will
compile in a module that must have the extension
<span class="code">.set.asn</span>. You chose name of the module and provide the
names of the asn1 specs. For instance, if you have the specs
<span class="code">File1.asn</span>, <span class="code">File2.asn</span> and <span class="code">File3.asn</span> your
module <span class="code">MyModule.set.asn</span> will look like:</p>
<div class="example"><pre>
File1.asn
File2.asn
File3.asn </pre></div>
<p>If you compile with:</p>
<div class="example"><pre>
~> erlc MyModule.set.asn </pre></div>
<p>the result will be one merged module <span class="code">MyModule.erl</span> with
the generated code from the three asn1 specs. But if you compile
with:</p>
<div class="example"><pre>
~> erlc +"{inline,'OutputModule'}" MyModule.set.asn </pre></div>
<p>the result will be a module <span class="code">OutputModule.erl</span> that
contains all encode/decode functions for the three asn1 specs and
all used functions from the asn1 run-time modules, in this case
<span class="code">asn1rt_ber_bin</span>. In the former case all encode/decode
functions are exported but in the latter only the encode/decode
functions of the first spec in the <span class="code">.set.asn</span>, i.e. those
from <span class="code">File1.asn</span>.
</p>
<h3><a name="id64631">1.5
The ASN.1 Types</a></h3>
<a name="ASN1Types"></a>
<p>This section describes the ASN.1 types including their
functionality, purpose and how values are assigned in Erlang.
</p>
<p>ASN.1 has both primitive and constructed types:</p>
<p></p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Primitive types</strong></td>
<td align="left" valign="middle"><strong>Constructed types</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#BOOLEAN">BOOLEAN</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#SEQUENCE">SEQUENCE</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#INTEGER">INTEGER</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#SET">SET</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#REAL">REAL</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#CHOICE">CHOICE</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#NULL">NULL</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#SOF">SET OF and SEQUENCE OF</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#ENUMERATED">ENUMERATED</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#ANY">ANY</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#BIT%20STRING">BIT STRING</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#ANY">ANY DEFINED BY</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#OCTET%20STRING">OCTET STRING</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#NegotiationTypes">EXTERNAL</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#Character%20Strings">Character Strings</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#NegotiationTypes">EMBEDDED PDV</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#OBJECT%20IDENTIFIER">OBJECT IDENTIFIER</a></span></td>
<td align="left" valign="middle"><span class="bold_code"><a href="#NegotiationTypes">CHARACTER STRING</a></span></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#Object%20Descriptor">Object Descriptor</a></span></td>
<td align="left" valign="middle"></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="bold_code"><a href="#The%20TIME%20types">The TIME types</a></span></td>
<td align="left" valign="middle"></td>
</tr>
</table>
<em>Table
1.4:
The supported ASN.1 types</em>
<a name="TypeNameValue"></a>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Values of each ASN.1 type has its own representation in Erlang
described in the following subsections. Users shall provide
these values for encoding according to the representation, as
in the example below.</p>
</p></div>
</div>
<div class="example"><pre>
Operational ::= BOOLEAN --ASN.1 definition </pre></div>
<p>In Erlang code it may look like:</p>
<div class="example"><pre>
Val = true,
{ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val), </pre></div>
<p>For historical reasons it is also possible to assign ASN.1 values
in Erlang using a tuple notation
with type and value as this</p>
<div class="example"><pre>
Val = {'Operational',true} </pre></div>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<a name="warning"></a>
<p>The tuple notation, <span class="code">{Typename, Value}</span> is only kept
because of backward compatibility and may be withdrawn in a
future release. If the notation is used the <span class="code">Typename</span>
element must be spelled correctly, otherwise a run-time error
will occur.
</p>
<p>If the ASN.1 module is compiled with the flags
<span class="code">per_bin</span> or <span class="code">ber_bin</span> and <span class="code">optimize</span> it is not
allowed to use the tuple notation. That possibility has been
removed due to performance reasons. Neither is it allowed to
use the <span class="code">{ComponentName,Value}</span> notation in case of a
SEQUENCE or SET type.</p>
</p></div>
</div>
<p>Below follows a description of how
values of each type can be represented in Erlang.
</p>
<h4>BOOLEAN</h4>
<a name="BOOLEAN"></a>
<p>Booleans in ASN.1 express values that can be either
TRUE or FALSE.
The meanings assigned to TRUE or FALSE is beyond the scope
of this text. <br>
In ASN.1 it is possible to have:</p>
<div class="example"><pre>
Operational ::= BOOLEAN
</pre></div>
<p>Assigning a value to the type Operational in Erlang is possible by
using the following Erlang code:</p>
<div class="example"><pre>
Myvar1 = true,
</pre></div>
<p>Thus, in Erlang the atoms <span class="code">true</span> and <span class="code">false</span> are used
to encode a boolean value.</p>
<h4>INTEGER</h4>
<a name="INTEGER"></a>
<p>ASN.1 itself specifies indefinitely large integers, and the Erlang
systems with versions 4.3 and higher, support very large
integers, in practice indefinitely large integers.</p>
<p>The concept of sub-typing can be applied to integers as well
as to other ASN.1 types. The details of sub-typing are not
explained here, for further info see [X.680]. A variety
of syntaxes are allowed when defining a type as an integer:</p>
<div class="example"><pre>
T1 ::= INTEGER
T2 ::= INTEGER (-2..7)
T3 ::= INTEGER (0..MAX)
T4 ::= INTEGER (0<..MAX)
T5 ::= INTEGER (MIN<..-99)
T6 ::= INTEGER {red(0),blue(1),white(2)}
</pre></div>
<p>The Erlang representation of an ASN.1 INTEGER is an integer or
an atom if a so called <span class="code">Named Number List</span> (see T6 above)
is specified.</p>
<p>Below is an example of Erlang code which assigns values for the
above types: </p>
<div class="example"><pre>
T1value = 0,
T2value = 6,
T6value1 = blue,
T6value2 = 0,
T6value3 = white
</pre></div>
<p>The Erlang variables above are now bound to valid instances of
ASN.1 defined types. This style of value can be passed directly
to the encoder for transformation into a series of bytes.</p>
<p>The decoder will return an atom if the value corresponds to a
symbol in the Named Number List.</p>
<h4>REAL</h4>
<a name="REAL"></a>
<p>In this version reals are not implemented. When they are,
the following
ASN.1 type is used:</p>
<div class="example"><pre>
R1 ::= REAL
</pre></div>
<p>Can be assigned a value in Erlang as:</p>
<div class="example"><pre>
R1value1 = 2.14,
R1value2 = {256,10,-2},
</pre></div>
<p>In the last line note that the tuple {256,10,-2} is the real number
2.56 in a special notation, which will encode faster than simply
stating the number as 2.56. The arity three tuple is
<span class="code">{Mantissa,Base,Exponent}</span> i.e. Mantissa * Base^Exponent.</p>
<h4>NULL</h4>
<a name="NULL"></a>
<p>Null is suitable in cases where supply and recognition of a value
is important but the actual value is not.</p>
<div class="example"><pre>
Notype ::= NULL
</pre></div>
<p>The NULL type can be assigned in Erlang:</p>
<div class="example"><pre>
N1 = 'NULL',
</pre></div>
<p>The actual value is the quoted atom 'NULL'.</p>
<h4>ENUMERATED</h4>
<a name="ENUMERATED"></a>
<p>The enumerated type can be used, when the value we wish to
describe, may only take one of a set of predefined values.</p>
<div class="example"><pre>
DaysOfTheWeek ::= ENUMERATED {
sunday(1),monday(2),tuesday(3),
wednesday(4),thursday(5),friday(6),saturday(7) }
</pre></div>
<p>For example to assign a weekday value in Erlang use the same atom
as in the <span class="code">Enumerations</span> of the type definition:</p>
<div class="example"><pre>
Day1 = saturday,
</pre></div>
<p>The enumerated type is very similar to an integer type, when
defined with a set of predefined values. An enumerated type
differs from an integer in that it may only have specified
values, whereas an integer can also have any other value.</p>
<h4>BIT STRING </h4>
<a name="BIT%20STRING"></a>
<p>The BIT STRING type can be used to model information which
is made up of arbitrary length series of bits. It is intended
to be used for a selection of flags, not for binary files. <br>
In ASN.1 BIT STRING definitions may look like:
</p>
<div class="example"><pre>
Bits1 ::= BIT STRING
Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
</pre></div>
<p>There are four different notations available for representation of
BIT STRING values in Erlang and as input to the encode functions.</p>
<ul>
<li>A list of binary digits (0 or 1).</li>
<li>A hexadecimal number (or an integer). This format should be
avoided, since it is easy to misinterpret a <span class="code">BIT STRING</span>
value in this format. This format may be withdrawn in a future
release.</li>
<li>A list of atoms corresponding to atoms in the <span class="code">NamedBitList</span>
in the BIT STRING definition.</li>
<li>As <span class="code">{Unused,Binary}</span> where <span class="code">Unused</span> denotes how
many trailing zero-bits 0 to 7 that are unused in the least
significant byte in <span class="code">Binary</span>. This notation is only
available when the ASN.1 files have been compiled with the
<strong>+compact_bit_string</strong> flag in the option list. In
this case it is possible to use all kinds of notation when
encoding. But the result when decoding is always in the
compact form. The benefit from this notation is a more
compact notation when one has large BIT STRINGs. The
encode/decode performance is also much better in the case of
large BIT STRINGs. </li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Note that it is advised not to use the integer format of a
BIT STRING, see the second point above.</p>
</p></div>
</div>
<div class="example"><pre>
Bits1Val1 = [0,1,0,1,1],
Bits1Val2 = 16#1A,
Bits1Val3 = {3,<<0:1,1:1,0:1,1:1,1:1,0:3>>}
</pre></div>
<p>Note that <span class="code">Bits1Val1</span>, <span class="code">Bits1Val2</span> and <span class="code">Bits1Val3</span>
denote the same value.</p>
<div class="example"><pre>
Bits2Val1 = [gnu,punk],
Bits2Val2 = 2#1110,
Bits2Val3 = [bar,gnu,gnome],
Bits2Val4 = [0,1,1,1]
</pre></div>
<p>The above <span class="code">Bits2Val2</span>, <span class="code">Bits2Val3</span> and <span class="code">Bits2Val4</span>
also all denote the same value.</p>
<p><span class="code">Bits2Val1</span> is assigned symbolic values. The assignment means
that the bits corresponding to <span class="code">gnu</span> and <span class="code">punk</span> i.e. bits
2 and 14 are set to 1 and the rest set to 0. The symbolic values
appear as a list of values. If a named value appears, which is not
specified in the type definition, a run-time error will occur.</p>
<p>The compact notation equivalent to the empty BIT STRING is
<span class="code">{0,<<>>}</span>, which in the other notations is <span class="code">[]</span> or
<span class="code">0</span>.</p>
<p>BIT STRINGS may also be sub-typed with for example a SIZE
specification:</p>
<div class="example"><pre>
Bits3 ::= BIT STRING (SIZE(0..31)) </pre></div>
<p>This means that no bit higher than 31 can ever be set.</p>
<h4>OCTET STRING</h4>
<a name="OCTET%20STRING"></a>
<p>The OCTET STRING is the simplest of all ASN.1 types The OCTET STRING
only moves or transfers e.g. binary files or other unstructured
information complying to two rules.
Firstly, the bytes consist of octets and secondly, encoding is
not required.</p>
<p>It is possible to have the following ASN.1 type definitions:</p>
<div class="example"><pre>
O1 ::= OCTET STRING
O2 ::= OCTET STRING (SIZE(28)) </pre></div>
<p>With the following example assignments in Erlang:</p>
<div class="example"><pre>
O1Val = [17,13,19,20,0,0,255,254],
O2Val = "must be exactly 28 chars....", </pre></div>
<p>Observe that <span class="code">O1Val</span> is assigned a series of numbers between 0
and 255 i.e. octets.
<span class="code">O2Val</span> is assigned using the string notation.
</p>
<h4>Character Strings</h4>
<a name="Character%20Strings"></a>
<p>ASN.1 supports a wide variety of character sets. The main difference
between OCTET STRINGS and the Character strings is that OCTET
STRINGS have no imposed semantics on the bytes delivered.</p>
<p>However, when using for instance the IA5String (which closely
resembles ASCII) the byte 65 (in decimal
notation) <strong>means</strong> the character 'A'.
</p>
<p>For example, if a defined type is to be a VideotexString and
an octet is received with the unsigned integer value X, then
the octet should be interpreted as specified in the standard
ITU-T T.100,T.101.
</p>
<p>The ASN.1 to Erlang compiler
will not determine the correct interpretation of each BER
(Basic Encoding Rules) string octet value with different
Character strings. Interpretation of octets is the
responsibility of the application. Therefore, from the BER
string point of view, octets appear to be very similar to
character strings and are compiled in the same way.
</p>
<p>It should be noted that when PER (Packed Encoding Rules) is
used, there is a significant difference in the encoding scheme
between OCTET STRINGS and other strings. The constraints
specified for a type are especially important for PER, where
they affect the encoding.
</p>
<p>Please note that <strong>all</strong> the Character strings are
supported and it is possible to use the following ASN.1 type
definitions:</p>
<div class="example"><pre>
Digs ::= NumericString (SIZE(1..3))
TextFile ::= IA5String (SIZE(0..64000)) </pre></div>
<p>and the following Erlang assignments:</p>
<div class="example"><pre>
DigsVal1 = "456",
DigsVal2 = "123",
TextFileVal1 = "abc...xyz...",
TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] </pre></div>
<p>The Erlang representation for "BMPString" and
"UniversalString" is either a list of ASCII values or a list
of quadruples. The quadruple representation associates to the
Unicode standard representation of characters. The ASCII
characters are all represented by quadruples beginning with
three zeros like {0,0,0,65} for the 'A' character. When
decoding a value for these strings the result is a list of
quadruples, or integers when the value is an ASCII character.
The following example shows how it works:</p>
<p>In a file <span class="code">PrimStrings.asn1</span> the type <span class="code">BMP</span> is defined as
<br>
<span class="code">BMP ::= BMPString</span> then using BER encoding (<span class="code">ber_bin</span>
option)the input/output format will be:</p>
<div class="example"><pre>
1> <span class="bold_code">{ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).</span>
{ok,[30,4,"55-8"]}
2> <span class="bold_code">asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes1)).</span>
{ok,[{0,0,53,53},{0,0,45,56}]}
3> <span class="bold_code">{ok,Bytes2} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,0,65}]).</span>
{ok,[30,4,[53,53,0,65]]}
4> <span class="bold_code">asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes2)).</span>
{ok,[{0,0,53,53},65]}
5> <span class="bold_code">{ok,Bytes3} = asn1rt:encode('PrimStrings','BMP',"BMP string").</span>
{ok,[30,20,[0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103]]}
6> <span class="bold_code">asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes3)).</span>
{ok,"BMP string"} </pre></div>
<p>The UTF8String is represented in Erlang as a list of integers,
where each integer represents the unicode value of one
character. When a value shall be encoded one first has to
transform it to a UTF8 encoded binary, then it can be encoded by
asn1. When decoding the result is a UTF8 encoded binary, which
may be transformed to an integer list. The transformation
functions, <span class="code">utf8_binary_to_list</span> and
<span class="code">utf8_list_to_binary</span>, are in the <span class="code">asn1rt</span> module. In
the example below we assume an asn1 definition <span class="code">UTF ::= UTF8String</span> in a module <span class="code">UTF.asn</span>:</p>
<div class="example"><pre>
1> <span class="bold_code">asn1ct:compile('UTF',[ber_bin]).</span>
Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn"
Compiler Options: [ber_bin]
--{generated,"UTF.asn1db"}--
--{generated,"UTF.erl"}--
ok
2> <span class="bold_code">UTF8Val1 = "hello".</span>
"hello"
3> <span class="bold_code">{ok,UTF8bin1} = asn1rt:utf8_list_to_binary(UTF8Val1).</span>
{ok,<<104,101,108,108,111>>}
4> <span class="bold_code">{ok,B}='UTF':encode('UTF',UTF8bin1).</span>
{ok,[12,
5,
<<104,101,108,108,111>>]}
5> <span class="bold_code">Bin = list_to_binary(B).</span>
<<12,5,104,101,108,108,111>>
6> <span class="bold_code">{ok,UTF8bin1}='UTF':decode('UTF',Bin).</span>
{ok,<<104,101,108,108,111>>}
7> <span class="bold_code">asn1rt:utf8_binary_to_list(UTF8bin1).</span>
{ok,"hello"}
8> <span class="bold_code">UTF8Val2 = [16#00,16#100,16#ffff,16#ffffff].</span>
[0,256,65535,16777215]
9> <span class="bold_code">{ok,UTF8bin2} = asn1rt:utf8_list_to_binary(UTF8Val2).</span>
{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
10> <span class="bold_code">{ok,B2} = 'UTF':encode('UTF',UTF8bin2).</span>
{ok,[12,
11,
<<0,196,128,239,191,191,248,191,191,191,191>>]}
11> <span class="bold_code">Bin2 = list_to_binary(B2).</span>
<<12,11,0,196,128,239,191,191,248,191,191,191,191>>
12> <span class="bold_code">{ok,UTF8bin2} = 'UTF':decode('UTF',Bin2).</span>
{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
13> <span class="bold_code">asn1rt:utf8_binary_to_list(UTF8bin2).</span>
{ok,[0,256,65535,16777215]}
14> </pre></div>
<h4>OBJECT IDENTIFIER</h4>
<a name="OBJECT%20IDENTIFIER"></a>
<p>The OBJECT IDENTIFIER is used whenever a unique identity is required.
An ASN.1 module, a transfer syntax, etc. is identified with an
OBJECT IDENTIFIER. Assume the example below:</p>
<div class="example"><pre>
Oid ::= OBJECT IDENTIFIER
</pre></div>
<p>Therefore, the example below is a valid Erlang instance of the
type 'Oid'.</p>
<div class="example"><pre>
OidVal1 = {1,2,55},
</pre></div>
<p>The OBJECT IDENTIFIER value is simply a tuple with the
consecutive values which must be integers.
</p>
<p>The first value is limited to the values 0, 1 or 2 and the
second value must be in the range 0..39 when the first value
is 0 or 1.
</p>
<p>The OBJECT IDENTIFIER is a very important type and it is
widely used within different standards to uniquely identify
various objects. In [DUBUISSON], there is an
easy-to-understand description of the usage of
OBJECT IDENTIFIER.</p>
<p></p>
<h4>Object Descriptor</h4>
<a name="Object%20Descriptor"></a>
<p>Values of this type can be assigned a value as an ordinary string i.e. <br>
"This is the value of an Object descriptor"</p>
<h4>The TIME Types</h4>
<a name="The%20TIME%20types"></a>
<p>Two different time types are defined within ASN.1, Generalized
Time and UTC (Universal Time Coordinated), both are assigned a
value as an ordinary string within double quotes i.e.
"19820102070533.8".</p>
<p>In case of DER encoding the compiler does not check the validity
of the time values. The DER requirements upon those strings is
regarded as a matter for the application to fulfill.</p>
<h4>SEQUENCE</h4>
<a name="SEQUENCE"></a>
<p>The structured types of ASN.1 are constructed from other types
in a manner similar to the concepts of array and struct in C.
<br>
A SEQUENCE in ASN.1 is
comparable with a struct in C and a record in Erlang.
A SEQUENCE may be defined as:</p>
<div class="example"><pre>
Pdu ::= SEQUENCE {
a INTEGER,
b REAL,
c OBJECT IDENTIFIER,
d NULL } </pre></div>
<p>This is a 4-component structure called 'Pdu'. The major format
for representation of SEQUENCE in Erlang is the record format.
For each SEQUENCE and <span class="code">SET</span> in an ASN.1 module an Erlang
record declaration is generated. For <span class="code">Pdu</span> above, a record
like this is defined:</p>
<div class="example"><pre>
-record('Pdu',{a, b, c, d}). </pre></div>
<p>The record declarations for a module <span class="code">M</span> are placed in a
separate <span class="code">M.hrl</span> file.</p>
<p>Values can be assigned in Erlang as shown below:</p>
<div class="example"><pre>
MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre></div>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>
In very early versions of the asn1 compiler it was also possible to
specify the values of the components in
a SEQUENCE or a SET as a list of tuples <span class="code">{ComponentName,Value}</span>.
This is no longer supported.
</p>
</p></div>
</div>
<p>The decode functions will return a record as result when decoding
a <span class="code">SEQUENCE</span> or a <span class="code">SET</span>.
<a name="DEFAULT"></a>
</p>
<p>A <span class="code">SEQUENCE</span> and a <span class="code">SET</span> may contain a component with a
<span class="code">DEFAULT</span> key word followed by the actual value that is the
default value. In case of BER encoding it is optional to encode the
value if it equals the default value. If the application uses the
atom asn1_DEFAULT as value or if the value is a primitive value
that equals the default value the encoding omits the bytes for
this value, which is more efficient and it results in fever
bytes to send to the receiving application.</p>
<p>For instance, if the following types exists in a file "File.asn":</p>
<div class="example"><pre>
Seq1 ::= SEQUENCE {
a INTEGER DEFAULT 1,
b Seq2 DEFAULT {aa TRUE, bb 15}
}
Seq2 ::= SEQUENCE {
aa BOOLEAN,
bb INTEGER
}
</pre></div>
<p>Some values and the corresponding encoding in an Erlang terminal
is shown below:</p>
<div class="example"><pre>
1> <span class="bold_code">asn1ct:compile('File').</span>
Erlang ASN.1 version "1.3.2" compiling "File.asn1"
Compiler Options: []
--{generated,"File.asn1db"}--
--{generated,"File.hrl"}--
--{generated,"File.erl"}--
ok
2> <span class="bold_code">'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</span>
{ok,["0",[0],[[],[]]]}
3> <span class="bold_code">lists:flatten(["0",[0],[[],[]]]).</span>
[48,0]
4> <span class="bold_code">'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</span>
{ok,["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]}
5> <span class="bold_code">lists:flatten(["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]).</span>
[48,8,161,6,128,1,255,129,1,15]
6> </pre></div>
<p>The result after command line 3, in the example above,shows that the
encoder omits the encoding of default values when they are specific
by asn1_DEFAULT. Line 5 shows that even primitive values that equals
the default value are detected and not encoded. But the constructed
value of component <span class="code">b</span> in <span class="code">Seq1</span> is not recognized as the
default value. Checking of default values in <span class="code">BER</span> is not done
in case of complex values, because it would be to expensive.
<a name="DEFAULT%20DER"></a>
</p>
<p>But, the DER encoding format has stronger requirements regarding
default values both for SET and SEQUENCE. A more elaborate and time
expensive check of default values will take place. The following is
an example with the same types and values as above but with der
encoding format.</p>
<div class="example"><pre>
1> <span class="bold_code">asn1ct:compile('File',[der]).</span>
Erlang ASN.1 version "1.3.2" compiling "File.asn1"
Compiler Options: [der]
--{generated,"File.asn1db"}--
--{generated,"File.hrl"}--
--{generated,"File.erl"}--
ok
2> <span class="bold_code">'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</span>
{ok,["0",[0],[[],[]]]}
3> <span class="bold_code">lists:flatten(["0",[0],[[],[]]]).</span>
[48,0]
4> <span class="bold_code">'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</span>
{ok,["0",[0],[[],[]]]}
5> <span class="bold_code">lists:flatten(["0",[0],[[],[]]]).</span>
[48,0]
6>
</pre></div>
<p>Line 5 shows that even values of constructed types is checked and if
it equals the default value it will not be encoded.</p>
<h4>SET</h4>
<a name="SET"></a>
<p>The SET type is an unusual construct and normally the SEQUENCE
type is more appropriate to use. Set is also inefficient compared with SEQUENCE, as the components can be in any order. Hence, it must be possible
to distinguish every component in 'SET', both when
encoding and decoding a value of a type defined to be a SET.
The tags of all components must be different from each other
in order to be easily recognizable.</p>
<p>A SET may be defined as:</p>
<div class="example"><pre>
Pdu2 ::= SET {
a INTEGER,
b BOOLEAN,
c ENUMERATED {on(0),off(1)} } </pre></div>
<p>A SET is represented as an Erlang record.
For each SEQUENCE and <span class="code">SET</span> in
an ASN.1 module an Erlang record declaration is generated. For
<span class="code">Pdu2</span> above a record is defined like this:</p>
<div class="example"><pre>
-record('Pdu2',{a, b, c}). </pre></div>
<p>The record declarations for a module <span class="code">M</span> are placed in a
separate <span class="code">M.hrl</span> file.</p>
<p>Values can be assigned in Erlang as demonstrated below:</p>
<div class="example"><pre>
V = #'Pdu2'{a=44,b=false,c=off}. </pre></div>
<p>The decode functions will return a record as result when decoding
a SET.
</p>
<p>The difference between SET and SEQUENCE is that the order of
the components (in the BER encoded format) is undefined for SET
and defined as the lexical order from the ASN.1 definition for
SEQUENCE. The ASN.1 compiler for Erlang will always encode a
SET in the lexical order. The decode routines can handle SET
components encoded in any order but will always return the
result as a record. Since all components of the SET must be
distinguishable both in the encoding phase as well as the
decoding phase the following type is not allowed in a module
with EXPLICIT or IMPLICIT as tag-default :</p>
<p></p>
<div class="example"><pre>
Bad ::= SET {i INTEGER,
j INTEGER } </pre></div>
<p>The ASN.1 to Erlang compiler rejects the above type. We
shall not explain the concept of tag further here, we refer to
[X.680].
</p>
<p>Encoding of a SET with components with DEFAULT values behaves
similar as a SEQUENCE, <span class="bold_code"><a href="#DEFAULT">see above</a></span>. The DER encoding format restrictions on DEFAULT
values is the same for SET as for SEQUENCE, and is supported by
the compiler, <span class="bold_code"><a href="#DEFAULT%20DER">see above</a></span>.</p>
<p>Moreover, in DER the elements of a SET will be sorted. If a
component is an un-tagged choice the sorting have to take place
in run-time. This fact emphasizes the following recommendation
if DER encoding format is used.</p>
<p>The concept of SET is an unusual
construct and one cannot think of one single application
where the set type is essential. (Imagine if someone
"invented'' the shuffled array in 'C') People tend to think
that 'SET' sounds nicer and more mathematical than 'SEQUENCE'
and hence use it when 'SEQUENCE' would have been more
appropriate. It is also most inefficient, since every correct
implementation of SET must always be prepared to accept the
components in any order. So, if possible use SEQUENCE instead
of SET.</p>
<h4>Notes about Extend-ability for SEQUENCE and SET</h4>
<p>When a SEQUENCE or SET contains an extension marker and
extension components like this:</p>
<div class="example"><pre>
SExt ::= SEQUENCE {
a INTEGER,
...,
b BOOLEAN }
</pre></div>
<p>It means that the type may get more components in newer
versions of the ASN.1 spec. In this case it has got a new
component <span class="code">b</span>. Thus, incoming messages that will be decoded
may have more or fever components than this one.
</p>
<p>The component <span class="code">b</span> will be treated as
an original component when encoding a message. In this case, as
it is not an optional element, it must be encoded.
</p>
<p>During decoding the <span class="code">b</span> field of the record will get the decoded
value of the <span class="code">b</span>
component if present and otherwise the value <span class="code">asn1_NOVALUE</span>.</p>
<h4>CHOICE</h4>
<a name="CHOICE"></a>
<p>The CHOICE type is a space saver and is similar to the concept of a
'union' in the C-language. As with the previous SET-type, the
tags of all components of a CHOICE need to be distinct. If
AUTOMATIC TAGS are defined for the module (which is
preferable) the tags can be omitted completely in the ASN.1
specification of a CHOICE.
</p>
<p>Assume:</p>
<div class="example"><pre>
T ::= CHOICE {
x [0] REAL,
y [1] INTEGER,
z [2] OBJECT IDENTIFIER }
</pre></div>
<p>It is then possible to assign values:</p>
<div class="example"><pre>
TVal1 = {y,17},
TVal2 = {z,{0,1,2}},
</pre></div>
<p>A CHOICE value is always represented as the tuple
<span class="code">{ChoiceAlternative, Val}</span> where <span class="code">ChoiceAlternative</span>
is an atom denoting the selected choice
alternative.
</p>
<p>It is also allowed to have a CHOICE type tagged as follow:</p>
<p></p>
<div class="example"><pre>
C ::= [PRIVATE 111] CHOICE {
C1,
C2 }
C1 ::= CHOICE {
a [0] INTEGER,
b [1] BOOLEAN }
C2 ::= CHOICE {
c [2] INTEGER,
d [3] OCTET STRING } </pre></div>
<p>In this case, the top type C appears to have no tags at all in
its components, however, both C1 and C2 are also defined as
CHOICE types and they have distinct tags among themselves.
Hence, the above type C is both legal and allowed.
</p>
<h4>Extendable CHOICE</h4>
<p>When a CHOICE contains an extension marker and the decoder detects
an unknown alternative of the CHOICE the value is represented as:</p>
<div class="example"><pre>
{asn1_ExtAlt, BytesForOpenType}
</pre></div>
<p>Where <span class="code">BytesForOpenType</span> is a list of bytes constituting the
encoding of the "unknown" CHOICE alternative. </p>
<h4>SET OF and SEQUENCE OF</h4>
<a name="SOF"></a>
<p>The SET OF and SEQUENCE OF types correspond to the concept of an array
found in several programming languages. The Erlang syntax for
both of these types is straight forward. For example:</p>
<div class="example"><pre>
Arr1 ::= SET SIZE (5) OF INTEGER (4..9)
Arr2 ::= SEQUENCE OF OCTET STRING </pre></div>
<p>We may have the following in Erlang:</p>
<div class="example"><pre>
Arr1Val = [4,5,6,7,8],
Arr2Val = ["abc",[14,34,54],"Octets"], </pre></div>
<p>Please note that the definition of the SET OF type implies that
the order of the components is undefined, but in practice there is
no difference between SET OF and SEQUENCE OF. The ASN.1 compiler
for Erlang does not randomize the order of the SET OF components
before encoding.</p>
<p>However, in case of a value of the type <span class="code">SET OF</span>, the DER
encoding format requires the elements to be sent in ascending
order of their encoding, which implies an expensive sorting
procedure in run-time. Therefore it is strongly recommended to
use <span class="code">SEQUENCE OF</span> instead of <span class="code">SET OF</span> if it is possible.</p>
<h4>ANY and ANY DEFINED BY</h4>
<a name="ANY"></a>
<p>The types <span class="code">ANY</span> and <span class="code">ANY DEFINED BY</span> have been removed
from the standard since 1994. It is recommended not to use
these types any more. They may, however, exist in some old ASN.1
modules.
The idea with this type was to leave a "hole" in a definition where
one could put unspecified data of any kind, even non ASN.1 data.</p>
<p>A value of this type is encoded as an <span class="code">open type</span>.</p>
<p>Instead of <span class="code">ANY</span>/<span class="code">ANY DEFINED BY</span> one should use
<span class="code">information object class</span>, <span class="code">table constraints</span> and
<span class="code">parameterization</span>. In particular the construct
<span class="code">TYPE-IDENTIFIER.@Type</span> accomplish the same as the
deprecated <span class="code">ANY</span>.</p>
<p>See also <span class="bold_code"><a href="#Information%20Object">Information object</a></span></p>
<h4>EXTERNAL, EMBEDDED PDV and CHARACTER STRING</h4>
<a name="NegotiationTypes"></a>
<p>These types are used in presentation layer negotiation. They are
encoded according to their associated type, see [X.680].</p>
<p>The <span class="code">EXTERNAL</span> type had a slightly different associated type
before 1994. [X.691] states that encoding shall follow
the older associate type. Therefore does generated encode/decode
functions convert values of the newer format to the older format
before encoding. This implies that it is allowed to use
<span class="code">EXTERNAL</span> type values of either format for encoding. Decoded
values are always returned on the newer format.</p>
<h4>Embedded Named Types</h4>
<p>The structured types previously described may very well have other named types
as their components. The general syntax to assign a value to the component C
of a named ASN.1 type T in Erlang is the record syntax
<span class="code">#'T'{'C'=Value}</span>.
Where <span class="code">Value</span> may be a value of yet another type T2.</p>
<p>For example:</p>
<div class="example"><pre>
B ::= SEQUENCE {
a Arr1,
b [0] T }
Arr1 ::= SET SIZE (5) OF INTEGER (4..9)
T ::= CHOICE {
x [0] REAL,
y [1] INTEGER,
z [2] OBJECT IDENTIFIER } </pre></div>
<p>The above example can be assigned like this in Erlang:</p>
<div class="example"><pre>
V2 = #'B'{a=[4,5,6,7,8], b={x,7.77}}.
</pre></div>
<h3><a name="id70609">1.6
Naming of Records in .hrl Files</a></h3>
<p>When an asn1 specification is compiled all defined types of
type SET or SEQUENCE will result in a corresponding record in the
generated hrl file. This is because the values for SET/SEQUENCE
as mentioned in sections above are represented as records.</p>
<p>Though there are some special cases of this functionality that
are presented below.</p>
<h4>Embedded Structured Types</h4>
<p>It is also possible in ASN.1 to have components that are themselves
structured types.
For example, it is possible to have:</p>
<div class="example"><pre>
Emb ::= SEQUENCE {
a SEQUENCE OF OCTET STRING,
b SET {
a [0] INTEGER,
b [1] INTEGER DEFAULT 66},
c CHOICE {
a INTEGER,
b FooType } }
FooType ::= [3] VisibleString </pre></div>
<p>The following records are generated because of the type <span class="code">Emb</span>:</p>
<div class="example"><pre>
-record('Emb,{a, b, c}).
-record('Emb_b',{a, b = asn1_DEFAULT}). % the embedded SET type
</pre></div>
<p>Values of the <span class="code">Emb</span> type can be assigned like this:</p>
<div class="example"><pre>
V = #'Emb'{a=["qqqq",[1,2,255]],
b = #'Emb_b'{a=99},
c ={b,"Can you see this"}}.
</pre></div>
<p>For an embedded type of type SEQUENCE/SET in a SEQUENCE/SET
the record name is extended with an underscore and the component
name. If the embedded structure is deeper with SEQUENCE, SET or
CHOICE types in the line, each component-/alternative-name will
be added to the record-name.</p>
<p>For example:</p>
<div class="example"><pre>
Seq ::= SEQUENCE{
a CHOICE{
b SEQUENCE {
c INTEGER
}
}
} </pre></div>
<p>will result in the following record:</p>
<div class="example"><pre>
-record('Seq_a_b',{c}). </pre></div>
<p>If the structured type has a component with an embedded
SEQUENCE OF/SET OF which embedded type in turn is a
SEQUENCE/SET it will give a record with the SEQOF/SETOF
addition as in the following example:</p>
<div class="example"><pre>
Seq ::= SEQUENCE {
a SEQUENCE OF SEQUENCE {
b
}
c SET OF SEQUENCE {
d
}
} </pre></div>
<p>This results in the records:</p>
<div class="example"><pre>
-record('Seq_a_SEQOF'{b}).
-record('Seq_c_SETOF'{d}). </pre></div>
<p>A parameterized type should be considered as an embedded
type. Each time a such type is referenced an instance of it is
defined. Thus in the following example a record with name
<span class="code">'Seq_b'</span> is generated in the .hrl file and used to hold
values.</p>
<div class="example"><pre>
Seq ::= SEQUENCE {
b PType{INTEGER}
}
PType{T} ::= SEQUENCE{
id T
} </pre></div>
<h4>Recursive Types</h4>
<p>Types may refer to themselves. Suppose:</p>
<div class="example"><pre>
Rec ::= CHOICE {
nothing [0] NULL,
something SEQUENCE {
a INTEGER,
b OCTET STRING,
c Rec }} </pre></div>
<p>This type is recursive; that is, it refers to itself. This is allowed
in ASN.1 and the ASN.1-to-Erlang compiler supports this recursive
type. A value for this type is assigned in Erlang as shown below:</p>
<div class="example"><pre>
V = {something,#'Rec_something'{a = 77,
b = "some octets here",
c = {nothing,'NULL'}}}. </pre></div>
<h3><a name="id70752">1.7
ASN.1 Values</a></h3>
<p>Values can be assigned to ASN.1 type within the ASN.1 code
itself, as opposed to the actions taken in the previous chapter where
a value was assigned to an ASN.1 type in Erlang. The full value
syntax of ASN.1 is supported and [X.680] describes in detail how
to assign values in ASN.1. Below is a short example:</p>
<div class="example"><pre>
TT ::= SEQUENCE {
a INTEGER,
b SET OF OCTET STRING }
tt TT ::= {a 77,b {"kalle","kula"}} </pre></div>
<p>The value defined here could be used in several ways.
Firstly, it could be used as the value in some DEFAULT component:</p>
<div class="example"><pre>
SS ::= SET {
s [0] OBJECT IDENTIFIER,
val TT DEFAULT tt } </pre></div>
<p>It could also be used from inside an Erlang program. If the above ASN.1
code was defined in ASN.1 module <span class="code">Values</span>, then the ASN.1 value
<span class="code">tt</span> can be reached from Erlang as
a function call to <span class="code">'Values':tt()</span> as in the example below.</p>
<div class="example"><pre>
1> <span class="bold_code">Val = 'Values':tt().</span>
{'TT',77,["kalle","kula"]}
2> <span class="bold_code">{ok,Bytes} = 'Values':encode('TT',Val).</span>
{ok,["0",
[18],
[[[128],[1],"M"],["\\241","\\r",[[[4],[5],"kalle"],[[4],[4],"kula"]]]]]}
3> <span class="bold_code">FlatBytes = lists:flatten(Bytes).</span>
[48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,107,117,108,97]
4> <span class="bold_code">'Values':decode('TT',FlatBytes).</span>
{ok,{'TT',77,["kalle","kula"]}}
5>
</pre></div>
<p>The above example shows that a function is generated by the compiler
that returns a valid Erlang representation of the value, even though
the value is of a complex type.</p>
<p>Furthermore, there is a macro generated for each value in the .hrl
file. So, the defined value <span class="code">tt</span> can also be extracted by
<span class="code">?tt</span> in application code.</p>
<h3><a name="id70833">1.8
Macros</a></h3>
<p>MACRO is not supported as the the type is no longer part of the
ASN.1 standard.</p>
<h3><a name="id70849">1.9
ASN.1 Information Objects (X.681)</a></h3>
<a name="Information%20Object"></a>
<p>Information Object Classes, Information Objects and Information
Object Sets, (in the following called classes, objects and
object sets respectively), are defined in the standard
definition [X.681]. In the following only a brief
explanation is given. </p>
<p>These constructs makes it possible to define open types,
i.e. values of that type can be of any ASN.1 type. It is also
possible to define relationships between different types and
values, since classes can hold types, values, objects, object
sets and other classes in its fields.
An Information Object Class may be defined in ASN.1 as:</p>
<div class="example"><pre>
GENERAL-PROCEDURE ::= CLASS {
&Message,
&Reply OPTIONAL,
&Error OPTIONAL,
&id PrintableString UNIQUE
}
WITH SYNTAX {
NEW MESSAGE &Message
[REPLY &Reply]
[ERROR &Error]
ADDRESS &id
} </pre></div>
<p>An object is an instance of a class and an object set is a set
containing objects of one specified class. A definition may look like
below.</p>
<p>The object <span class="code">object1</span> is an instance of the CLASS
GENERAL-PROCEDURE and has one type field and one fixed type value
field. The object <span class="code">object2</span> also has an OPTIONAL field ERROR,
which is a type field.</p>
<div class="example"><pre>
object1 GENERAL-PROCEDURE ::= {
NEW MESSAGE PrintableString
ADDRESS "home"
}
object2 GENERAL-PROCEDURE ::= {
NEW MESSAGE INTEGER
ERROR INTEGER
ADDRESS "remote"
} </pre></div>
<p>The field ADDRESS is a UNIQUE field. Objects in an object set must
have unique values in their UNIQUE field, as in GENERAL-PROCEDURES: </p>
<div class="example"><pre>
GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
object1 | object2} </pre></div>
<p>One can not encode a class, object or object set, only referring to
it when defining other ASN.1 entities. Typically one refers to a
class and to object sets by table constraints and component
relation constraints [X.682] in ASN.1 types, as in: </p>
<div class="example"><pre>
StartMessage ::= SEQUENCE {
msgId GENERAL-PROCEDURE.&id ({GENERAL-PROCEDURES}),
content GENERAL-PROCEDURE.&Message ({GENERAL-PROCEDURES}{@msgId}),
} </pre></div>
<p>In the type <span class="code">StartMessage</span> the constraint following the
<span class="code">content</span> field tells that in a value of type
<span class="code">StartMessage</span> the value in the <span class="code">content</span> field must
come from the same object that is chosen by the <span class="code">msgId</span>
field.</p>
<p>So, the value <span class="code">#'StartMessage'{msgId="home",content="Any Printable String"}</span> is legal to encode as a StartMessage
value, while the value <span class="code">#'StartMessage'{msgId="remote", content="Some String"}</span> is illegal since the constraint
in StartMessage tells that when you have chosen a value from a
specific object in the object set GENERAL-PROCEDURES in the
msgId field you have to choose a value from that same object in
the content field too. In this second case it should have been
any INTEGER value.</p>
<p><span class="code">StartMessage</span> can in the <span class="code">content</span> field be
encoded with a value of any type that an object in the
<span class="code">GENERAL-PROCEDURES</span> object set has in its <span class="code">NEW MESSAGE</span> field. This field refers to a type field
<span class="code">&amp;Message</span> in the class. The <span class="code">msgId</span> field is always
encoded as a PrintableString, since the field refers to a fixed type
in the class.</p>
<h3><a name="id70992">1.10
Parameterization (X.683)</a></h3>
<p>Parameterization, which is defined in the standard [X.683], can be used when defining types, values, value
sets, information object classes, information objects or
information object sets.
A part of a definition can be supplied as a parameter. For
instance, if a Type is used in a definition with certain
purpose, one want the type-name to express the intention. This
can be done with parameterization.</p>
<p>When many types (or an other ASN.1 entity) only differs in some
minor cases, but the structure of the types are similar, only
one general type can be defined and the differences may be supplied
through parameters. </p>
<p>One example of use of parameterization is:</p>
<div class="example"><pre>
General{Type} ::= SEQUENCE
{
number INTEGER,
string Type
}
T1 ::= General{PrintableString}
T2 ::= General{BIT STRING}
</pre></div>
<p>An example of a value that can be encoded as type T1 is {12,"hello"}.</p>
<p>Observe that the compiler not generates encode/decode functions for
parameterized types, only for the instances of the parameterized
types. So, if a file contains the types General{}, T1 and T2 above,
encode/decode functions will only be generated for T1 and T2.
</p>
<h3><a name="id71035">1.11
Tags</a></h3>
<p>Every built-in ASN.1 type, except CHOICE and ANY have a universal tag.
This is a unique number that clearly identifies the type. <br>
It is essential for all users of ASN.1 to
understand all the details about tags.</p>
<p>Tags are implicitly encoded in the BER encoding as shown below, but
are hardly not accounted for in the PER encoding. In PER tags are
used for instance to sort the components of a SET.</p>
<p>There are four different types of tags.</p>
<dl>
<dt><strong><strong>universal</strong></strong></dt>
<dd>
<p>For types whose meaning is the same in all
applications. Such as integers, sequences and so on; that is, all the built in
types.</p>
</dd>
<dt><strong><strong>application</strong></strong></dt>
<dd>
<p>For application specific types for example, the types in
X.400 Message handling service have this sort of tag.</p>
</dd>
<dt><strong><strong>private</strong></strong></dt>
<dd>
<p>For your own private types.</p>
</dd>
<dt><strong><strong>context</strong></strong></dt>
<dd>
<p>This is used to distinguish otherwise indistinguishable
types in a specific context. For example, if we have two
components of a
CHOICE type that are both <span class="code">INTEGER</span> values, there is no
way for the decoder to
decipher which component was actually chosen, since both
components will be
tagged as <span class="code">INTEGER</span>. When this or similar situations occur,
one or both of the components should be given a context specific
to resolve the ambiguity.</p>
</dd>
</dl>
<p>The tag in the case of the 'Apdu' type [PRIVATE 1] is encoded to a
sequence of bytes making it possible for a
decoder to look at the (initial) bytes that arrive and determine
whether the rest of the bytes must be of the type associated
with that particular sequence of bytes. This means that each
tag must be uniquely associated with <strong>only</strong> one ASN.1
type.
</p>
<p>Immediately following the tag is a sequence of bytes
informing the decoder of the length of the instance. This is
sometimes referred to as TLV (Tag length value) encoding.
Hence, the structure of a BER encoded series of bytes is as shown in the table below.</p>
<p></p>
<table border="1" cellpadding="2" cellspacing="0"><tr>
<td align="left" valign="middle">Tag</td>
<td align="left" valign="middle">Len</td>
<td align="left" valign="middle">Value</td>
</tr></table>
<em>Table
1.5:
Structure of a BER encoded series of bytes</em>
<h3><a name="id71184">1.12
Encoding Rules</a></h3>
<p>When the first recommendation on ASN.1 was released 1988 it was
accompanied with the Basic Encoding Rules, BER, as the only
alternative for encoding.
BER is a somewhat verbose protocol. It adopts a so-called TLV (type,
length, value) approach to encoding in which every element of the
encoding carries some type information, some length information and
then the value of that element. Where the element is itself
structured, then the Value part of the element is itself a series of
embedded TLV components, to whatever depth is necessary. In summary,
BER is not a compact encoding but is relatively fast and easy to
produce.</p>
<p>The DER (Distinguished Encoding Rule) encoding format was included in
the standard in 1994. It is a specialized form of BER, which gives
the encoder the option to encode some entities differently. For
instance, is the value for TRUE any octet with any bit set to one. But,
DER does not leave any such choices. The value for TRUE in the DER
case is encoded as the octet <span class="code">11111111</span>. So, the same value
encoded by two different DER encoders must result in the same bit
stream.</p>
<p>A more compact encoding is achieved with the Packed Encoding
Rules PER which was introduced together with the revised
recommendation in 1994. PER takes a rather different approach from
that taken by BER. The first difference is that the tag part in
the TLV is omitted from the encodings, and any tags in the
notation are not encoded. The potential ambiguities are resolved
as follows:</p>
<ul>
<li>
<p>A CHOICE is encoded by first encoding a choice index which
identifies the chosen
alternative by its position in the notation.</p>
</li>
<li>
<p>The elements of a SEQUENCE are transmitted in textual
order. OPTIONAL or DEFAULT elements are preceded by a bit map
to identify which elements are present. After sorting the
elements of a SET in the "canonical tag order" as defined in
X.680 8.6 they are treated as a SEQUENCE regarding OPTIONAL
and DEFAULT elements. A SET is transferred in the sorted
order.</p>
</li>
</ul>
<p>A second difference is that PER takes full account of the sub-typing
information in that the encoded bytes are affected by the constraints.
The BER encoded bytes are unaffected by the constraints.
PER uses the sub-typing information to for example omit length fields
whenever possible. </p>
<p>The run-time functions, sometimes take the constraints into account
both for BER and PER. For instance are SIZE constrained strings checked.</p>
<p>There are two variants of PER, <strong>aligned</strong> and <strong>unaligned</strong>.
In summary, PER results in compact encodings which require much more
computation to produce than BER.
</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
