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 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
).
Note!
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
.
Note!
In OTP R16, the options were simplified. The back end is chosen
using one of the options ber
, per
, or uper
.
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 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.
Functions
Asn1module = atom() | string()
Options = [Option| OldOption]
Option = ber | per | uper | der | compact_bit_string | legacy_bit_string | legacy_erlang_types | noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | undec_rest | no_ok_wrapper | {macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors
OldOption = ber | per
Reason = term()
Prefix = string()
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 that
returns the value in Erlang representation is generated.
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).
Asn1module
can be a full pathname (relative or
absolute) including filename with (or without) extension.
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"
).
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
must look as follows:
File1.asn File2.asn 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.
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 ASN.1
compiler and options that are applied to the Erlang compiler.
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 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. Therefore, only one
encoding rule per ASN.1
module can be used at runtime.
der
With this option the Distinguished Encoding Rules (DER) is chosen.
DER is regarded as a specialized variant of the BER encoding
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
as for ber
.
maps
This option changes the representation of the types
SEQUENCE
and SET
to use maps (instead of
records). This option also suppresses the generation of
.hrl
files.
For details, see Section Map representation for SEQUENCE and SET in the User's Guide.
compact_bit_string
The BIT STRING
type is decoded to "compact notation".
This option is not recommended for new code.
This option cannot be combined with the option maps
.
For details, see Section BIT STRING in the User's Guide.
This option implies option legacy_erlang_types
.
legacy_bit_string
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.
This option cannot be combined with the option maps
.
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 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.
This option cannot be combined with the option maps
.
{n2n, EnumTypeName}
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 (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 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 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 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
.
For instructions for exclusive decode, see Section Exclusive 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 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
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, 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 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 contain
records with identical names are included in a single module.
verbose
Causes more verbose information from the compiler describing what it is doing.
warnings_as_errors
Causes warnings to be treated as errors.
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 anySET
orSEQUENCE
is defined)Asn1module.erl
- Erlang module with encode, decode, and value functionsAsn1module.asn1db
- Intermediate format used by the compiler when modulesIMPORT
definitions from each other.
Module = Type = atom()
Value = term()
Reason = term()
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.
Note!
Currently, the value
function has many limitations.
Essentially, it will mostly work for old specifications based
on the 1997 standard for ASN.1, but not for most modern-style
applications. Another limitation is that the value
function
may not work if options that change code generations strategies
such as the options macro_name_prefix
and
record_name_prefix
have been used.
Module = Type = atom()
Value = term()
Options = [{i, IncludeDir}]
Reason = term()
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 as well as the general runtime support
work as expected.
Note!
Currently, the test
functions have many limitations.
Essentially, they will mostly work for old specifications based
on the 1997 standard for ASN.1, but not for most modern-style
applications. Another limitation is that the test
functions
may not work if options that change code generations strategies
such as the options macro_name_prefix
and
record_name_prefix
have been used.
-
test/1
iterates over all types inModule
. -
test/2
tests typeType
with a random value. -
test/3
tests typeType
withValue
.
Schematically, the following occurs for each type in the module:
{ok, Value} = asn1ct:value(Module, Type), {ok, Bytes} = Module:encode(Type, Value), {ok, Value} = Module:decode(Type, Bytes).
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
generating values. For static values using Value
no
options are needed.