asn1c compiles ASN.1 modules into C++-compatible C source by default. Its
opt-in --rust backend generates Rust source and Cargo metadata for the
supported subset. Generated code can serialize native values into compact
BER-family, OER, PER, XER, JER, and CBOR data, and decode them where supported.
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.
Use asn1c --strict-mode (also with --rust) to select the standards policy
for all enabled codecs. It disables the C non-known-multiplier PER SIZE
compatibility fallback, adds automatic C codec-boundary constraint checks,
and tightens documented syntax/repertoire allowances. Existing invocations
retain their compatibility behavior. Regenerate and rebuild both peers when
changing PER profiles. See strict-mode behavior and limits
for format coverage, Rust support limits and streaming/API contracts.
The C runtime and generated Rust BER decoder validate UTCTime syntax, clock
ranges, and real calendar dates by default. The accepted ASN.1 forms have
optional seconds and either Z or a complete +hhmm / -hhmm offset. The
C runtime's existing two-digit year mapping remains 00..59 to 2000..2059
and 60..99 to 1960..1999; it is not an RFC 5280 profile check. C's
-fno-constraints option does not disable decode validation.
Use asn1c -ftolerant-utc-time to retain legacy permissive UTCTime
decoding. For C output, the option records ASN_ENABLE_TOLERANT_UTCTIME in
generated asn_config.h. When reusing a separately built C runtime, define
that macro while compiling its skeleton objects; defining it only in
application code cannot change an already-built runtime. -R omits C runtime
support and configuration files, so configure the separately built runtime
directly. For Rust output, the option selects a tolerant BER decoder in the
generated type; it does not require a Cargo feature. Rust DER encoding stays
raw and canonical CER validation remains strict. The option affects
UTCTime; GeneralizedTime behavior is unchanged.
asn_UT2time() uses time_t and returns (time_t)-1 for errors, which can
collide with the valid UTC instant 1969-12-31 23:59:59. Use the UTCTime
constraint callback to check syntax when that distinction matters; time
conversion remains subject to the platform's representable time_t range.
The syntax follows ITU-T X.680, clauses 47.2 and 47.3.
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.
The JER converter and BER string security review documents the fixes for issues #578/#581 and the corrections to PRs #579/#580, including reproduction cases and regression coverage. The extension semantics and security review documents fixes for extensible permitted alphabets, SEQUENCE extension addition groups, and implied ENUMERATED extensibility (#582–#584). Regenerate C output with the matching updated runtime because SEQUENCE group descriptors now carry additional metadata. The follow-up SET extension-group notes describe transparent SET groups, regenerated descriptor layout, stack bounds, and UPER, APER, OER, and JER group support.
The incremental JER design proposal describes how to progress from buffering one PDU to decoding large messages in chunks, with explicit memory limits, framing and an optional application sink.
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 | cer_encode() | CER | cer_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.
CER encoding is available through cer_encode(), asn_encode(ATS_CER, ...),
and the generated converter's -ocer output selector. The default C target
generates CER support together with BER support; -gen-CER enables its
BER-family dependencies, -no-gen-CER omits CER encoding, and -no-gen-BER
omits the shared family. CER decoding is strict: cer_decode(),
asn_decode(ATS_CER, ...), and the converter's -icer input selector decode
with the BER decoder, re-encode the value with cer_encode(), and reject input
that is not byte-identical to the canonical CER encoding (for example long-form
lengths, definite-length constructed values, or unsorted SET OF). -icer
requires CER generation and buffers the whole input. As with the other
generated codecs, availability depends on the generated descriptor kinds and
canonical value forms handled by the encoder. ASN_DISABLE_CER_SUPPORT
disables both CER encoding and strict CER decoding at build time. See the
binary codec support audit for the current
descriptor, value, and resource boundaries.
Constructed CER character strings retain their outer string tag and use
universal OCTET STRING tags for the fragments; BIT STRING fragments use their
universal BIT STRING tag. BER input also preserves legacy opaque ANY
containers under the bounds described in that audit.
The C BER decoder validates each primitive BIT STRING fragment: its content must include an unused-bit count from 0 through 7, and an empty payload must have count zero. Only the final component may have unused bits (X.690 8.6.4). These checks also apply to nested constructed values and incremental input; malformed fragments fail decoding instead of silently changing the value.
In Rust output mode, CER supports top-level BOOLEAN, NULL, finite
nonextensible INTEGER values whose bounds fit signed 64-bit integers, direct
nonextensible ENUMERATED values fitting signed 64-bit integers, and direct
fixed or bounded BIT STRING and OCTET STRING values with supported finite
SIZE constraints. Long strings use CER fragmentation; decode_cer()
re-encodes and compares the consumed prefix to reject noncanonical forms.
Flat SEQUENCE records with an untagged outer type and distinct effective tags
for direct BOOLEAN, NULL, bounded INTEGER, ENUMERATED, and finite bounded
BIT/OCTET STRING fields also support
required and OPTIONAL members, literal BOOLEAN/INTEGER DEFAULT members, and
an empty record. Their BER/DER/CER operations share one record-wide resource
budget.
Flat SET records with an untagged outer type support the same six direct field kinds
under BER/DER/CER-only selection (-no-gen-UPER), with unordered BER field
decoding and canonical tag-ordered DER/CER output. The current XER-only SET
slice remains a separate codec selection.
The same flat BER/DER/CER records accept resolved context-specific IMPLICIT
member tags, including automatic tags, and one context-specific EXPLICIT
wrapper per direct field. High tag numbers within the C runtime's range and
repeated primitive kinds with distinct effective tags are supported; SET
output sorts by effective class and tag number. One nonrecursive inline
SEQUENCE child is supported in an untagged SEQUENCE or BER/CER-only SET, with
required or OPTIONAL direct primitive leaves and a shared resource budget.
Root tags, multi-tag stacks, aliases, and deeper constructed records remain
outside this slice.
Rust CER output is selected by default with UPER; -no-gen-UPER selects
CER-only output. -gen-BER adds BER prefix decoding and DER encoding for
these direct types. See Rust output usage and limits
and the parity design for remaining gaps.
The same primitive Rust subset also supports opt-in APER and OER encoding and
decoding with -gen-APER and -gen-OER.
Basic/canonical OER, UPER, and APER selectors share each family's decoder; CBOR has its own encoder and decoder. Support still depends on the generated type's codec operations and enabled codec families. See the binary codec audit for dispatch details and limits, and the CBOR standards review for the supported profile, IETF references, and interoperability changes.
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.
--rust selects native Rust output as a complete compiler mode. It generates a
standalone Cargo package with safe, dependency-free UPER and CER codecs for
BOOLEAN, NULL, and finite nonextensible INTEGER ranges fitting i64.
APER, OER, BER/DER, and JER are available for selected direct primitive types
when explicitly enabled. Unsupported schemas and unavailable codec requests
fail with diagnostics. -ftolerant-utc-time selects legacy UTCTime BER
decoding in the generated type. Build the generated package with Cargo in
offline mode.
With UPER as the only selected codec (-no-gen-CER), SEQUENCE assignments can
contain required, OPTIONAL, and supported primitive DEFAULT fields, including
inline nested SEQUENCE records. A shared cursor enforces one resource budget
across the complete value. Direct fixed-size OCTET STRING and BIT STRING types,
and either string type with one bounded contiguous SIZE range below 65536,
support UPER, including required and OPTIONAL SEQUENCE fields. Bounded BIT
STRING values carry their exact meaningful bit length. Direct
nonextensible ENUMERATED assignments use UPER indexes in numeric value order.
ENUMERATED and direct fixed-size or bounded OCTET STRING assignments can also
opt into JER.
Direct fixed-size and bounded BIT STRING assignments support the C-compatible
JER hexadecimal forms, including the bit length for bounded values.
Named-bit lists and other unsupported forms are rejected with diagnostics.
See the initial implementation for usage and limits, and the conversion plan for incremental delivery of all current codec families and test migration.
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.
APER open types governed by extensible information-object sets retain unknown
values in an opaque ANY_t alternative (choice.asn1cUnknown, with a numeric
suffix if that name is already used). Applications can copy, modify other fields,
and re-encode these values with APER. Regenerate C sources with the updated
compiler and runtime to obtain the new alternative. See the
issue #586 notes for ownership,
identifier validation, and round-trip limits.
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