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.

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:

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

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

Currently, Description looks like this: {ErrorDescription, StackTrace}. Applications should not depend on the exact contents of Description as it could change in the future.

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:

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

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.

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.

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

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.

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:

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.

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.

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]   

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.

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

      "This is the value of an Object descriptor"

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.

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. By default, a SEQUENCE is represented by a record in Erlang. It can also be represented as a map; see Map representation for SEQUENCE and SET. 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>>}     

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.

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.

If the ASN.1 module has been compiled with option maps, the types SEQUENCE and SET are represented as maps.

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

File DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
Seq1 ::= SEQUENCE {
    a INTEGER DEFAULT 42,
    b BOOLEAN OPTIONAL,
    c IA5String
}
END   

Optional fields are to be omitted from the map if they have no value:

1> asn1ct:compile('File', [per,maps]).
ok
2> {ok,E} = 'File':encode('Seq1', #{a=>0,c=>"string"}).
{ok,<<128,1,0,6,115,116,114,105,110,103>>} 

When decoding, optional fields will be omitted from the map:

3> 'File':decode('Seq1', E).
{ok,#{a => 0,c => "string"}}   

Default values can be omitted from the map:

4> {ok,E2} = 'File':encode('Seq1', #{c=>"string"}).
{ok,<<0,6,115,116,114,105,110,103>>}
5> 'File':decode('Seq1', E2).
{ok,#{a => 42,c => "string"}}   

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.

{asn1_ExtAlt, BytesForOpenType}

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.

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.

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.

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

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:

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
}      

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