asn1ct(3)

💖 NAME 💖

asn1ct — the ASN.1 compiler and its compile-time support functions. That's it, that's the whole name. Welcome to asn1ct(3), bestie, we're doing this together. 🫶

✨ DESCRIPTION ✨

Okay so. The ASN.1 compiler takes an ASN.1 module as input and generates a corresponding Erlang module, and that generated module can encode and decode the data types you specified. Iconic behavior honestly. 💅

Or!! Alternatively, the compiler takes a specification module that specifies all the input modules, and generates a module with encode/decode functions. And on top of all that, there are some generic functions you can use while you're developing applications that handle ASN.1 data (encoded as BER or PER). Slay.

NOTE: By default in Erlang/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. 👑

---

🔥 FUNCTIONS 🔥

compile(Asn1Module, Options) -> ok | {error, Reason}

compile(Asn1Module, Options) -> ok | {error, Reason}
                 when
                     Asn1Module :: atom() | string(),
                     Options :: [Option | OldOption],
                     Option ::
                         ber | per | uper | jer | der |
                         compact_bit_string | legacy_bit_string |
                         legacy_erlang_types | noobj |
                         {n2n, EnumTypeName :: term()} |
                         {outdir, Dir :: term()} |
                         {i, IncludeDir :: term()} |
                         asn1config | undec_rest | no_ok_wrapper |
                         {macro_name_prefix, Prefix} |
                         {record_name_prefix, Prefix} |
                         verbose | warnings_as_errors | deterministic,
                     OldOption :: ber | per,
                     Reason :: term(),
                     Prefix :: string().

So what does it do?? It compiles the ASN.1 module Asn1Module and generates an Erlang module Asn1Module.erl with encode and decode functions for all the types defined in that ASN.1 module. Chef's kiss. 😌

And for every ASN.1 value defined in the module, you also get an Erlang function that returns the value in Erlang representation. Free real estate.

Now, about finding the file. If Asn1Module is a filename without an extension, first .asn1 is assumed, then .asn, and finally .py (to be compatible with the old ASN.1 compiler). Asn1Module can also be a full pathname (relative or absolute) including filename, with (or without) the extension. Whatever works for you, babe.

If you need to compile a set of ASN.1 modules into one Erlang file with encode/decode functions, you list all the involved files in a configuration file, one line per file. That configuration file has to have a double extension: .set.asn1 (and the .asn1 part can alternatively be .asn or .py). So if your input files are File1.asn1, File2.asn1, and File3.asn1, the configuration file should look exactly like this:

File1.asn1
File2.asn1
File3.asn1

In that case, the output files get their names from the configuration file. If the configuration file is named SetOfFiles.set.asn1, then the names of the output files are SetOfFiles.hrl, SetOfFiles.erl, and SetOfFiles.asn1db. Cute, right? 🎀

Sometimes in a system of ASN.1 modules, different modules can have different default tag modes — for example, one uses AUTOMATIC and another uses IMPLICIT. The multi-file compilation resolves the default tagging as if the modules were compiled separately. No cap.

Name collisions are an 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 differ in the definition, they get 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 you whether a definition was renamed, and the new name that must be used to encode/decode data. Pay attention to those, bestie, they matter.

Options is a list with options specific for the ASN.1 compiler, plus options that get applied to the Erlang compiler. The ASN.1 compiler passes on any unrecognized options to the Erlang compiler. The available options are as follows:

• ber | per | uper | jer — the encoding rule to be used. The supported encoding rules are Basic Encoding Rules (ber), Packed Encoding Rules (per) aligned, PER unaligned (uper), and JSON Encoding Rules (jer). The jer option can be used by itself to generate a module that only supports encoding/decoding of JER, or it can be used as a supplementary option to ber, per, and uper, in which case a module that handles both the main encoding rules and JER will be generated. In that case, the exported functions for JER will be jer_encode(Type, Value) and jer_decode(Type, Bytes).

JER (ITU-T X.697) are experimental in OTP 22. There is support for a subset of the X.697 standard, for example there is no support for:

• JER encoding instructions
• the REAL type

CHANGE: In Erlang/OTP 27 and later, module json in STDLIB is used for encoding and decoding JSON. Before Erlang/OTP 27, it was necessary to provide an external JSON library.

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. Pick your fighter. 🥊

• 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 slower encoding (the price of correctness, honestly 💀). 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.

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

This option implies option legacy_erlang_types, and it cannot be combined with option maps. 🚫

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

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

This option implies option legacy_erlang_types, and it cannot be combined with option maps. 🚫

• legacy_erlang_types — use the same Erlang types to represent BIT STRING and OCTET STRING as in Erlang/OTP R16.

This option is not recommended for new code.

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

This option cannot be combined with option maps. 🚫

• {n2n, EnumTypeName} — tells the compiler to generate functions for conversion between names (as atoms) and numbers, and conversely, for the specified EnumTypeName. You can have 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. Bye. ✋

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. You can give several {i, IncludeDir} options.
• {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 into consideration. 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 — by default when decoding, any bytes following the end of an ASN.1 data structure are discarded. If an ASN.1 module is compiled with option undec_rest, the decode function returns a tuple {ok, Value, Rest}, where Rest is the bytes following the ASN.1 data structure. Rest can be a list or a binary.
• 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. No chill. 😤
• {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.

---

so yeah, picking up right where we left off with the compiler options — these are the ones that change the whole vibe of your build: 💖

• verbose — makes the compiler spill all the extra tea about what it's doing. more info, more chaos. 🗣️
• warnings_as_errors — warnings? not today. this treats them as full-on errors. periodt. ⚠️
• deterministic — strips every non-deterministic option from the -asn1_info() attribute. so your builds stay consistent, no cap. ✨

Unrecognized options get passed straight to the Erlang compiler when the generated .erl file is compiled. it's giving relay race. 🏃‍♀️

The compiler generates these files, and they're all iconic in their own way:

• Asn1Module.hrl (if any SET or SEQUENCE is defined)
• Asn1Module.erl — Erlang module with encode, decode, and value functions. the main character fr. 💅
• Asn1Module.asn1db — intermediate format used by the compiler when modules IMPORT definitions from each other. lowkey the glue holding the group project together. 🦋

🧪 test(Module) -> ok | {error, Reason}

       test(Module) -> ok | {error, Reason}
                     when Module :: module(), Reason :: term().

Tests encoding and decoding of all types in Module. for more details, see test/3. 👑

🌸 test(Module, Type | Options) -> ok | {error, Reason}

       test(Module, Type | Options) -> ok | {error, Reason}
                     when
                         Module :: module(),
                         Type :: atom(),
                         Options :: [{i, IncludeDir :: term()}],
                         Reason :: term().

Tests encoding and decoding of Module. 💫

If the second argument is given as atom Type, that type gets tested. if it's given as list Options, those are the options used for testing all types in the module. either way, we're testing. for more details, see test/3. 🎀

🔥 test(Module, Type, Value | Options) -> ok | {error, Reason}

       test(Module, Type, Value | Options) -> ok | {error, Reason}
                     when
                         Module :: module(),
                         Type :: atom(),
                         Value :: term(),
                         Options :: [{i, IncludeDir :: term()}],
                         Reason :: term().

Performs a test of encode and decode of types in Module. the generated functions are called by this function. it's useful for testing to make sure the generated encode and decode functions — plus 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 in Module. 🔁
• test/2 tests type Type with a random value. 🎲
• test/3 tests type Type with Value. 🎯

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're 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. 🗂️

💜 value(Module, Type) -> {ok, Value} | {error, Reason}

       value(Module, Type) -> {ok, Value} | {error, Reason}
                      when
                          Module :: 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. so spicy. 🌶️

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

---

and that's the whole manual page, bestie! this comes from Ericsson AB, version asn1 5.5, and it's the asn1ct(3) page — no date in the footer, but it's still iconic. slay. 💅✨