ASN.1 to C compiler takes the ASN.1 module files (example) and generates the C++ compatible C source code. That code can be used to serialize the native C structures into compact and unambiguous BER/OER/PER/XER/JER-based data files, and deserialize the files back.
Various ASN.1 based formats are widely used in the industry, such as to encode the X.509 certificates employed in the HTTPS handshake, to exchange control data between mobile phones and cellular networks, to perform car-to-car communication in intelligent transportation networks.
The ASN.1 family of standards is large and complex, and no open source compiler supports it in its entirety. The asn1c is arguably the most evolved open source ASN.1 compiler.
Current release: 1.5.3
This release corrects imported-name resolution and compiler diagnostics, fixes PER extensibility, avoids generated-file collisions with runtime skeletons on case-insensitive filesystems, and addresses a skeleton build race. It also includes header usability improvements and updated compiler documentation. See the v1.5.3 release notes for details.
Important: Decoding behavior for unknown extensions has changed from "fail" to "skip/relay". Evaluate the impact on your application before upgrading; define
ASN_REJECT_UNKNOWN_EXTENSIONSto restore the previous strict behavior.
This forward-compatible default applies to unknown alternatives of extensible
UPER/OER CHOICE values and unknown additions of extensible UPER/APER
ENUMERATED values. Existing deployments may rely on the old RC_FAIL result
as an implicit input-validation gate or as a protocol error in a state machine.
Compile all decoder skeleton objects with the macro and perform a clean rebuild;
defining it only in application code does not change an already-built runtime
library. Compatibility warning contributed by shakespark@gmail.com.
See ChangeLog for the complete release history and release-notes/v1.5.3.md for these release notes, release-notes/v1.4.2.md for v1.4.2, and release-notes/v1.4.md for v1.4.
ASN.1 encodings interoperability table
The ASN.1 family of standards define a number of ways to encode data, including byte-oriented (e.g., BER), bit-oriented (e.g., PER), and textual (e.g., XER). Some encoding variants (e.g., DER) are just stricter variants of the more general encodings (e.g., BER).
The interoperability table below specifies which API functions can be used to exchange data in a compatible manner. If you need to produce data conforming to the standard specified in the column 1, use the API function in the column 2. If you need to process data conforming to the standard(s) specified in the column 3, use the API function specified in column 4. See the doc/asn1c-usage.pdf for details.
| Encoding | API function | Understood by | API function |
|---|---|---|---|
| BER | der_encode() | BER | ber_decode() |
| DER | der_encode() | DER, BER | ber_decode() |
| CER | not supported | CER, BER | ber_decode() |
| BASIC-OER | oer_encode() | *-OER | oer_decode() |
| CANONICAL-OER | oer_encode() | *-OER | oer_decode() |
| BASIC-UPER | uper_encode() | *-UPER | uper_decode() |
| CANONICAL-UPER | uper_encode() | *-UPER | uper_decode() |
| BASIC-APER | aper_encode() | *-APER | aper_decode() |
| CANONICAL-APER | aper_encode() | *-APER | aper_decode() |
| BASIC-XER | xer_encode(XER_F_BASIC) | *-XER | xer_decode() |
| CANONICAL-XER | xer_encode(XER_F_CANONICAL) | *-XER | xer_decode() |
| JER | jer_encode() | JER | jer_decode() |
| JER-MINIFIED | jer_encode(JER_F_MINIFIED) | JER | jer_decode() |
| CBOR | cbor_encode() | CBOR | cbor_decode() |
*) Asterisk means both BASIC and CANONICAL variants. JER-MINIFIED produces
whitespace-free JSON, and jer_decode() accepts either JER form.
asn1c supports schema-level XER and JER encoding instructions for selected
standard-style encodings. Supported instructions include XER BASE64, TEXT,
DECIMAL, GLOBAL-DEFAULTS MODIFIED-ENCODINGS, and the legacy XER OCTET
STRING controls hexadecimal and utf8; JER supports BASE64, enumerated
value TEXT, and member NAME.
Flag ::= [TEXT] BOOLEAN
Blob ::= [JER:BASE64] OCTET STRING
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
DECIMAL Ratio
TEXT Count.one AS "uno"
END
ENCODING-CONTROL JER
NAME Packet.payload AS "payload64"
TEXT Mode.busy AS "occupied"
ENDBare [BASE64] remains a XER instruction for compatibility; use
[JER:BASE64] for JER. XER DECIMAL applies only to REAL and requires
GLOBAL-DEFAULTS MODIFIED-ENCODINGS. JER NAME changes JSON keys only; it
does not rename C fields or XER XML tags. See
ENCODING_CONTROL_STATUS.md for the support
matrix and diagnostics.
If you haven't installed the asn1c yet, read the INSTALL.md file for a short installation guide.
For the list of asn1c command line options, see asn1c -h or man asn1c.
The comprehensive documentation on this compiler is in doc/asn1c-usage.pdf.
Extensible UPER and OER types, plus extensible APER ENUMERATED types, decode
unknown extension additions forward-compatibly by default. Unknown CHOICE
alternatives are skipped and reported with no selected local alternative;
unknown UPER/APER ENUMERATED values are represented by the reserved
LONG_MAX - extension_index range so they can be relayed with the same PER
transfer syntax. Applications that require the historical strict rejection
behavior may compile generated skeletons with ASN_REJECT_UNKNOWN_EXTENSIONS;
this forfeits forward compatibility.
Please also read the FAQ file.
An excellent book on ASN.1 is written by Olivier Dubuisson: "ASN.1 Communication between heterogeneous systems", ISBN:0-12-6333361-0.
(also check out doc/asn1c-quick.pdf)
After installing the compiler (see INSTALL.md), you may use the asn1c command to compile the ASN.1 specification:
asn1c <module.asn1> # Compile moduleIf several specifications contain interdependencies, all of them must be specified at the same time:
asn1c <module1.asn1> <module2.asn1> ... # Compile interdependent modulesThe asn1c source tarball contains the examples/ directory with several ASN.1 modules and a script to extract the ASN.1 modules from RFC documents. Refer to the examples/README file in that directory.
To compile the X.509 PKI module:
./asn1c/asn1c -P ./examples/rfc3280-*.asn1 # Compile-n-printIn this example, the -P option is to print the compiled text on the standard output. The default behavior is that asn1c compiler creates multiple .c and .h files for every ASN.1 type found inside the specified ASN.1 modules.
The compiler's -E and -EF options are used for testing the parser and the semantic fixer, respectively. These options will instruct the compiler to dump out the parsed (and fixed) ASN.1 specification as it was "understood" by the compiler. It might be useful for checking whether a particular syntactic construction is properly supported by the compiler.
asn1c -EF <module-to-test.asn1> # Check semantic validityWhen working with large ASN.1 specifications (such as 3GPP 5G specs), you may only need to generate code for specific PDU (Protocol Data Unit) types and their dependencies. The asn1c compiler provides options for this:
To list all types that a specific PDU depends on without generating code:
asn1c -pdu=PDUType -flist-deps module.asn1This will output a list of type names that are dependencies of the specified PDU.
To generate code only for a specific PDU and its dependencies (reducing the amount of generated code):
asn1c -pdu=PDUType -fgen-only-pdu-deps module.asn1This is particularly useful for large specifications where you only need a subset of the types. You can specify multiple PDUs:
asn1c -pdu=PDU1 -pdu=PDU2 -fgen-only-pdu-deps module.asn1The -fgen-only-pdu-deps option also works with -pdu=all and -pdu=auto.
A name listed in an IMPORTS group always resolves to the module that its
FROM ModuleName names (X.680 13.19), with or without this flag. So when
two ASN.1 modules export identically-named types and a third module imports
one from each, each name binds to the module that it is imported from.
Without the flag (the default), a name that no IMPORTS group lists is also
searched for in the body of each FROM module (whole-module fallback).
X.680 does not allow this, but some specifications rely on it. Use
-fprefer-import-source to disable the fallback and resolve only names
that an IMPORTS group lists:
asn1c -fprefer-import-source <module1.asn1> <module2.asn1> ...With the flag, a name that is used but not listed in IMPORTS (and not defined locally) is reported as an error.
The asn1c compiler works by processing the ASN.1 module specifications in several stages:
- During the first stage, the ASN.1 file is parsed. (Parsing produces an ASN.1 syntax tree for the subsequent levels)
- During the second stage, the syntax tree is "fixed". (Fixing is a process of checking the tree for semantic errors, accompanied by the tree transformation into the canonical form)
- During the third stage, the syntax tree is compiled into the target language.
There are several command-line options reserved for printing the results after each stage of operation:
<parser> => print (-E)
<parser> => <fixer> => print (-E -F)
<parser> => <fixer> => <compiler> => print (-P)
<parser> => <fixer> => <compiler> => save-compiled [default]
When decoding fails (e.g., due to truncated or malformed input), the converter
tool can print partial decoding results to help with debugging. Use the -P
flag with the generated converter to see what was successfully decoded before
the error occurred:
./converter-example -iper -P truncated-message.uperFor more details, see PARTIAL_DECODING.md.
-- Mouse and Lev Walkin