From e95095457c4d83c02850b811fb28711c0b3d1c23 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update asn1 documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson. --- lib/asn1/doc/src/Makefile | 4 +- lib/asn1/doc/src/asn1_getting_started.xml | 1290 ++++++++++++++++++++++++++ lib/asn1/doc/src/asn1_introduction.xml | 99 ++ lib/asn1/doc/src/asn1_overview.xml | 49 + lib/asn1/doc/src/asn1_spec.xmlsrc | 521 ++++++----- lib/asn1/doc/src/asn1_ug.xml | 1417 ----------------------------- lib/asn1/doc/src/asn1ct.xml | 316 +++---- lib/asn1/doc/src/asn1rt.xml | 26 +- lib/asn1/doc/src/part.xml | 9 +- lib/asn1/doc/src/ref_man.xml | 6 +- 10 files changed, 1898 insertions(+), 1839 deletions(-) create mode 100644 lib/asn1/doc/src/asn1_getting_started.xml create mode 100644 lib/asn1/doc/src/asn1_introduction.xml create mode 100644 lib/asn1/doc/src/asn1_overview.xml delete mode 100644 lib/asn1/doc/src/asn1_ug.xml (limited to 'lib/asn1/doc/src') diff --git a/lib/asn1/doc/src/Makefile b/lib/asn1/doc/src/Makefile index 3b3e1bd8f9..f26508295c 100644 --- a/lib/asn1/doc/src/Makefile +++ b/lib/asn1/doc/src/Makefile @@ -48,7 +48,9 @@ XML_HTML_FILE = \ notes_history.xml XML_CHAPTER_FILES = \ - asn1_ug.xml \ + asn1_introduction.xml \ + asn1_getting_started.xml \ + asn1_overview.xml \ asn1_spec.xml \ notes.xml diff --git a/lib/asn1/doc/src/asn1_getting_started.xml b/lib/asn1/doc/src/asn1_getting_started.xml new file mode 100644 index 0000000000..1a9c279191 --- /dev/null +++ b/lib/asn1/doc/src/asn1_getting_started.xml @@ -0,0 +1,1290 @@ + + + + +
+ + 19972013 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Getting Started + Kenneth Lundin + + 1999-03-25 + D + asn1_getting_started.xml +
+ +
+ Example +

The following example demonstrates the basic functionality used to + run the Erlang ASN.1 compiler.

+

Create a file named People.asn containing the following:

+ 
+People DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+  Person ::= SEQUENCE {
+    name PrintableString,
+    location INTEGER {home(0),field(1),roving(2)},
+    age INTEGER OPTIONAL
+  }
+END
+

This file 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 to generate code.

+

The generated Erlang files are placed in the current directory or + in the directory specified with option {outdir,Dir}.

+

The following shows how the compiler + can be called from the Erlang shell:

+ + 
+1> asn1ct:compile("People", [ber]).
+ok
+2>
+ +

Option verbose can be added to get information + about the generated files:

+ 
+2> asn1ct:compile("People", [ber,verbose]).
+Erlang ASN.1 compiling "People.asn" 
+--{generated,"People.asn1db"}--
+--{generated,"People.hrl"}--
+--{generated,"People.erl"}--
+ok
+3>
+ +

ASN.1 module People is now accepted and the + abstract syntax tree is saved in file People.asn1db. + The generated Erlang code is compiled using the Erlang compiler + and loaded into the Erlang runtime system. There is now an API + for encode/2 and decode/2 in module + People, which is called like:

+ , )]]> +

+ or

+, )]]>

+ +

Assume that there is a network + application that receives instances of the ASN.1 defined + type Person, modifies, and sends them back again:

+ + +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, +

In this example, 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 + 'People':decode('Person',Bytes), which returned + an Erlang value of the ASN.1 type Person. Then an answer was + constructed and encoded using + 'People':encode('Person',Answer), which takes an + instance of a defined ASN.1 type and transforms it to a + binary according to the BER or PER encoding rules.

+

The encoder and decoder can also be run from the shell:

+ 
+2> Rockstar = {'Person',"Some Name",roving,50}.
+{'Person',"Some Name",roving,50}
+3> {ok,Bin} = 'People':encode('Person',Rockstar).
+{ok,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
+      2,1,50>>}
+4> {ok,Person} = 'People':decode('Person',Bin).
+{ok,{'Person',"Some Name",roving,50}}
+5>
+ +
+ Module Dependencies +

It is common that ASN.1 modules import defined types, values, and + other entities from another ASN.1 module.

+

Earlier versions of the ASN.1 compiler required that modules + that were imported from had to be compiled before the module + that imported. This caused problems when ASN.1 modules had circular + dependencies.

+

Referenced modules are now parsed when the compiler finds an + entity that is imported. No code is generated for + the referenced module. However, the compiled modules rely on + that the referenced modules are also compiled.

+
+
+ +
+ ASN.1 Application User Interface +

The ASN.1 application provides the following two + separate user interfaces:

+ + +

The module asn1ct, which provides the compile-time functions + (including the compiler)

+ + +

The module asn1rt_nif, which provides the runtime functions + for the ASN.1 decoder for the BER back end

+ + +

The reason for this division of the interfaces into compile-time + and runtime + is that only runtime modules (asn1rt*) need to be loaded in + an embedded system. +

+ +
+ Compile-Time Functions +

The ASN.1 compiler can be started directly from the command line + by the erlc program. This is convenient when compiling + many ASN.1 files from the command line or when using Makefiles. + Some examples of how the erlc command can be used to start + the ASN.1 compiler:

+ 
+erlc Person.asn
+erlc -bper Person.asn
+erlc -bber ../Example.asn
+erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
+

Useful options for the ASN.1 compiler:

+ + -b[ber | per | uper] + +

Choice of encoding rules. If omitted, ber is the + default.

+ + -o OutDirectory + +

Where to put the generated files. Default is the current + directory.

+ + -I IncludeDir + +

Where to search for .asn1db files and ASN.1 + source specs to resolve references to other + modules. This option can be repeated many times if there + are several places to search in. The compiler + searches the current directory first.

+ + +der + +

DER encoding rule. Only when using option -ber.

+ + +asn1config + +

This functionality works together with option + ber. It enables the specialized decodes, see Section + Specialized Decode.

+ + +undec_rest + +

A buffer that holds a message being decoded can also have + trailing bytes. If those trailing bytes are important, they + can be returned along with the decoded value by compiling + the ASN.1 specification with option +undec_rest. + The return value from the decoder is + {ok,Value,Rest} where Rest is a binary + containing the trailing bytes.

+ + +'Any Erlc Option' + +

Any option can be added to the Erlang compiler when + compiling the generated Erlang files. Any option + unrecognized by the ASN.1 compiler is passed to the + Erlang compiler.

+ + +

For a complete description of erlc, see + ERTS Reference Manual.

+

The compiler and other compile-time functions can also be started + from the Erlang shell. Here follows a brief + description of the primary functions. For a + complete description of each function, see module asn1ct in + the ASN.1 Reference Manual.

+

The compiler is started by asn1ct:compile/1 with + default options, or asn1ct:compile/2 if explicit options + are given.

+

Example:

+ 
+asn1ct:compile("H323-MESSAGES.asn1").
+

This equals:

+ 
+asn1ct:compile("H323-MESSAGES.asn1",[ber]).
+

If PER encoding is wanted:

+ 
+asn1ct:compile("H323-MESSAGES.asn1",[per]).
+

The generic encode and decode functions can be called + as follows:

+ 
+'H323-MESSAGES':encode('SomeChoiceType',{call,<<"octetstring">>}).
+'H323-MESSAGES':decode('SomeChoiceType',Bytes).
+
+ +
+ Runtime Functions +

When an ASN.1 specification is compiled with option ber, + the asn1rt_nif module and the NIF library in + asn1/priv_dir are needed at runtime.

+

By calling function info/0 in a generated module, you + get information about which compiler options were used.

+
+ +
+ Errors +

Errors detected at + compile-time are displayed on the screen together with line + numbers indicating where in the source file the respective error + was detected. If no errors are found, an Erlang ASN.1 module is + created.

+

The runtime encoders and decoders execute within a catch and + return {ok, Data} or + {error, {asn1, Description}} where + Description is + an Erlang term describing the error.

+
+
+ +
+ + Multi-File Compilation +

There are various reasons for using multi-file compilation:

+ + To choose the name for the generated module, for + example, because you need to compile the same specs for + different encoding rules. + You want only one resulting module. + +

Specify which ASN.1 specs to compile in a module with extension + .set.asn. Choose a module name and provide the + names of the ASN.1 specs. For example, if you have the specs + File1.asn, File2.asn, and File3.asn, your + module MyModule.set.asn looks as follows:

+ 
+File1.asn
+File2.asn
+File3.asn
+

If you compile with the following, the result is one merged + module MyModule.erl with the generated code from the three + ASN.1 specs:

+ +~> erlc MyModule.set.asn +
+ +
+ Remark about Tags + +

Tags used to be important for all users of ASN.1, because it + was necessary to add tags manually to certain constructs in order + for the ASN.1 specification to be valid. Example of + an old-style specification:

+ + 
+Tags DEFINITIONS ::=
+BEGIN
+  Afters ::= CHOICE { cheese [0] IA5String,
+                      dessert [1] IA5String }
+END
+ +

Without the tags (the numbers in square brackets) the ASN.1 + compiler refused to compile the file.

+ +

In 1994 the global tagging mode AUTOMATIC TAGS was introduced. + By putting AUTOMATIC TAGS in the module header, the ASN.1 + compiler automatically adds tags when needed. The following is the + same specification in AUTOMATIC TAGS mode:

+ + 
+Tags DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+  Afters ::= CHOICE { cheese IA5String,
+                      dessert IA5String }
+END
+ +

Tags are not mentioned any more in this User's Guide.

+
+ +
+ + ASN.1 Types +

This section describes the ASN.1 types including their + functionality, purpose, and how values are assigned in Erlang. +

+

ASN.1 has both primitive and constructed types:

+

+ + + Primitive Types + Constructed Types + + + BOOLEAN + SEQUENCE + + + INTEGER + SET + + + REAL + CHOICE + + + NULL + SET OF and SEQUENCE OF + + + ENUMERATED + ANY + + + BIT STRING + ANY DEFINED BY + + + OCTET STRING + EXTERNAL + + + Character Strings + EMBEDDED PDV + + + OBJECT IDENTIFIER + CHARACTER STRING + + + Object Descriptor + + + + TIME Types + + + Supported ASN.1 Types +
+ + +

The values of each ASN.1 type have their own representation in Erlang, as + described in the following sections. Users must provide + these values for encoding according to the representation, as shown in the + following example:

+ + 
+Operational ::= BOOLEAN --ASN.1 definition
+

In Erlang code it can look as follows:

+ 
+Val = true,
+{ok,Bytes} = MyModule:encode('Operational', Val),
+ +
+ + BOOLEAN +

Booleans in ASN.1 express values that can be either + TRUE or FALSE. + The meanings assigned to TRUE and FALSE are outside the scope + of this text.

+

In ASN.1 it is possible to have:

+ 
+Operational ::= BOOLEAN
+

Assigning a value to type Operational in Erlang is possible by + using the following Erlang code:

+ +Myvar1 = true, +

Thus, in Erlang the atoms true and false are used + to encode a boolean value.

+
+ +
+ + INTEGER +

ASN.1 itself specifies indefinitely large integers. Erlang + systems with version 4.3 and higher support very large + integers, in practice indefinitely large integers.

+

The concept of subtyping can be applied to integers and + to other ASN.1 types. The details of subtyping are not + explained here; for more information, see X.680. Various + syntaxes are allowed when defining a type as an integer:

+ 
+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)}
+

The Erlang representation of an ASN.1 INTEGER is an integer or + an atom if a Named Number List (see T6 in the previous + list) is specified.

+

The following is an example of Erlang code that assigns values for the + types in the previous list:

+ 
+T1value = 0,
+T2value = 6,
+T6value1 = blue,
+T6value2 = 0,
+T6value3 = white
+

These Erlang variables 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.

+

The decoder returns an atom if the value corresponds to a + symbol in the Named Number List.

+
+ +
+ + REAL +

The following ASN.1 type is used for real numbers:

+ 
+R1 ::= REAL
+

It is assigned a value in Erlang as follows:

+ 
+R1value1 = "2.14",
+R1value2 = {256,10,-2},
+

In the last line, notice that the tuple {256,10,-2} is the real number + 2.56 in a special notation, which encodes faster than simply + stating the number as "2.56". The arity three tuple is + {Mantissa,Base,Exponent}, that is, Mantissa * Base^Exponent.

+
+ +
+ + NULL +

The type NULL is suitable where supply and recognition of a value + is important but the actual value is not.

+ 
+Notype ::= NULL
+

This type is assigned in Erlang as follows:

+ 
+N1 = 'NULL',
+

The actual value is the quoted atom 'NULL'.

+
+ +
+ + ENUMERATED +

The type ENUMERATED can be used when the value you want to + describe can only take one of a set of predefined values. Example:

+ 
+DaysOfTheWeek ::= ENUMERATED { 
+    sunday(1),monday(2),tuesday(3),
+    wednesday(4),thursday(5),friday(6),saturday(7) }
+

For example, to assign a weekday value in Erlang, use the same atom + as in the Enumerations of the type definition:

+ 
+Day1 = saturday,
+

The enumerated type is similar to an integer type, when + defined with a set of predefined values. The difference is that + an enumerated type can only have specified + values, whereas an integer can have any value.

+
+ +
+ + BIT STRING +

The type BIT STRING can be used to model information that + is made up of arbitrary length series of bits. It is intended + to be used for selection of flags, not for binary files.

+

In ASN.1, BIT STRING definitions can look as follows:

+ 
+Bits1 ::= BIT STRING
+Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
+

The following two notations are available for representation of BIT + STRING values in Erlang and as input to the encode functions:

+ + A bitstring. By default, a BIT STRING with no + symbolic names is decoded to an Erlang bitstring. + A list of atoms corresponding to atoms in the NamedBitList + in the BIT STRING definition. A BIT STRING with symbolic + names is always decoded to the format shown in the following + example: + + 
+Bits1Val1 = <<0:1,1:1,0:1,1:1,1:1>>,
+Bits2Val1 = [gnu,punk],
+Bits2Val2 = <<2#1110:4>>,
+Bits2Val3 = [bar,gnu,gnome],
+

Bits2Val2 and Bits2Val3 denote the same value.

+

Bits2Val1 is assigned symbolic values. The assignment means + that the bits corresponding to gnu and punk, that is, bits + 2 and 14 are set to 1, and the rest are set to 0. The symbolic values + are shown as a list of values. If a named value, which is not + specified in the type definition, is shown, a runtime error occurs.

+

BIT STRINGs can also be subtyped with, for example, a SIZE + specification:

+ 
+Bits3 ::= BIT STRING (SIZE(0..31))
+

This means that no bit higher than 31 can be set.

+ +
+ Deprecated Representations for BIT STRING +

In addition to the representations described earlier, the + following deprecated representations are available if the + specification has been compiled with option + legacy_erlang_types:

+ + Aa a list of binary digits (0 or 1). This format is + accepted as input to the encode functions, and a BIT STRING + is decoded to this format if option + legacy_bit_string is given. + + As {Unused,Binary} where Unused denotes + how many trailing zero-bits 0-7 that are unused in the + least significant byte in Binary. This format is + accepted as input to the encode functions, and a BIT + STRING is decoded to this format if + compact_bit_string has been given. + + As a hexadecimal number (or an integer). Avoid this + as it is easy to misinterpret a BIT + STRING value in this format. + + +
+
+ +
+ + OCTET STRING +

OCTET STRING is the simplest of all ASN.1 types. OCTET + STRING only moves or transfers, for example, binary files or other + unstructured information complying with two rules: the + bytes consist of octets and encoding is not required.

+

It is possible to have the following ASN.1 type definitions:

+ 
+O1 ::= OCTET STRING
+O2 ::= OCTET STRING (SIZE(28))
+

With the following example assignments in Erlang:

+ 
+O1Val = <<17,13,19,20,0,0,255,254>>,
+O2Val = <<"must be exactly 28 chars....">>,
+

By default, an OCTET STRING is always represented as + an Erlang binary. If the specification has been compiled with + option legacy_erlang_types, the encode functions + accept both lists and binaries, and the decode functions + decode an OCTET STRING to a list.

+
+ +
+ + Character Strings +

ASN.1 supports a wide variety of character sets. The main difference + between an OCTET STRING and a character string is that the + OCTET STRING has no imposed semantics on the bytes delivered.

+

However, when using, for example, IA5String (which closely + resembles ASCII), byte 65 (in decimal + notation) means character 'A'. +

+

For example, if a defined type is to be a VideotexString and + an octet is received with the unsigned integer value X, + the octet is to be interpreted as specified in standard + ITU-T T.100, T.101. +

+

The ASN.1 to Erlang compiler + does not determine the correct interpretation of each BER + string octet value with different character strings. The + application is responsible for interpretation + of octets. Therefore, from the BER + string point of view, octets are very similar to + character strings and are compiled in the same way. +

+

When PER 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. +

+

Examples:

+ 
+Digs ::= NumericString (SIZE(1..3))
+TextFile ::= IA5String (SIZE(0..64000))
+

The corresponding Erlang assignments:

+ 
+DigsVal1 = "456",
+DigsVal2 = "123",
+TextFileVal1 = "abc...xyz...",
+TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
+

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 character 'A'. 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. Assume the following + specification is in file PrimStrings.asn1:

+ 
+PrimStrings DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+   BMP ::= BMPString
+END
+ +

Encoding and decoding some strings:

+ + 
+1> asn1ct:compile('PrimStrings', [ber]).
+ok
+2> {ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).
+{ok,<<30,4,53,54,45,56>>}
+3> 'PrimStrings':decode('BMP', Bytes1).
+{ok,[{0,0,53,53},{0,0,45,56}]}
+4> {ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).
+{ok,<<30,4,53,53,0,65>>}
+5> 'PrimStrings':decode('BMP', Bytes2).
+{ok,[{0,0,53,53},65]}
+6> {ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").
+{ok,<<30,20,0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103>>}
+7> 'PrimStrings':decode('BMP', Bytes3).
+{ok,"BMP string"}
+ +

Type UTF8String is represented as a UTF-8 encoded binary in + Erlang. Such binaries can be created directly using the binary syntax + or by converting from a list of Unicode code points using function + unicode:characters_to_binary/1.

+ +

The following shows examples of how UTF-8 encoded binaries can + be created and manipulated:

+ 
+1> Gs = "Мой маленький Гном".
+[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
+ 1081,32,1043,1085,1086,1084]
+2> Gbin = unicode:characters_to_binary(Gs).
+<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
+  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
+  208,...>>
+3> Gbin = <<"Мой маленький Гном"/utf8>>.
+<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
+  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
+  208,...>>
+4> Gs = unicode:characters_to_list(Gbin).
+[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
+ 1081,32,1043,1085,1086,1084]
+ +

For details, see the unicode + module in stdlib.

+ +

In the following example, this ASN.1 specification is used:

+ 
+UTF DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+   UTF ::= UTF8String
+END
+ +

Encoding and decoding a string with Unicode characters:

+ + 
+5> asn1ct:compile('UTF', [ber]).
+ok
+6> {ok,Bytes1} = 'UTF':encode('UTF', <<"Гном"/utf8>>).
+{ok,<<12,8,208,147,208,189,208,190,208,188>>}
+7> {ok,Bin1} = 'UTF':decode('UTF', Bytes1).
+{ok,<<208,147,208,189,208,190,208,188>>}
+8> io:format("~ts\n", [Bin1]).
+Гном
+ok
+9> unicode:characters_to_list(Bin1).
+[1043,1085,1086,1084]
+
+ +
+ + OBJECT IDENTIFIER +

The type OBJECT IDENTIFIER is used whenever a unique identity is + required. An ASN.1 module, a transfer syntax, and so on, is identified + with an OBJECT IDENTIFIER. Assume the following example:

+ 
+Oid ::= OBJECT IDENTIFIER
+

Therefore, the following example is a valid Erlang instance of + type 'Oid':

+ 
+OidVal1 = {1,2,55},
+

The OBJECT IDENTIFIER value is simply a tuple with the + consecutive values, which must be integers. +

+

The first value is limited to the values 0, 1, or 2. The + second value must be in the range 0..39 when the first value + is 0 or 1. +

+

The OBJECT IDENTIFIER is an important type and it is + widely used within different standards to identify various + objects uniquely. Dubuisson: ASN.1 - Communication Between + Heterogeneous Systems includes an + easy-to-understand description of the use of + OBJECT IDENTIFIER.

+
+ +
+ + Object Descriptor +

Values of this type can be assigned a value as an ordinary string + as follows:

+ + 
+      "This is the value of an Object descriptor"
+
+ +
+ + TIME Types +

Two time types are defined within ASN.1: Generalized + Time and Universal Time Coordinated (UTC). Both are assigned a + value as an ordinary string within double quotes, for example, + "19820102070533.8".

+

For DER encoding, the compiler does not check the validity + of the time values. The DER requirements upon those strings are + regarded as a matter for the application to fulfill.

+
+ +
+ + SEQUENCE +

The structured types of ASN.1 are constructed from other types + in a manner similar to the concepts of array and struct in C.

+

A SEQUENCE in ASN.1 is + comparable with a struct in C and a record in Erlang. + A SEQUENCE can be defined as follows:

+ 
+Pdu ::= SEQUENCE {
+   a INTEGER,
+   b REAL,
+   c OBJECT IDENTIFIER,
+   d NULL }
+

This is a 4-component structure called Pdu. The record format + is the major format for representation of SEQUENCE in Erlang. + For each SEQUENCE and SET in an ASN.1 module an Erlang + record declaration is generated. For Pdu, a record + like the following is defined:

+ 
+-record('Pdu',{a, b, c, d}).
+

The record declarations for a module M are placed in a + separate M.hrl file.

+

Values can be assigned in Erlang as follows:

+ 
+MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}.
+

The decode functions return a record as result when decoding + a SEQUENCE or a SET.

+ +

A SEQUENCE and a SET can contain a component + with a DEFAULT keyword followed by the actual value, which + is the default value. The DEFAULT keyword means that the + application doing the encoding can omit encoding of the value, which + results in fewer bytes to send to the receiving application.

+ +

An application can use the atom asn1_DEFAULT to indicate + that the encoding is to be omitted for that position in + the SEQUENCE.

+ +

Depending on the encoding rules, the encoder can also compare + the given value to the default value and automatically omit the + encoding if the values are equal. How much effort the encoder makes + to compare the values depends on the encoding rules. The DER + encoding rules forbid encoding a value equal to the default value, + so it has a more thorough and time-consuming comparison than the + encoders for the other encoding rules.

+ +

In the following example, this ASN.1 specification is used:

+ 
+File DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+Seq1 ::= SEQUENCE {
+    a INTEGER DEFAULT 1,
+    b Seq2 DEFAULT {aa TRUE, bb 15}
+}
+
+Seq2 ::= SEQUENCE {
+    aa BOOLEAN,
+    bb INTEGER
+}
+
+Seq3 ::= SEQUENCE {
+    bs BIT STRING {a(0), b(1), c(2)} DEFAULT {a, c}
+}
+END
+

Example where the BER encoder is able to omit encoding + of the default values:

+ 
+1> asn1ct:compile('File', [ber]).
+ok
+2> 'File':encode('Seq1', {'Seq1',asn1_DEFAULT,asn1_DEFAULT}).
+{ok,<<48,0>>}
+3> 'File':encode('Seq1', {'Seq1',1,{'Seq2',true,15}}).
+{ok,<<48,0>>}
+ +

Example with a named BIT STRING where the BER + encoder does not omit the encoding:

+ 
+4> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT).
+{ok,<<48,0>>}
+5> 'File':encode('Seq3', {'Seq3',<<16#101:3>>).
+{ok,<<48,4,128,2,5,160>>}
+ +

The DER encoder omits the encoding for the same BIT STRING:

+ 
+6> asn1ct:compile('File', [ber,der]).
+ok
+7> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT).
+{ok,<<48,0>>}
+8> 'File':encode('Seq3', {'Seq3',<<16#101:3>>).
+{ok,<<48,0>>}
+
+ +
+ + SET +

In Erlang, the SET type is used exactly as SEQUENCE. + Notice that if BER or DER encoding rules are used, decoding a + SET is slower than decoding a SEQUENCE because the + components must be sorted.

+
+ +
+ Extensibility for SEQUENCE and SET +

When a SEQUENCE or SET contains an extension marker + and extension components as the following, the type can get more + components in newer versions of the ASN.1 spec:

+ 
+SExt ::= SEQUENCE {
+           a INTEGER,
+           ...,
+           b BOOLEAN }
+

In this case it has got a new + component b. Thus, incoming messages that are decoded + can have more or fever components than this one. +

+

The component b is treated as + an original component when encoding a message. In this case, as + it is not an optional element, it must be encoded. +

+

During decoding, the b field of the record gets the decoded + value of the b + component, if present, otherwise the value asn1_NOVALUE.

+
+ +
+ + CHOICE +

The type CHOICE is a space saver and is similar to the + concept of a 'union' in C.

+

Assume the following:

+ 
+SomeModuleName DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+T ::= CHOICE {
+        x REAL,
+        y INTEGER,
+        z OBJECT IDENTIFIER }
+END
+

It is then possible to assign values as follows:

+ 
+TVal1 = {y,17},
+TVal2 = {z,{0,1,2}},
+

A CHOICE value is always represented as the tuple + {ChoiceAlternative, Val} where ChoiceAlternative + is an atom denoting the selected choice alternative. +

+ +
+ Extensible CHOICE +

When a CHOICE contains an extension marker and the + decoder detects an unknown alternative of the CHOICE, + the value is represented as follows:

+ 
+{asn1_ExtAlt, BytesForOpenType}
+

Here BytesForOpenType is a list of bytes constituting the + encoding of the "unknown" CHOICE alternative.

+
+
+ +
+ + SET OF and SEQUENCE OF +

The types SET OF and SEQUENCE OF correspond + to the concept of an array + in several programming languages. The Erlang syntax for + both types is straightforward, for example:

+ 
+Arr1 ::= SET SIZE (5) OF INTEGER (4..9) 
+Arr2 ::= SEQUENCE OF OCTET STRING
+

In Erlang the following can apply:

+ 
+Arr1Val = [4,5,6,7,8],
+Arr2Val = ["abc",[14,34,54],"Octets"],
+

Notice that the definition of type SET OF 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.

+

However, for a value of type SET OF, the DER + encoding format requires the elements to be sent in ascending + order of their encoding, which implies an expensive sorting + procedure in runtime. Therefore it is recommended to + use SEQUENCE OF instead of SET OF if possible.

+
+ +
+ + ANY and ANY DEFINED BY +

The types ANY and ANY DEFINED BY have been removed + from the standard since 1994. It is recommended not to use + these types any more. They can, however, exist in some old ASN.1 + modules. The idea with this type was to leave a "hole" in a + definition where it was possible to + put unspecified data of any kind, even non-ASN.1 data.

+

A value of this type is encoded as an open type.

+

Instead of ANY and ANY DEFINED BY, it is + recommended to use + information object class, table constraints, and + parameterization. In particular the construct + TYPE-IDENTIFIER.@Type accomplish the same as the + deprecated ANY.

+

See also + Information object.

+
+ +
+ + EXTERNAL, EMBEDDED PDV, and CHARACTER STRING +

The types EXTERNAL, EMBEDDED PDV, and + CHARACTER STRING are used in presentation layer negotiation. + They are encoded according to their associated type, see X.680.

+

The type EXTERNAL had a slightly different associated type + before 1994. X.691 states that encoding must follow + the older associated type. So, generated encode/decode + functions convert values of the newer format to the older format + before encoding. This implies that it is allowed to use + EXTERNAL type values of either format for encoding. Decoded + values are always returned in the newer format.

+
+ +
+ Embedded Named Types +

The structured types previously described can have other named + types as their components. The general syntax to assign a value + to component C of a named ASN.1 type T in Erlang + is the record syntax #'T'{'C'=Value}. + Here Value can be a value of yet another type T2, + for example:

+ 
+EmbeddedExample DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+B ::= SEQUENCE {
+        a Arr1,
+        b T }
+
+Arr1 ::= SET SIZE (5) OF INTEGER (4..9) 
+
+T ::= CHOICE {
+        x REAL,
+        y INTEGER,
+        z OBJECT IDENTIFIER }
+        END
+

SEQUENCE b can be encoded as follows in Erlang:

+ 
+1> 'EmbeddedExample':encode('B', {'B',[4,5,6,7,8],{x,"7.77"}}).
+{ok,<<5,56,0,8,3,55,55,55,46,69,45,50>>}
+
+
+ +
+ Naming of Records in .hrl Files +

When an ASN.1 specification is compiled, all defined types of type + SET or SEQUENCE result in a corresponding record in the + generated .hrl file. This is because the values for + SET and SEQUENCE are represented as records as + mentioned earlier.

+

Some special cases of this functionality are presented in the + next section.

+ +
+ Embedded Structured Types +

In ASN.1 it is also possible to have components that are themselves + structured types. + For example, it is possible to have the following:

+ 
+Emb ::= SEQUENCE {
+    a SEQUENCE OF OCTET STRING,
+    b SET {
+       a INTEGER,
+       b INTEGER DEFAULT 66},
+    c CHOICE {
+       a INTEGER,
+       b FooType } }
+
+FooType ::= [3] VisibleString
+

The following records are generated because of type Emb:

+ 
+-record('Emb,{a, b, c}).
+-record('Emb_b',{a, b = asn1_DEFAULT}). % the embedded SET type
+

Values of type Emb can be assigned as follows:

+ +V = #'Emb'{a=["qqqq",[1,2,255]], + b = #'Emb_b'{a=99}, + c ={b,"Can you see this"}}. +

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 the SEQUENCE, SET, or CHOICE + types in the line, each component name/alternative name is + added to the record name.

+

Example:

+ 
+Seq ::= SEQUENCE{
+    a CHOICE{
+        b SEQUENCE {
+           c  INTEGER
+        }
+    }
+}
+

This results in the following record:

+ 
+-record('Seq_a_b',{c}).
+

If the structured type has a component with an embedded + SEQUENCE OF/SET OF which embedded type in turn + is a SEQUENCE/SET, it gives a record with the + SEQUENCE OF/SET OF + addition as in the following example:

+ 
+Seq ::= SEQUENCE {
+    a SEQUENCE OF SEQUENCE {
+           b
+               }
+    c SET OF SEQUENCE {
+           d
+               }
+}
+

This results in the following records:

+ 
+-record('Seq_a_SEQOF'{b}).
+-record('Seq_c_SETOF'{d}).
+

A parameterized type is to be considered as an embedded + type. Each time such a type is referenced, an instance of it is + defined. Thus, in the following example a record with name + 'Seq_b' is generated in the .hrl file and is used + to hold values:

+ 
+Seq ::= SEQUENCE {
+    b PType{INTEGER}
+}
+
+PType{T} ::= SEQUENCE{
+    id T
+}
+
+ +
+ Recursive Types +

Types that refer to themselves are called recursive types. + Example:

+ 
+Rec ::= CHOICE {
+     nothing NULL,
+     something SEQUENCE {
+          a INTEGER,
+          b OCTET STRING,
+          c Rec }}
+

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 follows:

+ 
+V = {something,#'Rec_something'{a = 77, 
+                                b = "some octets here", 
+                                c = {nothing,'NULL'}}}.
+
+
+ +
+ ASN.1 Values +

Values can be assigned to an ASN.1 type within the ASN.1 code + itself, as opposed to the actions in the previous section 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. A short example:

+ 
+TT ::= SEQUENCE {
+   a INTEGER,
+   b SET OF OCTET STRING }
+
+tt TT ::= {a 77,b {"kalle","kula"}}
+

The value defined here can be used in several ways. It can, for + example, be used as the value in some DEFAULT component:

+ 
+SS ::= SET {
+    s OBJECT IDENTIFIER,
+    val TT DEFAULT tt }
+

It can also be used from inside an Erlang program. If this ASN.1 + code is defined in ASN.1 module Values, the ASN.1 value + tt can be reached from Erlang as a function call to + 'Values':tt() as in the following example:

+ 
+1> Val = 'Values':tt().
+{'TT',77,["kalle","kula"]}
+2> {ok,Bytes} = 'Values':encode('TT',Val).
+{ok,<<48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
+      107,117,108,97>>}
+4> 'Values':decode('TT',Bytes).
+{ok,{'TT',77,["kalle","kula"]}}
+5>
+

This example shows that a function is generated by the compiler + that returns a valid Erlang representation of the value, although + the value is of a complex type.

+

Furthermore, a macro is generated for each value in the .hrl + file. So, the defined value tt can also be extracted by + ?tt in application code.

+
+ +
+ Macros +

The type MACRO is not supported. It is no longer part of + the ASN.1 standard.

+
+ +
+ + ASN.1 Information Objects (X.681) +

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. Only a brief explanation is given here.

+

These constructs makes it possible to define open types, that + is, values of that type can be of any ASN.1 type. Also, + relationships can be defined between different types and + values, as classes can hold types, values, objects, object + sets, and other classes in their fields. A class can be + defined in ASN.1 as follows:

+ 
+GENERAL-PROCEDURE ::= CLASS {
+      &Message,
+      &Reply               OPTIONAL,
+      &Error               OPTIONAL,
+      &id          PrintableString UNIQUE
+}
+WITH SYNTAX {
+      NEW MESSAGE     &Message
+      [REPLY           &Reply]
+      [ERROR           &Error]
+      ADDRESS          &id
+}
+

An object is an instance of a class. An object set is a set + containing objects of a specified class. A definition can look + as follows:

+ 
+object1 GENERAL-PROCEDURE ::= {
+    NEW MESSAGE      PrintableString
+    ADDRESS          "home"
+}
+
+object2 GENERAL-PROCEDURE ::= {
+    NEW MESSAGE INTEGER
+    ERROR INTEGER
+    ADDRESS "remote"
+}
+

The object object1 is an instance of the class + GENERAL-PROCEDURE and has one type field and one + fixed type value field. The object object2 has also an + optional field ERROR, which is a type field. The field + ADDRESS is a UNIQUE field. Objects in an object set + must have unique values in their UNIQUE field, as in + GENERAL-PROCEDURES:

+ 
+GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
+    object1 | object2}
+

You cannot encode a class, object, or object set, only refer to + it when defining other ASN.1 entities. Typically you refer to a + class as well as to object sets by table constraints and component + relation constraints (X.682) in ASN.1 types, as in the following:

+ 
+StartMessage  ::= SEQUENCE {
+    msgId  GENERAL-PROCEDURE.&id  ({GENERAL-PROCEDURES}),
+    content GENERAL-PROCEDURE.&Message ({GENERAL-PROCEDURES}{@msgId}),
+    }
+

In type StartMessage, the constraint following field + content tells that in a value of type + StartMessage the value in field content must + come from the same object that is chosen by field msgId.

+

So, the value + #'StartMessage'{msgId="home",content="Any Printable String"} + is legal to encode as a StartMessage value. However, the value + #'StartMessage'{msgId="remote", content="Some String"} + is illegal as the constraint in StartMessage tells that + when you have chosen a value from a specific object in object + set GENERAL-PROCEDURES in field + msgId, you must choose a value from that same object in + the content field too. In this second case, it is to be + any INTEGER value.

+

StartMessage can in field content be + encoded with a value of any type that an object in object set + GENERAL-PROCEDURES has in its NEW MESSAGE field. + This field refers to a type field + &Message in the class. Field msgId is always + encoded as a PrintableString, as the field refers to a + fixed type in the class.

+

In practice, object sets are usually declared to be extensible so + that more objects can be added to the set later. Extensibility is + indicated as follows:

+ 
+GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
+    object1 | object2, ...}
+

When decoding a type that uses an extensible set constraint, + it is always possible that the value in field UNIQUE + is unknown (that is, the type has been encoded with a later + version of the ASN.1 specification). The unencoded data is then + returned wrapped in a tuple as follows:

+ + 
+{asn1_OPENTYPE,Binary}
+ +

Here Binary is an Erlang binary that contains the encoded + data. (If option legacy_erlang_types has been given, + only the binary is returned.)

+
+ +
+ Parameterization (X.683) +

Parameterization, which is defined in X.683, can be used when + defining types, values, value sets, classes, objects, or object sets. + A part of a definition can be supplied as a parameter. For + example, if a Type is used in a definition with a certain + purpose, you want the type name to express the intention. This + can be done with parameterization.

+

When many types (or another ASN.1 entity) only differ in some + minor cases, but the structure of the types is similar, only + one general type can be defined and the differences can be supplied + through parameters.

+

Example of use of parameterization:

+ 
+General{Type} ::= SEQUENCE
+{
+     number     INTEGER,
+     string     Type
+}
+      
+T1 ::= General{PrintableString}
+
+T2 ::= General{BIT STRING}
+

An example of a value that can be encoded as type T1 is + {12,"hello"}.

+

Notice that the compiler does not generate encode/decode functions + for parameterized types, only for the instances of the parameterized + types. Therefore, if a file contains the types General{}, + T1, and T2 as in the previous example, encode/decode + functions are only generated for T1 and T2. +

+
+ + diff --git a/lib/asn1/doc/src/asn1_introduction.xml b/lib/asn1/doc/src/asn1_introduction.xml new file mode 100644 index 0000000000..ae0379684a --- /dev/null +++ b/lib/asn1/doc/src/asn1_introduction.xml @@ -0,0 +1,99 @@ + + + + +
+ + 19972013 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Introduction + + + 2015-03-31 + A + asn1_introduction.xml +
+ +

The ASN.1 application provides the following:

+ + + 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. + Runtime functions used by the generated code. + Support for the following encoding rules: + Basic Encoding Rules (BER) + Distinguished Encoding Rules (DER), a specialized form of + BER that is used in security-conscious applications + Packed Encoding Rules (PER), both the aligned and + unaligned variant + + + + +
+ Scope +

This application covers all features of ASN.1 up to the 1997 + edition of the specification. In the 2002 edition, + new features were introduced. The following features + of the 2002 edition are fully or partly supported:

+ + +

Decimal notation (for example, "1.5e3) for REAL values. + The NR1, NR2, and NR3 formats as explained in ISO 6093 are + supported.

+ + +

The RELATIVE-OID type for relative object identifiers is + fully supported.

+ + +

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.

+ + +

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.

+ + +

Multiple-line comments as in C, /* ... */, are + supported.

+ + +
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language, concepts of OTP, and is familiar with the + ASN.1 notation. The ASN.1 notation is documented in the standard + definition X.680, which is the primary text. It can also be + helpful, but not necessary, to read the standard definitions + X.681, X.682, X.683, X.690, and X.691.

+

A good book explaining those reference texts is + Dubuisson: ASN.1 - Communication Between Heterogeneous Systems, + is free to download at + http://www.oss.com/asn1/dubuisson.html.

+
+ + + diff --git a/lib/asn1/doc/src/asn1_overview.xml b/lib/asn1/doc/src/asn1_overview.xml new file mode 100644 index 0000000000..4a10819c36 --- /dev/null +++ b/lib/asn1/doc/src/asn1_overview.xml @@ -0,0 +1,49 @@ + + + + +
+ + 19972013 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ASN.1 + Kenneth Lundin + + 1999-03-25 + D + asn1_overview.xml +
+ +
+ Introduction + +

ASN.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 any type of communication + channel. This way, two applications written in different + programming languages running on different computers, and with + different internal representation of data, can exchange instances + of structured data types.

+ +
+ + diff --git a/lib/asn1/doc/src/asn1_spec.xmlsrc b/lib/asn1/doc/src/asn1_spec.xmlsrc index 9001aca65c..5bee9f0075 100644 --- a/lib/asn1/doc/src/asn1_spec.xmlsrc +++ b/lib/asn1/doc/src/asn1_spec.xmlsrc @@ -29,94 +29,105 @@ asn1_spec.xml -

When performance is of highest priority and one is interested in - a limited part of the ASN.1 encoded message, before one decide what - to do with the rest of it, one may want to decode only this small - part. The situation may be a server that has to decide to which - addressee it will send a message. The addressee may be interested in - the entire message, but the server may be a bottleneck that one want - to spare any unnecessary load. Instead of making two complete decodes (the normal case of decode), one in the server and one - in the addressee, it is only necessary to make one specialized decode(in the server) and another complete decode(in the - addressee). The following specialized decodes exclusive decode and selected decode support to solve this and - similar problems. -

+

When performance is of highest priority and you are interested in + a limited part of the ASN.1 encoded message before deciding what + to do with the rest of it, an option is to decode only this small + part. The situation can be a server that has to decide the + addressee of a message. The addressee can be interested in + the entire message, but the server can be a bottleneck that you want + to spare any unnecessary load.

+

Instead of making two complete decodes (the normal case of + decode), one in the server and one in the addressee, it is only + necessary to make one specialized decode(in the server) + and another complete decode(in the addressee). This section + describes the following two specialized decodes, which support + to solve this and similar problems:

+ + Exclusive decode + Selected decode +

So far this functionality is only provided when using the - optimized BER_BIN version, that is when compiling with the - options ber_bin and optimize. It does also work - using the nif option. We have no intent to make this - available on the default BER version, but maybe in the PER_BIN - version (per_bin). + optimized BER_BIN version, that is, when compiling with + options ber_bin and optimize. It also works + with optionnif. We do not intent to make this functionality + available in the default BER version, but possibly in the + PER_BIN version (per_bin).

Exclusive Decode

The basic idea with exclusive - decode is that you specify which parts of the message you want to + decode is to specify which parts of the message you want to exclude from being decoded. These parts remain encoded and are - returned in the value structure as binaries. They may be decoded + returned in the value structure as binaries. They can be decoded in turn by passing them to a certain decode_part/2 - function. The performance gain is high when the message is large - and you can do an exclusive decode and later on one or several - decodes of the parts or a second complete decode instead of two or + function. The performance gain is high for large messages. + You can do an exclusive decode and later one or more + decodes of the parts, or a second complete decode instead of two or more complete decodes.

- How To Make It Work -

In order to make exclusive decode work you have to do the - following: + Procedure +

To perform an exclusive decode:

- First,decide the name of the function for the exclusive - decode. - Second, write instructions that must consist of the name - of the exclusive decode function, the name of the ASN.1 - specification and a notation that tells which parts of the - message structure will be excluded from decode. These - instructions shall be included in a configuration - file. - Third, compile with the additional option - asn1config. The compiler searches for a configuration - file with the same name as the ASN.1 spec but with the - extension .asn1config. This configuration file is not the same - as used for compilation of a set of files. See section - Writing an Exclusive Decode Instruction. + Step 1: Decide the name of the function for the + exclusive decode. +

Step 2: Include the following instructions in + a configuration file:

+ + The name of the exclusive decode function + The name of the ASN.1 specification + A notation that tells which parts of the message + structure to be excluded from decode + + Step 3 Compile with the additional option + asn1config. The compiler searches for a configuration + file with the same name as the ASN.1 specification but with + extension .asn1config. This configuration file is not + the same as used for compilation of a set of files. See Section + Writing an Exclusive Decode + Instruction.
User Interface -

The run-time user interface for exclusive decode consists of - two different functions. First, the function for an exclusive - decode, whose name the user decides in the configuration - file. Second, the compiler generates a decode_part/2 - function when exclusive decode is chosen. This function decodes - the parts that were left undecoded during the exclusive - decode. Both functions are described below. -

-

If the exclusive decode function has for example got the name +

The runtime user interface for exclusive decode consists of + the following two functions:

+ + A function for an exclusive decode, whose name the user + decides in the configuration file + The compiler generates a decode_part/2 + function when exclusive decode is chosen. This function decodes + the parts that were left undecoded during the exclusive + decode. + +

Both functions are described in the following.

+

If the exclusive decode function has, for example, the name decode_exclusive and an ASN.1 encoded message - Bin shall be exclusive decoded, the call is:

+ Bin is to be exclusive decoded, the call is as follows:

 {ok,Excl_Message} = 'MyModule':decode_exclusive(Bin)
-

The result Excl_Message has the same structure as an - complete decode would have, except for the parts of the top-type - that were not decoded. The undecoded parts will be on their place - in the structure on the format {Type_Key,Undecoded_Value}. +

The result Excl_Message has the same structure as a + complete decode would have, except for the parts of the top type + that were not decoded. The undecoded parts are on their places + in the structure on format {Type_Key,Undecoded_Value}.

-

Each undecoded part that shall be decoded must be fed into the decode_part/2 function,like:

+

Each undecoded part that is to be decoded must be fed into + function decode_part/2 as follows:

-{ok,Part_Message} = 'MyModule':decode_part(Type_Key,Undecoded_Value)
+{ok,Part_Message} = 'MyModule':decode_part(Type_Key,Undecoded_Value)
Writing an Exclusive Decode Instruction -

This instruction is written in the configuration file on the - format:

+

This instruction is written in the configuration file + in the following format:

-
 Exclusive_Decode_Instruction = {exclusive_decode,{Module_Name,Decode_Instructions}}.
 
 Module_Name = atom()
@@ -137,70 +148,76 @@ Element = {Name,parts} |
 
 Top_Type = atom()
 
-Name = atom()
-
-

Observe that the instruction must be a valid Erlang term ended - by a dot. +Name = atom() +

The instruction must be a valid Erlang term ended by a dot.

-

In the Type_List the "path" from the top type to each - undecoded sub-components is described. The top type of the path is +

In Type_List the "path" from the top type to each + undecoded subcomponents is described. The top type of the path is an atom, the name of it. The action on each component/type that - follows will be described by one of {Name,parts}, {Name,undecoded}, {Name,Element_List}

-

The use and effect of the actions are: + follows is described by one of + {Name,parts}, {Name,undecoded}, {Name,Element_List}.

+

The use and effect of the actions are as follows:

- {Name,undecoded} Tells that the element will be - left undecoded during the exclusive decode. The type of Name may - be any ASN.1 type. The value of element Name will be returned as a - tuple,as mentioned above, in the value structure of the top type. - {Name,parts} The type of Name may be one of - SEQUENCE OF or SET OF. The action implies that the different - components of Name will be left undecoded. The value of Name - will be returned as a tuple, as above , where the second element is a list of - binaries. That is because the representation of a SEQUENCE OF/ - SET OF in Erlang is a list of its internal type. Any of the - elements of this list or the entire list can be decoded by the - decode_part function. - {Name,Element_List}This action is used when one or - more of the sub-types of Name will be exclusive decoded. + {Name,undecoded} - Tells that the element is left + undecoded during the exclusive decode. The type of Name + can be any ASN.1 type. The value of element Name is + returned as a tuple (as mentioned in the previous section) in + the value structure of the top type. + {Name,parts} - The type of Name can be one of + SEQUENCE OF or SET OF. The action implies that + the different components of Name are left undecoded. The + value of Name is returned as a tuple (as mentioned in + the previous section) where the second element is a list of + binaries. This is because the representation of a SEQUENCE OF + or a SET OF in Erlang is a list of its internal type. Any + of the elements in this list or the entire list can be decoded by + function decode_part. + {Name,Element_List} - This action is used when one or + more of the subtypes of Name is exclusive decoded. -

Name in the actions above may be a component name of a - SEQUENCE or a SET or a name of an alternative in a CHOICE. +

Name in these actions can be a component name of a + SEQUENCE OF or a SET OF, or a name of an alternative + in a CHOICE.

Example -

In the examples below we use the definitions from the following ASN.1 spec:

+

In this examples, the definitions from the following ASN.1 + specification are used:

-

If Button is a top type and we want to exclude - component number from decode the Type_List in the - instruction in the configuration file will be - ['Button',[{number,undecoded}]]. If we call the decode - function decode_Button_exclusive the Decode_Instruction - will be +

If Button is a top type and it is needed to exclude + component number from decode, Type_List in the + instruction in the configuration file is + ['Button',[{number,undecoded}]]. If you call the decode + function decode_Button_exclusive, Decode_Instruction is {decode_Button_exclusive,['Button',[{number,undecoded}]]}.

-

We also have another top type Window whose sub - component actions in type Status and the parts of component - buttonList shall be left undecoded. For this type we name - the function decode__Window_exclusive. The whole - Exclusive_Decode_Instruction configuration is as follows:

+

Another top type is Window whose subcomponent + actions in type Status and the parts of component + buttonList are to be left undecoded. For this type, the + function is named decode__Window_exclusive. The complete + Exclusive_Decode_Instruction configuration is as follows:

+

The following figure shows the bytes of a Window:status + message. The components buttonList and actions are + excluded from decode. Only state and enabled are decoded + when decode__Window_exclusive is called.

- Figure symbolizes the bytes of a Window:status message. The components buttonList and actions are excluded from decode. Only state and enabled are decoded when decode__Window_exclusive is called. + Bytes of a Window:status Message

-

Compiling GUI.asn including the configuration file is done like:

+

Compiling GUI.asn including the configuration file is done + as follows:

 unix> erlc -bber_bin +optimize +asn1config GUI.asn
 
-erlang> asn1ct:compile('GUI',[ber_bin,optimize,asn1config]).
-

The module can be used like:

+erlang> asn1ct:compile('GUI',[ber_bin,optimize,asn1config]). +

The module can be used as follows:

-
 1> Button_Msg = {'Button',123,true}.
 {'Button',123,true}
 2> {ok,Button_Bytes} = 'GUI':encode('Button',Button_Msg).
@@ -289,35 +306,39 @@ BoolOpt,{Type_Key_Choice,Val_Choice}}}}=
 11> 'GUI':decode_part(Type_Key_SeqOf,hd(Val_SEQOF)).
 {ok,{'Button',3,true}}
 12> 'GUI':decode_part(Type_Key_Choice,Val_Choice).  
-{ok,{possibleActions,[{'Action',16,{'Button',17,true}}]}}
-
+{ok,{possibleActions,[{'Action',16,{'Button',17,true}}]}}
Selective Decode -

This specialized decode decodes one single subtype of a - constructed value. It is the fastest method to extract one sub - value. The typical use of this decode is when one want to - inspect, for instance a version number,to be able to decide what +

This specialized decode decodes a subtype of a + constructed value and is the fastest method to extract a + subvalue. This decode is typically used when you want to + inspect, for example, a version number, to be able to decide what to do with the entire value. The result is returned as {ok,Value} or {error,Reason}.

- How To Make It Work -

The following steps are necessary: + Procedure +

To perform a selective decode:

- Write instructions in the configuration - file. Including the name of a user function, the name of the ASN.1 - specification and a notation that tells which part of the type - will be decoded. - Compile with the additional option - asn1config. The compiler searches for a configuration file - with the same name as the ASN.1 spec but with the extension - .asn1config. In the same file you can provide configuration specs - for exclusive decode as well. The generated Erlang module has the +

Step 1: Include the following instructions in + the configuration file:

+ + The name of the user function + The name of the ASN.1 specification + A notation that tells which part of the type to be + decoded + + Step 2: Compile with the additional option + asn1config. The compiler searches for a configuration file + with the same name as the ASN.1 specification, but with extension + .asn1config. In the same file you can also provide + configuration specifications for exclusive decode. + The generated Erlang module has the usual functionality for encode/decode preserved and the specialized decode functionality added. @@ -326,21 +347,20 @@ BoolOpt,{Type_Key_Choice,Val_Choice}}}}=
User Interface

The only new user interface function is the one provided by the - user in the configuration file. You can invoke that function by + user in the configuration file. The function is started by the ModuleName:FunctionName notation.

-

So, if you have the following spec +

For example, if the configuration file includes the specification {selective_decode,{'ModuleName',[{selected_decode_Window,TypeList}]}} - in the con-fig file, you do the selective decode by + do the selective decode by {ok,Result}='ModuleName':selected_decode_Window(EncodedBinary).

Writing a Selective Decode Instruction -

It is possible to describe one or many selective decode - functions in a configuration file, you have to use the following - notation:

+

One or more selective decode functions can be described in a + configuration file. Use the following notation:

 Selective_Decode_Instruction = {selective_decode,{Module_Name,Decode_Instructions}}.
 
@@ -358,37 +378,43 @@ Element_List = Name|List_Selector
 
 Name = atom()
 
-List_Selector = [integer()]
-

Observe that the instruction must be a valid Erlang term ended - by a dot. -

-

The Module_Name is the same as the name of the ASN.1 - spec, but without the extension. A Decode_Instruction is - a tuple with your chosen function name and the components from - the top type that leads to the single type you want to - decode. Notice that you have to choose a name of your function - that will not be the same as any of the generated functions. The - first element of the Type_List is the top type of the - encoded message. In the Element_List it is followed by - each of the component names that leads to selected type. Each of - the names in the Element_List must be constructed types - except the last name, which can be any type. +List_Selector = [integer()] +

The instruction must be a valid Erlang term ended by a dot.

-

The List_Selector makes it possible to choose one of the - encoded components in a SEQUENCE OF/ SET OF. It is also possible - to go further in that component and pick a sub type of that to - decode. So in the Type_List: ['Window',status,buttonList,[1],number] the - component buttonList has to be a SEQUENCE OF or SET OF type. In - this example component number of the first of the encoded - elements in the SEQUENCE OF buttonList is selected. This apply on - the ASN.1 spec above. + + Module_Name is the same as the name of the ASN.1 + specification, but without the extension. + Decode_Instruction is a tuple with your chosen + function name and the components from the top type that leads + to the single type you want to decode. Ensure to choose a name + of your function that is not the same as any of the generated + functions. + The first element of Type_List is the top type of the + encoded message. In Element_List, it is followed by + each of the component names that leads to selected type. + Each name in Element_List must be a constructed type + except the last name, which can be any type. + List_Selector makes it possible to choose one of the + encoded components in a a SEQUENCE OF or a SET OF. + It is also possible to go further in that component and pick a + subtype of that to decode. So, in the Type_List: + ['Window',status,buttonList,[1],number], component + buttonList must be of type SEQUENCE OF or + SET OF. + +

In the example, component number of the first of the encoded + elements in the SEQUENCE OF buttonList is selected. + This applies on the ASN.1 specification in Section + Writing an Exclusive Decode + Instruction.

Another Example -

In this example we use the same ASN.1 spec as above. A valid selective decode - instruction is:

+

In this example, the same ASN.1 specification as in Section + Writing an Exclusive Decode Instruction + is used. The following is a valid selective decode instruction:

 {selective_decode,
     {'GUI',
@@ -404,16 +430,17 @@ List_Selector = [integer()]
actions, possibleActions, [1], - handle,number]}]}}. - -

The first Decode_Instruction, + handle,number]}]}}. +

The first instruction, {selected_decode_Window1,['Window',status,buttonList,[1],number]} - is commented in the previous section. The instruction - {selected_decode_Action,['Action',handle,number]} picks - the component number in the handle component of the type - Action. If we have the value ValAction = {'Action',17,{'Button',4711,false}} the internal value 4711 - should be picked by selected_decode_Action. In an Erlang - terminal it looks like:

+ is described in the previous section.

+

The second instruction, + {selected_decode_Action,['Action',handle,number]}, takes + component number in the handle component of type + Action. If the value is + ValAction = {'Action',17,{'Button',4711,false}}, the internal + value 4711 is to be picked by selected_decode_Action. In an + Erlang terminal it looks as follows:

 ValAction = {'Action',17,{'Button',4711,false}}.
 {'Action',17,{'Button',4711,false}}
@@ -423,44 +450,41 @@ ValAction = {'Action',17,{'Button',4711,false}}.
 <<48,18,2,1,17,160,13,172,11,171,9,48,7,128,2,18,103,129,1,0>>
 9> 'GUI':selected_decode_Action(BinBytes).
 {ok,4711}
-10>
+10>

The third instruction, ['Window',status,actions,possibleActions,[1],handle,number], - which is a little more complicated,

+ works as follows:

- starts with type Window. - Picks component status of Window that is - of type Status. - Then takes component actions of type + Step 1: Starts with type Window. + Step 2: Takes component status of Window + that is of type Status. + Step 3: Takes actions of type Status. - Then possibleActions of the internal defined - CHOICE type. - Thereafter it goes into the first component of the - SEQUENCE OF by [1]. That component is of type - Action. - The instruction next picks component - handle. - And finally component number of the type + Step 4: Takes possibleActions of the internally + defined CHOICE type. + Step 5: Goes into the first component of + SEQUENCE OF by [1]. That component is of type + Action. + Step 6: Takes component handle. + Step 7: Takes component number of type Button. -

The following figures shows which components are in the - TypeList - ['Window',status,actions,possibleActions,[1],handle,number]. And - which part of a message that will be decoded by - selected_decode_Window2. -

+

The following figure shows which components are in TypeList + ['Window',status,actions,possibleActions,[1],handle,number]:

- The elements specified in the config file for selective decode of a sub-value in a Window message + Elements Specified in Configuration File for Selective Decode of a Subvalue in a Window Message +

In the following figure, only the marked element is decoded by + selected_decode_Window2:

- Figure symbolizes the bytes of a Window:status message. Only the marked element is decoded when selected_decode_Window2 is called. + Bytes of a Window:status Message -

With the following example you can examine that both +

With the following example, you can examine that both selected_decode_Window2 and - selected_decode_Window1 decodes the intended sub-value - of the value Val

+ selected_decode_Window1 decodes the intended subvalue + of value Val:

 1> Val = {'Window',{status,{'Status',12,
                     [{'Button',13,true},
@@ -478,8 +502,8 @@ ValAction = {'Action',17,{'Button',4711,false}}.
 4> 'GUI':selected_decode_Window1(Bin).
 {ok,13}
 5> 'GUI':selected_decode_Window2(Bin).
-{ok,18}
-

Observe that the value feed into the selective decode +{ok,18} +

Notice that the value fed into the selective decode functions must be a binary.

@@ -489,19 +513,19 @@ ValAction = {'Action',17,{'Button',4711,false}}. Performance

To give an indication on the possible performance gain using the specialized decodes, some measures have been performed. The - relative figures in the outcome between selective, exclusive and - complete decode (the normal case) depends on the structure of - the type, the size of the message and on what level the + relative figures in the outcome between selective, exclusive, and + complete decode (the normal case) depend on the structure of + the type, the size of the message, and on what level the selective and exclusive decodes are specified.

- ASN.1 Specifications, Messages and Configuration -

The specs GUI and + ASN.1 Specifications, Messages, and Configuration +

The specifications GUI and MEDIA-GATEWAY-CONTROL - was used in the test. + were used in the test.

-

For the GUI spec the configuration looked like:

+

For the GUI specification the configuration was as follows:

 {selective_decode,
   {'GUI',
@@ -523,9 +547,8 @@ ValAction = {'Action',17,{'Button',4711,false}}.
                 ['Window',
                  [{status,
                      [{buttonList,parts},
-                      {actions,undecoded}]}]]}]}}.
-
-

The MEDIA-GATEWAY-CONTROL configuration was:

+ {actions,undecoded}]}]]}]}}. +

The MEDIA-GATEWAY-CONTROL configuration was as follows:

 {exclusive_decode,
   {'MEDIA-GATEWAY-CONTROL',
@@ -538,9 +561,8 @@ ValAction = {'Action',17,{'Button',4711,false}}.
 {selective_decode,
   {'MEDIA-GATEWAY-CONTROL',
     [{decode_MegacoMessage_selective,
-         ['MegacoMessage',mess,version]}]}}.
-
-

The corresponding values were:

+ ['MegacoMessage',mess,version]}]}}. +

The corresponding values were as follows:

 {'Window',{status,{'Status',12,
               [{'Button',13,true},
@@ -649,177 +671,178 @@ ValAction = {'Action',17,{'Button',4711,false}}.
                 {'StatisticsParameter',[0,11,0,3],[[52,53,49,48,48]]},
                 {'StatisticsParameter',[0,12,0,6],[[48,46,50]]},
                 {'StatisticsParameter',[0,12,0,7],[[50,48]]},
-                {'StatisticsParameter',[0,12,0,8],[[52,48]]}]}]}}}]}]}}}]}}}      
-
-

The size of the encoded values was 458 bytes for GUI and 464 - bytes for MEDIA-GATEWAY-CONTROL. + {'StatisticsParameter',[0,12,0,8],[[52,48]]}]}]}}}]}]}}}]}}} +

The size of the encoded values was 458 bytes for GUI and 464 + bytes for MEDIA-GATEWAY-CONTROL.

Results -

The ASN.1 specs in the test are compiled with the options - ber_bin, optimize, driver and asn1config. If the - driver option had been omitted there should have been +

The ASN.1 specifications in the test were compiled with options + ber_bin, optimize, driver and asn1config. Omitting + option driver gives higher values for decode and decode_part. These tests have - not been re-run using nifs, but are expected to perform about 5% better + not been rerun using NIFs, but are expected to perform about 5% better than the linked-in driver.

The test program runs 10000 decodes on the value, resulting - in a printout with the elapsed time in microseconds for the + in an output with the elapsed time in microseconds for the total number of decodes.

Function - Time(microseconds) - Kind of Decode - ASN.1 spec - % of time vs. complete decode + Time (microseconds) + Decode Type + ASN.1 Specification + % of Time versus Complete Decode decode_MegacoMessage_selective/1 374045 - selective + Selective MEDIA-GATEWAY-CONTROL 8.3 decode_MegacoMessage_exclusive/1 621107 - exclusive + Exclusive MEDIA-GATEWAY-CONTROL 13.8 decode/2 4507457 - complete + Complete MEDIA-GATEWAY-CONTROL 100 selected_decode_Window1/1 449585 - selective + Selective GUI 7.6 selected_decode_Window2/1 890666 - selective + Selective GUI 15.1 decode_Window_status_exclusive/1 1251878 - exclusive + Exclusive GUI 21.3 decode/2 5889197 - complete + Complete GUI 100 - Results of complete, exclusive and selective decode + Results of Complete, Exclusive, and Selective Decode
-

Another interesting question is what the relation is between +

It is also of interest to know the relation is between a complete decode, an exclusive decode followed by - decode_part of the excluded parts and a selective decode - followed by a complete decode. Some situations may be compared to - this simulation, e.g. inspect a sub-value and later on look at + decode_part of the excluded parts, and a selective decode + followed by a complete decode. Some situations can be compared to + this simulation, for example, inspect a subvalue and later inspect the entire value. The following table shows figures from this - test. The number of loops and time unit is the same as in the + test. The number of loops and the time unit are the same as in the previous test.

Actions Function     - Time(microseconds) - ASN.1 spec - % of time vs. complete decode + Time (microseconds) + ASN.1 Specification + % of Time vs. Complete Decode - complete + Complete decode/2 4507457 MEDIA-GATEWAY-CONTROL 100 - selective and complete + Selective and Complete decode_­MegacoMessage_­selective/1 4881502 MEDIA-GATEWAY-CONTROL 108.3 - exclusive and decode_part + Exclusive and decode_part decode_­MegacoMessage_­exclusive/1 5481034 MEDIA-GATEWAY-CONTROL 112.3 - complete + Complete decode/2 5889197 GUI 100 - selective and complete + Selective and Complete selected_­decode_­Window1/1 6337636 GUI 107.6 - selective and complete + Selective and Complete selected_­decode_­Window2/1 6795319 GUI 115.4 - exclusive and decode_part + Exclusive and decode_part decode_­Window_­status_­exclusive/1 6249200 GUI 106.1 - Results of complete, exclusive + decode_part and selective + complete decodes + Results of Complete, Exclusive + decode_part, and Selective + complete decodes

Other ASN.1 types and values can differ much from these - figures. Therefore it is important that you, in every case where + figures. It is therefore important that you, in every case where you intend to use either of these decodes, perform some tests - that shows if you will benefit your purpose. + that show if you will benefit your purpose.

- Comments -

Generally speaking the gain of selective and exclusive decode - in advance of complete decode is greater the bigger value and the - less deep in the structure you have to decode. One should also - prefer selective decode instead of exclusive decode if you are - interested in just one single sub-value.

-

Another observation is that the exclusive decode followed by - decode_part decodes is very attractive if the parts will be sent - to different servers for decoding or if one in some cases not is - interested in all parts.

-

The fastest selective decode are when the decoded type is a + Final Remarks + + The gain of using selective and exclusive decode instead of a + complete decode is greater the bigger the value and the + less deep in the structure you have to decode. + Use selective decode instead of exclusive decode if you are + interested in only a single subvalue. + Exclusive decode followed by + decode_part decodes is attractive if the parts are sent + to different servers for decoding, or if you in some cases are not + interested in all parts. + The fastest selective decode is when the decoded type is a primitive type and not so deep in the structure of the top - type. The selected_decode_Window2 decodes a big constructed - value, which explains why this operation is relatively slow.

-

It may vary from case to case which combination of - selective/complete decode or exclusive/part decode is the fastest.

+ type. selected_decode_Window2 decodes a high constructed + value, which explains why this operation is relatively slow. + It can vary from case to case which combination of + selective/complete decode or exclusive/part decode is the fastest. +
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml deleted file mode 100644 index 8b33497dd3..0000000000 --- a/lib/asn1/doc/src/asn1_ug.xml +++ /dev/null @@ -1,1417 +0,0 @@ - - - - -
- - 19972013 - Ericsson AB. All Rights Reserved. - - - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. - - - - Asn1 - Kenneth Lundin - - 1999-03-25 - D - asn1_ug.xml -
- -
- Introduction - -
- Features -

The Asn1 application provides:

- - 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. - Run-time functions used by the generated code. - Support for the following encoding rules: - - - Basic Encoding Rules (BER) - - - Distinguished Encoding Rules (DER), a specialized - form of BER that is used in security-conscious - applications. - - - Packed Encoding Rules (PER); both the aligned and - unaligned variant. - - - - -
- -
- Overview -

ASN.1 (Abstract Syntax Notation One) 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 any type of communication - channel. This way, two applications written in different - programming languages running on different computers with - different internal representation of data can exchange instances - of structured data types.

-
- -
- Prerequisites -

It is assumed that the reader is familiar with the ASN.1 - notation as documented in the standard definition [] which is the primary text. It may also be - helpful, but not necessary, to read the standard definitions - [] [] [] [] [].

-

A good book explaining those reference texts is - [], which is free to download at - http://www.oss.com/asn1/dubuisson.html. -

-
- -
- Capabilities -

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 were introduced. The following features - of the 2002 edition are fully or partly supported as shown - below:

- - -

Decimal notation (e.g., "1.5e3") for REAL values. The - NR1, NR2 and NR3 formats as explained in ISO6093 are - supported.

- - -

The RELATIVE-OID type for relative object identifiers is - fully supported.

- - -

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.

- - -

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.

- - -

Multiple-line comments as in C, /* ... */, are - supported.

- - -
- -
- -
- Getting Started with Asn1 - -
- A First Example -

The following example demonstrates the basic functionality used to run - the Erlang ASN.1 compiler.

-

Create a file called People.asn containing the following:

- 
-People DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-  Person ::= SEQUENCE {
-    name PrintableString,
-    location INTEGER {home(0),field(1),roving(2)},
-    age INTEGER OPTIONAL
-  }
-END
-

This file (People.asn) 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. -

-

The generated Erlang files will be placed in the current directory or - in the directory specified with the {outdir,Dir} option. - The following shows how the compiler - can be called from the Erlang shell:

- 
-1> asn1ct:compile("People", [ber]).
-ok
-2>
- -

The verbose option can be given to have information - about the generated files printed:

- 
-2> asn1ct:compile("People", [ber,verbose]).
-Erlang ASN.1 compiling "People.asn" 
---{generated,"People.asn1db"}--
---{generated,"People.hrl"}--
---{generated,"People.erl"}--
-ok
-3>
- -

The ASN.1 module People is now accepted and the - abstract syntax tree is saved in the People.asn1db file; - the generated Erlang code is compiled using the Erlang compiler - and loaded into the Erlang run-time system. Now there is an API - for encode/2 and decode/2 in the module - People, which is invoked by:

- , )]]> -

- or

-, )]]>

- -

Assume there is a network - application which receives instances of the ASN.1 defined - type Person, modifies and sends them back again:

- -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, -

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 - 'People':decode('Person',Bytes) which returned - an Erlang value of the ASN.1 type Person. Then an answer was - constructed and encoded using - 'People':encode('Person',Answer) which takes an - instance of a defined ASN.1 type and transforms it to a - binary according to the BER or PER encoding rules. -

-The encoder and the decoder can also be run from - the shell.

- 
-2> Rockstar = {'Person',"Some Name",roving,50}.
-{'Person',"Some Name",roving,50}
-3> {ok,Bin} = 'People':encode('Person',Rockstar).
-{ok,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
-      2,1,50>>}
-4> {ok,Person} = 'People':decode('Person',Bin).
-{ok,{'Person',"Some Name",roving,50}}
-5>
-
- -
- Module dependencies -

It is common that ASN.1 modules import defined types, values and - other entities from another ASN.1 module.

-

Earlier versions of the ASN.1 compiler required that modules that - were imported from had to be compiled before the module that - imported. This caused problems when ASN.1 modules had circular - dependencies.

-

Referenced modules are now 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.

-
-
- -
- The Asn1 Application User Interface -

The Asn1 application provides two separate user interfaces:

- - -

The module asn1ct which provides the compile-time functions - (including the compiler).

- - -

The module asn1rt_nif which provides the run-time functions - for the ASN.1 decoder for the BER back-end.

- - -

The reason for the division of the interface into compile-time - and run-time - is that only run-time modules (asn1rt*) need to be loaded in - an embedded system. -

- -
- Compile-time Functions -

The ASN.1 compiler can be invoked directly from the command-line - by means of the erlc 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 erlc command can be used to invoke the - ASN.1 compiler:

- 
-erlc Person.asn
-erlc -bper Person.asn
-erlc -bber ../Example.asn
-erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
-

The useful options for the ASN.1 compiler are:

- - -b[ber | per | uper] - -

Choice of encoding rules, if omitted ber is the - default.

- - -o OutDirectory - -

Where to put the generated files, default is the current - directory.

- - -I IncludeDir - -

Where to search for .asn1db files and ASN.1 - 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.

- - +der - -

DER encoding rule. Only when using -ber option.

- - +asn1config - -

This functionality works together with the - ber option. It enables the - specialized decodes, see the Specialized Decode chapter. -

- - +undec_rest - -

A buffer that holds a message being decoded may also have - trailing bytes. If those trailing bytes are important they - can be returned along with the decoded value by compiling - the ASN.1 specification with the +undec_rest option. - The return value from the decoder will be - {ok,Value,Rest} where Rest is a binary - containing the trailing bytes.

- - +'Any Erlc Option' - -

You may add any option to the Erlang compiler when - compiling the generated Erlang files. Any option - unrecognized by the ASN.1 compiler will be passed to the - Erlang compiler.

- - -

For a complete description of erlc see Erts Reference Manual.

-

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 - the Asn1 Reference Manual, the - asn1ct module.

-

The compiler is invoked by using asn1ct:compile/1 with - default options, or asn1ct:compile/2 if explicit options - are given. - Example:

- 
-asn1ct:compile("H323-MESSAGES.asn1").
-

which equals:

- 
-asn1ct:compile("H323-MESSAGES.asn1",[ber]).
-

If one wants PER encoding:

- 
-asn1ct:compile("H323-MESSAGES.asn1",[per]).
-

The generic encode and decode functions can be invoked like this:

- 
-'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
-'H323-MESSAGES':decode('SomeChoiceType',Bytes).
-
- -
- Run-time Functions -

When an ASN.1 specification is compiled with the ber - option, the module asn1rt_nif module and the NIF library in - asn1/priv_dir will be needed at run-time.

-

By invoking the function info/0 in a generated module, one - gets information about which compiler options were used.

-
- -
- Errors -

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.

-

The run-time encoders and decoders execute within a catch and - returns {ok, Data} or - {error, {asn1, Description}} where - Description is - an Erlang term describing the error.

-
-
- -
- - Multi-file Compilation -

There are various reasons for using multi-file compilation:

- - You want to choose the name for the generated module, - perhaps because you need to compile the same specs for - different encoding rules. - You want only one resulting module. - -

You need to specify which ASN.1 specs you will - compile in a module that must have the extension - .set.asn. You chose name of the module and provide the - names of the ASN.1 specs. For instance, if you have the specs - File1.asn, File2.asn and File3.asn your - module MyModule.set.asn will look like:

- 
-File1.asn
-File2.asn
-File3.asn
-

If you compile with:

- -~> erlc MyModule.set.asn -

the result will be one merged module MyModule.erl with - the generated code from the three ASN.1 specs. -

-
- -
- A quick note about tags - -

Tags used to be important for all users of ASN.1, because it - was necessary to manually add tags to certain constructs in order - for the ASN.1 specification to be valid. Here is an example of - an old-style specification:

- - 
-Tags DEFINITIONS ::=
-BEGIN
-  Afters ::= CHOICE { cheese [0] IA5String,
-                      dessert [1] IA5String }
-END
- -

Without the tags (the numbers in square brackets) the ASN.1 - compiler would refuse to compile the file.

- -

In 1994 the global tagging mode AUTOMATIC TAGS was introduced. - By putting AUTOMATIC TAGS in the module header, the ASN.1 compiler - will automatically add tags when needed. Here is the same - specification in AUTOMATIC TAGS mode:

- - 
-Tags DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-  Afters ::= CHOICE { cheese IA5String,
-                      dessert IA5String }
-END
-
- -

Tags will not be mentioned any more in this manual.

-
- -
- - The ASN.1 Types -

This section describes the ASN.1 types including their - functionality, purpose and how values are assigned in Erlang. -

-

ASN.1 has both primitive and constructed types:

-

- - - Primitive types - Constructed types - - - BOOLEAN - SEQUENCE - - - INTEGER - SET - - - REAL - CHOICE - - - NULL - SET OF and SEQUENCE OF - - - ENUMERATED - ANY - - - BIT STRING - ANY DEFINED BY - - - OCTET STRING - EXTERNAL - - - Character Strings - EMBEDDED PDV - - - OBJECT IDENTIFIER - CHARACTER STRING - - - Object Descriptor - - - - The TIME types - - - The supported ASN.1 types -
- - -

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.

- - 
-Operational ::= BOOLEAN --ASN.1 definition
-

In Erlang code it may look like:

- 
-Val = true,
-{ok,Bytes} = MyModule:encode('Operational', Val),
-

Below follows a description of how - values of each type can be represented in Erlang. -

- -
- - BOOLEAN -

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.

- - In ASN.1 it is possible to have:

- 
-Operational ::= BOOLEAN
-
-

Assigning a value to the type Operational in Erlang is possible by - using the following Erlang code:

- -Myvar1 = true, - -

Thus, in Erlang the atoms true and false are used - to encode a boolean value.

-
- -
- - INTEGER -

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.

-

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 []. A variety - of syntaxes are allowed when defining a type as an integer:

- 
-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)}
-
-

The Erlang representation of an ASN.1 INTEGER is an integer or - an atom if a so called Named Number List (see T6 above) - is specified.

-

Below is an example of Erlang code which assigns values for the - above types:

- 
-T1value = 0,
-T2value = 6,
-T6value1 = blue,
-T6value2 = 0,
-T6value3 = white
-
-

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.

-

The decoder will return an atom if the value corresponds to a - symbol in the Named Number List.

-
- -
- - REAL -

The following ASN.1 type is used for real numbers:

- 
-R1 ::= REAL
-
-

It can be assigned a value in Erlang as:

- 
-R1value1 = "2.14",
-R1value2 = {256,10,-2},
-
-

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 - {Mantissa,Base,Exponent} i.e. Mantissa * Base^Exponent.

-
- -
- - NULL -

Null is suitable in cases where supply and recognition of a value - is important but the actual value is not.

- 
-Notype ::= NULL
-
-

The NULL type can be assigned in Erlang:

- 
-N1 = 'NULL',
-
-

The actual value is the quoted atom 'NULL'.

-
- -
- - ENUMERATED -

The enumerated type can be used, when the value we wish to - describe, may only take one of a set of predefined values.

- 
-DaysOfTheWeek ::= ENUMERATED { 
-    sunday(1),monday(2),tuesday(3),
-    wednesday(4),thursday(5),friday(6),saturday(7) }
-
-

For example to assign a weekday value in Erlang use the same atom - as in the Enumerations of the type definition:

- 
-Day1 = saturday,
-
-

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.

-
- -
- - BIT STRING -

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.

- - In ASN.1 BIT STRING definitions may look like: -

- 
-Bits1 ::= BIT STRING
-Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
-
-

There are two notations available for representation of - BIT STRING values in Erlang and as input to the encode functions.

- - A bitstring. By default, a BIT STRING with no - symbolic names will be decoded to an Erlang bitstring. - A list of atoms corresponding to atoms in the NamedBitList - in the BIT STRING definition. A BIT STRING with symbolic - names will always be decoded to this format. - -

Example:

- 
-Bits1Val1 = <<0:1,1:1,0:1,1:1,1:1>>,
-Bits2Val1 = [gnu,punk],
-Bits2Val2 = <<2#1110:4>>,
-Bits2Val3 = [bar,gnu,gnome],
-
-

Bits2Val2 and Bits2Val3 above denote the same value.

-

Bits2Val1 is assigned symbolic values. The assignment means - that the bits corresponding to gnu and punk 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.

-

BIT STRINGS may also be sub-typed with, for example, a SIZE - specification:

- 
-Bits3 ::= BIT STRING (SIZE(0..31))
-

This means that no bit higher than 31 can ever be set.

- -
- Deprecated representations for BIT STRING -

In addition to the representations described above, the - following deprecated representations are available if the - specification has been compiled with the - legacy_erlang_types option:

- - A list of binary digits (0 or 1). This format is - accepted as input to the encode functions, and a BIT STRING - will be decoded to this format if the - legacy_bit_string option has been given. - - As {Unused,Binary} where Unused denotes - how many trailing zero-bits 0 to 7 that are unused in the - least significant byte in Binary. This format is - accepted as input to the encode functions, and a BIT - STRING will be decoded to this format if - compact_bit_string has been given. - - A hexadecimal number (or an integer). This format - should be avoided, since it is easy to misinterpret a BIT - STRING value in this format. - - -
-
- -
- - OCTET STRING -

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.

-

It is possible to have the following ASN.1 type definitions:

- 
-O1 ::= OCTET STRING
-O2 ::= OCTET STRING (SIZE(28))
-

With the following example assignments in Erlang:

- 
-O1Val = <<17,13,19,20,0,0,255,254>>,
-O2Val = <<"must be exactly 28 chars....">>,
-

By default, an OCTET STRING is always represented as - an Erlang binary. If the specification has been compiled with - the legacy_erlang_types option, the encode functions - will accept both lists and binaries, and the decode functions - will decode an OCTET STRING to a list.

-
- -
- - Character Strings -

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.

-

However, when using for instance the IA5String (which closely - resembles ASCII) the byte 65 (in decimal - notation) means the character 'A'. -

-

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. -

-

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. -

-

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. -

-

Here are some examples:

- 
-Digs ::= NumericString (SIZE(1..3))
-TextFile ::= IA5String (SIZE(0..64000))
-

with corresponding Erlang assignments:

- 
-DigsVal1 = "456",
-DigsVal2 = "123",
-TextFileVal1 = "abc...xyz...",
-TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
-

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. We have the following - specification in the file PrimStrings.asn1.

- 
-PrimStrings DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-   BMP ::= BMPString
-END
-
- -

Encoding and decoding some strings:

- - 
-1> asn1ct:compile('PrimStrings', [ber]).
-ok
-2> {ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).
-{ok,<<30,4,53,54,45,56>>}
-3> 'PrimStrings':decode('BMP', Bytes1).
-{ok,[{0,0,53,53},{0,0,45,56}]}
-4> {ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).
-{ok,<<30,4,53,53,0,65>>}
-5> 'PrimStrings':decode('BMP', Bytes2).
-{ok,[{0,0,53,53},65]}
-6> {ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").
-{ok,<<30,20,0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103>>}
-7> 'PrimStrings':decode('BMP', Bytes3).
-{ok,"BMP string"}
- -

The UTF8String type is represented as a UTF-8 encoded binary in - Erlang. Such binaries can be created directly using the binary syntax - or by converting from a list of Unicode code points using the - unicode:characters_to_binary/1 function.

- -

Here are some examples showing how UTF-8 encoded binaries can - be created and manipulated:

- - 
-1> Gs = "Мой маленький Гном".
-[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
- 1081,32,1043,1085,1086,1084]
-2> Gbin = unicode:characters_to_binary(Gs).
-<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
-  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
-  208,...>>
-3> Gbin = <<"Мой маленький Гном"/utf8>>.
-<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
-  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
-  208,...>>
-4> Gs = unicode:characters_to_list(Gbin).
-[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
- 1081,32,1043,1085,1086,1084]
-
- -

See the unicode module - for more details.

- -

In the following example we will use this ASN.1 specification:

- 
-UTF DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-   UTF ::= UTF8String
-END
-
- -

Encoding and decoding a string with Unicode characters:

- - 
-5> asn1ct:compile('UTF', [ber]).
-ok
-6> {ok,Bytes1} = 'UTF':encode('UTF', <<"Гном"/utf8>>).
-{ok,<<12,8,208,147,208,189,208,190,208,188>>}
-7> {ok,Bin1} = 'UTF':decode('UTF', Bytes1).
-{ok,<<208,147,208,189,208,190,208,188>>}
-8> io:format("~ts\n", [Bin1]).
-Гном
-ok
-9> unicode:characters_to_list(Bin1).
-[1043,1085,1086,1084]
-
-
- -
- - OBJECT IDENTIFIER -

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:

- 
-Oid ::= OBJECT IDENTIFIER
-
-

Therefore, the example below is a valid Erlang instance of the - type 'Oid'.

- 
-OidVal1 = {1,2,55},
-
-

The OBJECT IDENTIFIER value is simply a tuple with the - consecutive values which must be integers. -

-

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. -

-

The OBJECT IDENTIFIER is a very important type and it is - widely used within different standards to uniquely identify - various objects. In [], there is an - easy-to-understand description of the usage of - OBJECT IDENTIFIER.

-

-
- -
- - Object Descriptor -

Values of this type can be assigned a value as an ordinary string - like this:

- - 
-      "This is the value of an Object descriptor"
-
- -
- - The TIME Types -

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".

-

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.

-
- -
- - SEQUENCE -

The structured types of ASN.1 are constructed from other types - in a manner similar to the concepts of array and struct in C. -

- A SEQUENCE in ASN.1 is - comparable with a struct in C and a record in Erlang. - A SEQUENCE may be defined as:

- 
-Pdu ::= SEQUENCE {
-   a INTEGER,
-   b REAL,
-   c OBJECT IDENTIFIER,
-   d NULL }
-

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 SET in an ASN.1 module an Erlang - record declaration is generated. For Pdu above, a record - like this is defined:

- 
--record('Pdu',{a, b, c, d}).
-

The record declarations for a module M are placed in a - separate M.hrl file.

-

Values can be assigned in Erlang as shown below:

- 
-MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}.
-

The decode functions will return a record as result when decoding - a SEQUENCE or a SET.

- -

A SEQUENCE and a SET may contain a component - with a DEFAULT key word followed by the actual value that - is the default value. The DEFAULT keyword means that the - application doing the encoding can omit encoding of the value, - thus resulting in fewer bytes to send to the receiving - application.

- -

An application can use the atom asn1_DEFAULT to indicate - that the encoding should be omitted for that position in - the SEQUENCE.

- -

Depending on the encoding rules, the encoder may also compare - the given value to the default value and automatically omit the - encoding if they are equal. How much effort the encoder makes to - to compare the values depends on the encoding rules. The DER - encoding rules forbids encoding a value equal to the default value, - so it has a more thorough and time-consuming comparison than the - encoders for the other encoding rules.

- -

In the following example we will use this ASN.1 specification:

- 
-File DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-Seq1 ::= SEQUENCE {
-    a INTEGER DEFAULT 1,
-    b Seq2 DEFAULT {aa TRUE, bb 15}
-}
-
-Seq2 ::= SEQUENCE {
-    aa BOOLEAN,
-    bb INTEGER
-}
-
-Seq3 ::= SEQUENCE {
-    bs BIT STRING {a(0), b(1), c(2)} DEFAULT {a, c}
-}
-END
-

Here is an example where the BER encoder is able to omit encoding - of the default values:

- 
-1> asn1ct:compile('File', [ber]).
-ok
-2> 'File':encode('Seq1', {'Seq1',asn1_DEFAULT,asn1_DEFAULT}).
-{ok,<<48,0>>}
-3> 'File':encode('Seq1', {'Seq1',1,{'Seq2',true,15}}).
-{ok,<<48,0>>}
- -

And here is an example with a named BIT STRING where the BER - encoder will not omit the encoding:

- 
-4> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT).
-{ok,<<48,0>>}
-5> 'File':encode('Seq3', {'Seq3',<<16#101:3>>).
-{ok,<<48,4,128,2,5,160>>}
- -

The DER encoder will omit the encoding for the same BIT STRING:

- 
-6> asn1ct:compile('File', [ber,der]).
-ok
-7> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT).
-{ok,<<48,0>>}
-8> 'File':encode('Seq3', {'Seq3',<<16#101:3>>).
-{ok,<<48,0>>}
-
- -
- - SET -

In Erlang, the SET type is used exactly as SEQUENCE. Note - that if the BER or DER encoding rules are used, decoding a - SET is slower than decoding a SEQUENCE because the components - must be sorted.

-
- -
- Notes about extensibility for SEQUENCE and SET -

When a SEQUENCE or SET contains an extension marker and - extension components like this:

- 
-SExt ::= SEQUENCE {
-           a INTEGER,
-           ...,
-           b BOOLEAN }
-
-

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 b. Thus, incoming messages that will be decoded - may have more or fever components than this one. -

-

The component b 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. -

-

During decoding the b field of the record will get the decoded - value of the b - component if present and otherwise the value asn1_NOVALUE.

-
- -
- - CHOICE -

The CHOICE type is a space saver and is similar to the concept of a - 'union' in the C language.

-

Assume:

- 
-SomeModuleName DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-T ::= CHOICE {
-        x REAL,
-        y INTEGER,
-        z OBJECT IDENTIFIER }
-END
-

It is then possible to assign values:

- 
-TVal1 = {y,17},
-TVal2 = {z,{0,1,2}},
-
-

A CHOICE value is always represented as the tuple - {ChoiceAlternative, Val} where ChoiceAlternative - is an atom denoting the selected choice alternative. -

- -
- Extensible CHOICE -

When a CHOICE contains an extension marker and the decoder detects - an unknown alternative of the CHOICE the value is represented as:

- 
-{asn1_ExtAlt, BytesForOpenType}
-
-

Where BytesForOpenType is a list of bytes constituting the - encoding of the "unknown" CHOICE alternative.

-
-
- -
- - SET OF and SEQUENCE OF -

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:

- 
-Arr1 ::= SET SIZE (5) OF INTEGER (4..9) 
-Arr2 ::= SEQUENCE OF OCTET STRING
-

We may have the following in Erlang:

- 
-Arr1Val = [4,5,6,7,8],
-Arr2Val = ["abc",[14,34,54],"Octets"],
-

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.

-

However, in case of a value of the type SET OF, 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 SEQUENCE OF instead of SET OF if it is possible.

-
- -
- - ANY and ANY DEFINED BY -

The types ANY and ANY DEFINED BY 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.

-

A value of this type is encoded as an open type.

-

Instead of ANY/ANY DEFINED BY one should use - information object class, table constraints and - parameterization. In particular the construct - TYPE-IDENTIFIER.@Type accomplish the same as the - deprecated ANY.

-

See also Information object

-
- -
- - EXTERNAL, EMBEDDED PDV and CHARACTER STRING -

These types are used in presentation layer negotiation. They are - encoded according to their associated type, see [].

-

The EXTERNAL type had a slightly different associated type - before 1994. [] 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 - EXTERNAL type values of either format for encoding. Decoded - values are always returned on the newer format.

-
- -
- Embedded Named Types -

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 - #'T'{'C'=Value}. - Where Value may be a value of yet another type T2.

-

For example:

- 
-EmbeddedExample DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-B ::= SEQUENCE {
-        a Arr1,
-        b T }
-
-Arr1 ::= SET SIZE (5) OF INTEGER (4..9) 
-
-T ::= CHOICE {
-        x REAL,
-        y INTEGER,
-        z OBJECT IDENTIFIER }
-        END
-

The SEQUENCE b can be encoded like this in Erlang:

- 
-1> 'EmbeddedExample':encode('B', {'B',[4,5,6,7,8],{x,"7.77"}}).
-{ok,<<5,56,0,8,3,55,55,55,46,69,45,50>>}
-
-
- -
- Naming of Records in .hrl Files -

When an ASN.1 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.

-

Though there are some special cases of this functionality that - are presented below.

- -
- Embedded Structured Types -

It is also possible in ASN.1 to have components that are themselves - structured types. - For example, it is possible to have:

- 
-Emb ::= SEQUENCE {
-    a SEQUENCE OF OCTET STRING,
-    b SET {
-       a INTEGER,
-       b INTEGER DEFAULT 66},
-    c CHOICE {
-       a INTEGER,
-       b FooType } }
-
-FooType ::= [3] VisibleString
-

The following records are generated because of the type Emb:

- 
--record('Emb,{a, b, c}).
--record('Emb_b',{a, b = asn1_DEFAULT}). % the embedded SET type
-
-

Values of the Emb type can be assigned like this:

- -V = #'Emb'{a=["qqqq",[1,2,255]], - b = #'Emb_b'{a=99}, - c ={b,"Can you see this"}}. - -

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.

-

For example:

- 
-Seq ::= SEQUENCE{
-    a CHOICE{
-        b SEQUENCE {
-           c  INTEGER
-        }
-    }
-}
-

will result in the following record:

- 
--record('Seq_a_b',{c}).
-

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:

- 
-Seq ::= SEQUENCE {
-    a SEQUENCE OF SEQUENCE {
-           b
-               }
-    c SET OF SEQUENCE {
-           d
-               }
-}
-

This results in the records:

- 
--record('Seq_a_SEQOF'{b}).
--record('Seq_c_SETOF'{d}).
-

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 - 'Seq_b' is generated in the .hrl file and used to hold - values.

- 
-Seq ::= SEQUENCE {
-    b PType{INTEGER}
-}
-
-PType{T} ::= SEQUENCE{
-    id T
-}
-
- -
- Recursive Types -

Types may refer to themselves. Suppose:

- 
-Rec ::= CHOICE {
-     nothing NULL,
-     something SEQUENCE {
-          a INTEGER,
-          b OCTET STRING,
-          c Rec }}
-

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:

- 
-V = {something,#'Rec_something'{a = 77, 
-                                b = "some octets here", 
-                                c = {nothing,'NULL'}}}.
-
-
- -
- ASN.1 Values -

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:

- 
-TT ::= SEQUENCE {
-   a INTEGER,
-   b SET OF OCTET STRING }
-
-tt TT ::= {a 77,b {"kalle","kula"}}
-

The value defined here could be used in several ways. - Firstly, it could be used as the value in some DEFAULT component:

- 
-SS ::= SET {
-    s OBJECT IDENTIFIER,
-    val TT DEFAULT tt }
-

It could also be used from inside an Erlang program. If the above ASN.1 - code was defined in ASN.1 module Values, then the ASN.1 value - tt can be reached from Erlang as - a function call to 'Values':tt() as in the example below.

- 
-1> Val = 'Values':tt().
-{'TT',77,["kalle","kula"]}
-2> {ok,Bytes} = 'Values':encode('TT',Val).
-{ok,<<48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
-      107,117,108,97>>}
-4> 'Values':decode('TT',Bytes).
-{ok,{'TT',77,["kalle","kula"]}}
-5>
-
-

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.

-

Furthermore, there is a macro generated for each value in the .hrl - file. So, the defined value tt can also be extracted by - ?tt in application code.

-
- -
- Macros -

MACRO is not supported as the the type is no longer part of the - ASN.1 standard.

-
- -
- - ASN.1 Information Objects (X.681) -

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 []. In the following only a brief - explanation is given.

-

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:

- 
-GENERAL-PROCEDURE ::= CLASS {
-      &Message,
-      &Reply               OPTIONAL,
-      &Error               OPTIONAL,
-      &id          PrintableString UNIQUE
-}
-WITH SYNTAX {
-      NEW MESSAGE     &Message
-      [REPLY           &Reply]
-      [ERROR           &Error]
-      ADDRESS          &id
-}
-

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.

-

The object object1 is an instance of the CLASS - GENERAL-PROCEDURE and has one type field and one fixed type value - field. The object object2 also has an OPTIONAL field ERROR, - which is a type field.

- 
-object1 GENERAL-PROCEDURE ::= {
-    NEW MESSAGE      PrintableString
-    ADDRESS          "home"
-}
-
-object2 GENERAL-PROCEDURE ::= {
-    NEW MESSAGE INTEGER
-    ERROR INTEGER
-    ADDRESS "remote"
-}
-

The field ADDRESS is a UNIQUE field. Objects in an object set must - have unique values in their UNIQUE field, as in GENERAL-PROCEDURES:

- 
-GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
-    object1 | object2}
-

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 [] in ASN.1 types, as in:

- 
-StartMessage  ::= SEQUENCE {
-    msgId  GENERAL-PROCEDURE.&id  ({GENERAL-PROCEDURES}),
-    content GENERAL-PROCEDURE.&Message ({GENERAL-PROCEDURES}{@msgId}),
-    }
-

In the type StartMessage the constraint following the - content field tells that in a value of type - StartMessage the value in the content field must - come from the same object that is chosen by the msgId - field.

-

So, the value #'StartMessage'{msgId="home",content="Any Printable String"} is legal to encode as a StartMessage - value, while the value #'StartMessage'{msgId="remote", content="Some String"} 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.

-

StartMessage can in the content field be - encoded with a value of any type that an object in the - GENERAL-PROCEDURES object set has in its NEW MESSAGE field. This field refers to a type field - &Message in the class. The msgId field is always - encoded as a PrintableString, since the field refers to a fixed type - in the class.

-

In practice, object sets are usually declared to be extensible so - so that more objects can be added to the set later. Extensibility is - indicated like this:

- 
-GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
-    object1 | object2, ...}
-

When decoding a type that uses an extensible set constraint, - there is always the possibility that the value in the UNIQUE - field is unknown (i.e. the type has been encoded with a later - version of the ASN.1 specification). When that happens, the - unencoded data will be returned wrapped in a tuple like this:

- - 
-{asn1_OPENTYPE,Binary}
-

where Binary is an Erlang binary that contains the encoded - data. (If the option legacy_erlang_types has been given, - just the binary will be returned.)

-
- -
- Parameterization (X.683) -

Parameterization, which is defined in the standard [], 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.

-

When many types (or another 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.

-

One example of use of parameterization is:

- 
-General{Type} ::= SEQUENCE
-{
-     number     INTEGER,
-     string     Type
-}
-      
-T1 ::= General{PrintableString}
-
-T2 ::= General{BIT STRING}
-
-

An example of a value that can be encoded as type T1 is {12,"hello"}.

-

Note that the compiler does not generate encode/decode functions for - parameterized types, but only for the instances of the parameterized - types. Therefore, if a file contains the types General{}, T1 and T2 above, - encode/decode functions will only be generated for T1 and T2. -

-
- - diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index 32ff2d52cf..4e0bf055fc 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -35,43 +35,45 @@ ASN.1 compiler and compile-time support functions

The ASN.1 compiler takes an ASN.1 module as input and generates a - corresponding Erlang module which can encode and decode the data-types - specified. Alternatively the compiler takes a specification module - (se below) specifying all input modules and generates one module with - encode/decode functions. There are also some generic functions which - can be used in during development of applications which handles ASN.1 - data (encoded as BER or PER).

+ corresponding Erlang module, which can encode and decode the specified + data types. Alternatively, the compiler takes a specification module + specifying all input modules, and generates a module with + encode/decode functions. In addition, some generic functions + can be used during development of applications that handles ASN.1 + data (encoded as BER or PER).

+ -

By default in OTP 17, the representation of the BIT STRING - and OCTET STRING types as Erlang terms have changed. BIT - STRING values are now Erlang bitstrings and OCTET STRING values - are binaries. Also, an undecoded open type will now be wrapped in - a asn1_OPENTYPE tuple. For details see BIT STRING, OCTET STRING, and - ASN.1 Information Objects in User's Guide.

-

To revert to the old representation of the types, use the - legacy_erlang_types option.

+

By default in OTP 17, the representation of the BIT STRING + and OCTET STRING types as Erlang terms were changed. BIT + STRING values are now Erlang bit strings and OCTET STRING + values are binaries. Also, an undecoded open type is now wrapped in + an asn1_OPENTYPE tuple. For details, see BIT STRING, OCTET STRING, and + ASN.1 Information Objects in the User's Guide.

+

To revert to the old representation of the types, use option + legacy_erlang_types.

 + -

In R16, the options have been simplified. The back-end is chosen +

In OTP R16, the options were simplified. The back end is chosen using one of the options ber, per, or uper. - The options optimize, nif, and driver options - are no longer necessary (and the ASN.1 compiler will print a - warning if they are used). The options ber_bin, per_bin, - and uper_bin options will still work, but will print a warning. + Options optimize, nif, and driver options + are no longer necessary (and the ASN.1 compiler generates a + warning if they are used). Options ber_bin, per_bin, + and uper_bin options still work, but generates a warning.

-

Another change in R16 is that the generated encode/2 - function always returns a binary. - The encode/2 function for the BER back-end used to return - an iolist.

+

Another change in OTP R16 is that the generated function + encode/2 always returns a binary. Function encode/2 + for the BER back end used to return an iolist.

 + compile(Asn1module) -> ok | {error, Reason} compile(Asn1module, Options) -> ok | {error, Reason} - Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER. + Compiles an ASN.1 module and generates encode/decode functions according to encoding rules BER or PER. Asn1module = atom() | string() Options = [Option| OldOption] @@ -85,79 +87,82 @@ Prefix = string() -

Compiles the ASN.1 module Asn1module and generates an - Erlang module Asn1module.erl with encode and decode +

Compiles the ASN.1 module Asn1module and generates + an Erlang module Asn1module.erl with encode and decode functions for the types defined in Asn1module. For each - ASN.1 value defined in the module an Erlang function which + ASN.1 value defined in the module, an Erlang function that returns the value in Erlang representation is generated.

-

If Asn1module is a filename without extension first - ".asn1" is assumed, then ".asn" and finally +

If Asn1module is a filename without extension, first + ".asn1" is assumed, then ".asn", and finally ".py" (to be compatible with the old ASN.1 compiler). - Of course Asn1module can be a full pathname (relative or + Asn1module can be a full pathname (relative or absolute) including filename with (or without) extension.

-

If one wishes to compile a set of Asn1 modules into one - Erlang file with encode/decode functions one has to list all +

If it is needed to compile a set of ASN.1 modules into an + Erlang file with encode/decode functions, ensure to list all involved files in a configuration file. This configuration - file must have a double extension ".set.asn", (".asn" can - alternatively be ".asn1" or ".py"). The input files' names - must be listed, within quotation marks (""), one at each row + file must have a double extension ".set.asn" + (".asn" can alternatively be ".asn1" or ".py"). + List the input file names + within quotation marks (""), one at each row in the file. If the input files are File1.asn, - File2.asn and File3.asn the configuration file - shall look like:

+ File2.asn, and File3.asn, the configuration file + must look as follows:

 File1.asn
 File2.asn
-File3.asn
-

The output files will in this case get their names from the - configuration file. If the configuration file has the name - SetOfFiles.set.asn the name of the output files will be - SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db.

-

Sometimes in a system of ASN.1 modules there are different - default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The - multi file compilation resolves the default tagging as if +File3.asn +

The output files in this case get their names from the + configuration file. If the configuration file is named + SetOfFiles.set.asn, the names of the output files are + SetOfFiles.hrl, SetOfFiles.erl, and SetOfFiles.asn1db.

+

Sometimes in a system of ASN.1 modules, different + default tag modes, for example, AUTOMATIC, IMPLICIT, + or EXPLICIT. The + multi-file compilation resolves the default tagging as if the modules were compiled separately.

-

Another unwanted effect that may occur in multi file compilation - is name collisions. The compiler solves this problem in two - ways: If the definitions are identical then the output module - keeps only one definition with the original name. But if - definitions only have same name and differs in the definition, - then they will be renamed. The new names will be the definition - name and the original module name concatenated.

-

If any name collision have occurred the compiler reports a - "NOTICE: ..." message that tells if a definition was renamed, +

Name collisions is another unwanted effect that can occur in + multi file-compilation. The compiler solves this problem in one + of two ways:

+ + If the definitions are identical, the output module + keeps only one definition with the original name. + If the definitions have the same name and differs in the + definition, they are renamed. The new names are the definition + name and the original module name concatenated. + +

If a name collision occurs, the compiler reports a + "NOTICE: ..." message that tells if a definition was renamed, and the new name that must be used to encode/decode data.

- -

- Options is a list with options specific for the asn1 +

Options is a list with options specific for the ASN.1 compiler and options that are applied to the Erlang compiler. - The latter are those that not is recognized as asn1 specific. - Available options are: + The latter are not recognized as ASN.1 specific. The + available options are as follows:

ber | per | uper

The encoding rule to be used. The supported encoding rules - are BER (Basic Encoding Rules), - PER aligned (Packed Encoding Rules) and PER unaligned. - If the encoding rule option is omitted ber + are Basic Encoding Rules (BER), + Packed Encoding Rules (PER) aligned, and PER unaligned. + If the encoding rule option is omitted, ber is the default.

The generated Erlang module always gets the same name - as the ASN.1 module and as a consequence of this only one - encoding rule per ASN.1 module can be used at runtime. + as the ASN.1 module. Therefore, only one + encoding rule per ASN.1 module can be used at runtime.

der

- By this option the Distinguished Encoding Rules (DER) is chosen. + With this option the Distinguished Encoding Rules (DER) is chosen. DER is regarded as a specialized variant of the BER encoding - rule, therefore the der option only makes sense together - with the ber option. + rule. Therefore, this option only makes sense together + with option ber. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding. The decoding routines are the same @@ -167,118 +172,123 @@ File3.asn compact_bit_string

- The BIT STRING type will be decoded to the "compact notation". + The BIT STRING type is decoded to "compact notation". This option is not recommended for new code.

-

For details see - - BIT STRING type section in the Users Guide - . +

For details, see Section + + BIT STRING in the User's Guide.

-

This option implies the legacy_erlang_types option.

+

This option implies option legacy_erlang_types.

 legacy_bit_string

- The BIT STRING type will be decoded to the legacy - format, i.e. a list of zeroes and ones. + The BIT STRING type is decoded to the legacy + format, that is, a list of zeroes and ones. This option is not recommended for new code.

-

For details see - - BIT STRING type section in the Users Guide - . -

This option implies the legacy_erlang_types option.

-

+

For details, see Section + BIT STRING + in the User's Guide

+

This option implies option legacy_erlang_types.

 legacy_erlang_types -

Use the same Erlang types to represent BIT STRING and - OCTET STRING as in R16. For details see BIT STRING and - OCTET - STRING in User's Guide.

-

This option is not recommended for - new code.

+

Use the same Erlang types to represent BIT STRING and + OCTET STRING as in OTP R16.

+

For details, see Section BIT STRING and Section + OCTET + STRING in the User's Guide.

+

This option is not recommended for new code.

 {n2n, EnumTypeName}

- Tells the compiler to generate functions for conversion between - names (as atoms) and numbers and vice versa for the EnumTypeName specified. There can be multiple occurrences of this option in order to specify several type names. The type names must be declared as ENUMERATIONS in the ASN.1 spec. - If the EnumTypeName does not exist in the ASN.1 spec the - compilation will stop with an error code. - The generated conversion functions are named + Tells the compiler to generate functions for conversion + between names (as atoms) and numbers and conversely for + the specified EnumTypeName. There can be multiple + occurrences of this option to specify several type names. + The type names must be declared as ENUMERATIONS in + the ASN.1 specification.

+

+ If EnumTypeName does not exist in the ASN.1 specification, + the compilation stops with an error code.

+

+ The generated conversion functions are named name2num_EnumTypeName/1 and num2name_EnumTypeName/1.

noobj -

Do not compile (i.e do not produce object code) the generated - .erl file. If this option is omitted the generated Erlang module - will be compiled.

+

Do not compile (that is, do not produce object code) the + generated .erl file. If this option is omitted, the + generated Erlang module is compiled.

 {i, IncludeDir}

Adds IncludeDir to the search-path for - .asn1db and asn1 source files. The compiler tries - to open a .asn1db file when a module imports - definitions from another ASN.1 module. If no - .asn1db file is found the asn1 source file is - parsed. Several {i, IncludeDir} can be given. + .asn1db and ASN.1 source files. The compiler + tries to open an .asn1db file when a module imports + definitions from another ASN.1 module. If no + .asn1db file is found, the ASN.1 source file is + parsed. Several {i, IncludeDir} can be given.

{outdir, Dir} -

Specifies the directory Dir where all generated files - shall be placed. If omitted the files are placed in the - current directory.

+

Specifies directory Dir where all generated files + are to be placed. If this option is omitted, the files are + placed in the current directory.

 asn1config -

When one of the specialized decodes, exclusive or - selective decode, is wanted one has to give instructions in - a configuration file. The option asn1config enables - specialized decodes and takes the configuration file, which - has the same name as the ASN.1 spec but with extension - .asn1config, in concern. +

When using one of the specialized decodes, exclusive or + selective decode, instructions must be given in + a configuration file. Option asn1config enables + specialized decodes and takes the configuration file in + concern. The configuration file has + the same name as the ASN.1 specification, but with extension + .asn1config.

-

The instructions for exclusive decode must follow the - instruction and grammar in the User's Guide. +

For instructions for exclusive decode, see Section + Exclusive + Decode in the User's Guide.

-

You can also find the instructions for selective decode - in the - User's Guide. +

For instructions for selective decode, see Section + Selective + Decode in the User's Guide.

undec_rest -

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 - {ok, Value, Rest} is returned. Rest may be a +

A buffer that holds a message, being decoded it can also + have some following bytes. Those following bytes can now + be returned together with the decoded value. If an + ASN.1 specification is compiled with this option, a tuple + {ok, Value, Rest} is returned. Rest can be a list or a binary. Earlier versions of the compiler ignored those following bytes.

 no_ok_wrapper -

If this option is given, the generated encode/2 - and decode/2 functions will not wrap a successful +

With this option, the generated encode/2 + and decode/2 functions do not wrap a successful return value in an {ok,...} tuple. If any error - occurs, there will be an exception.

+ occurs, an exception will be raised.

 {macro_name_prefix, Prefix}

All macro names generated by the compiler are prefixed with - Prefix. This is useful when multiple protocols that contains + Prefix. This is useful when multiple protocols that contain macros with identical names are included in a single module.

 {record_name_prefix, Prefix}

All record names generated by the compiler are prefixed with - Prefix. This is useful when multiple protocols that contains + Prefix. This is useful when multiple protocols that contain records with identical names are included in a single module.

 verbose @@ -291,27 +301,27 @@ File3.asn

Causes warnings to be treated as errors.

 -

Any additional option that is applied will be passed to - the final step when the generated .erl file is compiled. +

Any more option that is applied is passed to + the final step when the generated .erl file is compiled.

The compiler generates the following files:

- -

Asn1module.hrl (if any SET or SEQUENCE is defined)

+ Asn1module.hrl (if any SET or SEQUENCE + is defined) - -

Asn1module.erl the Erlang module with encode, decode and value functions.

+ Asn1module.erl - Erlang module with encode, decode, + and value functions - -

Asn1module.asn1db intermediate format used by the compiler when modules IMPORTS - definitions from each other.

+ Asn1module.asn1db - Intermediate format used by the + compiler when modules IMPORT definitions from each other. + encode(Module, Type, Value)-> {ok, Bytes} | {error, Reason} - Encode an ASN.1 value. + Encodes an ASN.1 value. Module = Type = atom() Value = term() @@ -319,11 +329,11 @@ File3.asn Reason = term() -

Encodes Value of Type defined in the ASN.1 module - Module. To get as fast execution as possible the - encode function only performs rudimentary tests that the input - Value - is a correct instance of Type. The length of strings is for example +

Encodes Value of Type defined in the ASN.1 module + Module. To get as fast execution as possible, the + encode function performs only the rudimentary tests that input + Value is a correct instance of Type. So, for example, + the length of strings is not always checked. Returns {ok, Bytes} if successful or {error, Reason} if an error occurred.

@@ -331,6 +341,7 @@ File3.asn Use Module:encode(Type, Value) instead.

 + decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason} Decode from Bytes into an ASN.1 value. @@ -346,26 +357,28 @@ File3.asn Use Module:decode(Type, Bytes) instead.

 + value(Module, Type) -> {ok, Value} | {error, Reason} - Create an ASN.1 value for test purposes. + Creates an ASN.1 value for test purposes. Module = Type = atom() Value = term() Reason = term() -

Returns an Erlang term which is an example of a valid Erlang - representation of a value of the ASN.1 type Type. The value +

Returns an Erlang term that is an example of a valid Erlang + representation of a value of the ASN.1 type Type. The value is a random value and subsequent calls to this function will for most types return different values.

 + test(Module) -> ok | {error, Reason} test(Module, Type | Options) -> ok | {error, Reason} test(Module, Type, Value | Options) -> ok | {error, Reason} - Perform a test of encode and decode for types in an ASN.1 module. + Performs a test of encode and decode for types in an ASN.1 module. Module = Type = atom() Value = term() @@ -376,9 +389,8 @@ File3.asn

Performs a test of encode and decode of types in Module. The generated functions are called by this function. This function is useful during test to secure that the generated - encode and decode functions and the general runtime support work - as expected.

- + encode and decode functions as well as the general runtime support + work as expected.

test/1 iterates over all types in Module.

@@ -390,14 +402,12 @@ File3.asn

test/3 tests type Type with Value.

 - -

Schematically the following happens for each type in the module:

+

Schematically, the following occurs for each type in the module:

{ok, Value} = asn1ct:value(Module, Type), {ok, Bytes} = asn1ct:encode(Module, Type, Value), {ok, Value} = asn1ct:decode(Module, Type, Bytes). - -

The test functions utilizes the *.asn1db files +

The test functions use the *.asn1db files for all included modules. If they are located in a different directory than the current working directory, use the include option to add paths. This is only needed when automatically diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml index 3cf56b01ca..f5c334c2ac 100644 --- a/lib/asn1/doc/src/asn1rt.xml +++ b/lib/asn1/doc/src/asn1rt.xml @@ -46,7 +46,7 @@ decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason} - Decode from bytes into an ASN.1 value. + Decodes from Bytes into an ASN.1 value. Module = Type = atom() Value = Reason = term() @@ -61,7 +61,7 @@ encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason} - Encode an ASN.1 value. + Encodes an ASN.1 value. Module = Type = atom() Value = term() @@ -69,12 +69,12 @@ Reason = term() -

Encodes Value of Type defined in the ASN.1 +

Encodes Value of Type defined in the ASN.1 module Module. Returns a binary if successful. To get - as fast execution as possible the encode function only - performs rudimentary tests that the input Value is a - correct instance of Type. The length of strings is, for - example, not always checked.

+ as fast execution as possible, the encode function performs + only the rudimentary test that input Value is a correct + instance of Type. For example, the length of strings is + not always checked.

Use Module:encode(Type, Value) instead of this function.

 @@ -88,23 +88,23 @@ Reason = term() -

info/1 returns the version of the asn1 compiler that was +

Returns the version of the ASN.1 compiler that was used to compile the module. It also returns the compiler options - that was used.

+ that were used.

Use Module:info() instead of this function.

 utf8_binary_to_list(UTF8Binary) -> {ok,UnicodeList} | {error,Reason} - Transforms an utf8 encoded binary to a unicode list. + Transforms an UTF8 encoded binary to a unicode list. UTF8Binary = binary() UnicodeList = [integer()] Reason = term() -

utf8_binary_to_list/1 Transforms a UTF8 encoded binary +

Transforms a UTF8 encoded binary to a list of integers, where each integer represents one character as its unicode value. The function fails if the binary is not a properly encoded UTF8 string.

@@ -114,14 +114,14 @@ utf8_list_to_binary(UnicodeList) -> {ok,UTF8Binary} | {error,Reason} - Transforms an unicode list ot an utf8 binary. + Transforms an unicode list to a UTF8 binary. UnicodeList = [integer()] UTF8Binary = binary() Reason = term() -

utf8_list_to_binary/1 Transforms a list of integers, +

Transforms a list of integers, where each integer represents one character as its unicode value, to a UTF8 encoded binary.

Use unicode:characters_to_binary/1 instead of this function.

diff --git a/lib/asn1/doc/src/part.xml b/lib/asn1/doc/src/part.xml index 735ec2e616..104aeb1f34 100644 --- a/lib/asn1/doc/src/part.xml +++ b/lib/asn1/doc/src/part.xml @@ -29,11 +29,14 @@ part.sgml -

The Asn1 application - contains modules with compile-time and run-time support for ASN.1. +

The ASN.1 application + contains modules with compile-time and runtime support for + Abstract Syntax Notation One (ASN.1).

- + + + diff --git a/lib/asn1/doc/src/ref_man.xml b/lib/asn1/doc/src/ref_man.xml index 0a0ed5416a..e157f542f3 100644 --- a/lib/asn1/doc/src/ref_man.xml +++ b/lib/asn1/doc/src/ref_man.xml @@ -21,7 +21,7 @@ - Asn1 Reference Manual + ASN.1 Reference Manual OTP Team 1997-10-04 @@ -29,8 +29,8 @@ application.sgml -

The Asn1 application - contains modules with compile-time and run-time support for ASN.1.

+

The ASN.1 application + contains modules with compile-time and runtime support for ASN.1.

 -- cgit v1.2.3