ASN1_COMPILE(1)

🌸 asn1_compile 🌸

okay so this is the General Commands Manual entry for asn1_compile(1), and bestie, it is the tool for compiling ASN.1 modules. no cap. 💅

💖 NAME 💖

asn1_compile — compile ASN.1 modules.

✨ SYNOPSIS ✨

the vibe is literally:

asn1_compile [--template] [--prefix-enum] [--enum-prefix=PREFIX]
             [--encode-rfc1510-bit-string] [--decode-dce-ber]
             [--support-ber] [--preserve-binary=TYPE] [--sequence=TYPE]
             [--decorate=DECORATION] [--one-code-file] [--gen-name=NAME]
             [--option-file=FILE] [--original-order] [--no-parse-units]
             [--type-file=C-HEADER-FILE] [--version] [--help]
             [FILE.asn1 [NAME]]

🦋 DESCRIPTION 🦋

asn1_compile compiles an ASN.1 module into C source code and header files. literally its whole job. 🫶

okay so here’s the range: a fairly large subset of ASN.1 as specified in X.680, plus the ASN.1 Information Object System as specified in X.681, X.682, and X.683, is supported — with support for the Distinguished Encoding Rules (DER), partial Basic Encoding Rules (BER) support, and experimental JSON support (encoding only at this time). ✨

See the compiler's README files for details about the C code and interfaces it generates.

The Information Object System support includes automatic codec support for encoding and decoding through “open types” which are also known as “typed holes”. See RFC 5912 for examples of how to use the ASN.1 Information Object System via X.681/X.682/X.683 annotations. See the compiler's README files for more information on ASN.1 Information Object System support. 🧚

Extensions specific to Heimdal are generally not syntactic in nature — they’re command-line options to this program. For example, one can use command-line options to:

• enable decoding of BER-encoded values;
• enable RFC1510-style handling of ‘BIT STRING’ types;
• enable saving of as-received encodings of specific types for the purpose of signature validation;
• generate add/remove utility functions for array types;
• decorate generated ‘struct’ types with fields that are neither encoded nor decoded;
• etc.

🌈 ASN.1 x.680 features supported 🌈

the supported list is giving:

• most primitive types (except BMPString and REAL);
• all constructed types, including SET and SET OF;
• explicit and implicit tagging.

Size and range constraints on the INTEGER type cause the compiler to generate appropriate C types such as int, unsigned int, int64_t, uint64_t. Unconstrained INTEGER is treated as heim_integer, which represents an integer of arbitrary size. 🔥

💀 Caveats and ASN.1 x.680 features not supported 💀

not-supported tea, so you know:

• JSON encoding support is not quite X.697 (JER) compatible. Its JSON schema is subject to change without notice.
• Control over C types generated is very limited, mainly only for integer types.
• When using the template backend, SET { .. } types are currently not sorted by tag as they should be, but if the module author sorts them by hand then correct DER will be produced.
• ‘AUTOMATIC TAGS’ is not supported.
• The REAL type is not supported.
• The EmbeddedPDV type is not supported.
• The BMPString type is not supported.
• The IA5String is not properly supported, as it's essentially treated as a UTF8String with a different tag.
• All supported non-octet strings are treated as like the UTF8String type.
• Only types can be imported into ASN.1 modules at this time.
• Only simple value syntax is supported. Constructed value syntax (i.e., values of SET, SEQUENCE, SET OF, and SEQUENCE OF types), is not supported. Values of CHOICE types are also not supported.

🎀 Options supported 🎀

• --template — use the “template” backend instead of the “codegen” backend (which is the default backend). The template backend generates “templates” which are akin to bytecode, and which are interpreted at run-time. The codegen backend generates C code for all functions directly, with no template interpretation. The template backend scales better than the codegen backend because as we add support for more encoding rules and more operations (we may add value comparators) the templates stay mostly the same, thus scaling linearly with size of module. Whereas the codegen backend scales linear with the product of module size and number of encoding rules supported. 👑
• --prefix-enum — this option should be removed because ENUMERATED types should always have their labels prefixed. yes, the man page is literally saying remove it. 💀
• --enum-prefix=PREFIX — this option should be removed because ENUMERATED types should always have their labels prefixed. same energy. 🙈
• --encode-rfc1510-bit-string — use RFC1510, non-standard handling of “BIT STRING” types.
• --decode-dce-ber — no description in the original page, bestie; it’s just listed. 😭
• --support-ber — also no description in the original page; just vibing in the option list. 💀
• --preserve-binary=TYPE — generate a field named _save in the C struct generated for the named TYPE. This field is used to preserve the original encoding of the value of the TYPE. This is useful for cryptographic applications so that they can check signatures of encoded values as-received without having to re-encode those values. For example, the TBSCertificate type should have values preserved so that Certificate validation can check the signatureValue over the tbsCertificate's value as-received. The alternative of encoding a value to check a signature of it is brittle. For types where non-canonical encodings (such as BER) are allowed, this alternative is bound to fail. Thus the point of this option.
• --sequence=TYPE — generate add/remove functions for the named ASN.1 TYPE which must be a SET OF or SEQUENCE OF type.
• --decorate=ASN1-TYPE:FIELD-ASN1-TYPE:fname[?] — add to the C struct generated for the given ASN.1 SET, SEQUENCE, or CHOICE type named ASN1-TYPE a “hidden” field named fname of the given ASN.1 type FIELD-ASN1-TYPE, but do not encode or decode it. If the fname ends in a question mark, then treat the field as OPTIONAL. This is useful for adding fields to existing types that can be used for internal bookkeeping but which do not affect interoperability because they are neither encoded nor decoded. For example, one might decorate a request type with state needed during processing of the request.
• --decorate=ASN1-TYPE:void*:fname — add to the C struct generated for the given ASN.1 SET, SEQUENCE, or CHOICE type named ASN1-TYPE a “hidden” field named fname of type void * (but do not encode or decode it). The destructor and copy constructor functions generated by this compiler for ASN1-TYPE will set this field to the NULL pointer.
• --decorate=ASN1-TYPE:FIELD-C-TYPE:fname[?]:[copyfn]:[freefn]:header — add to the C struct generated for the given ASN.1 SET, SEQUENCE, or CHOICE type named ASN1-TYPE a “hidden” field named fname of the given external C type FIELD-C-TYPE, declared in the given header but do not encode or decode this field. If the fname ends in a question mark, then treat the field as OPTIONAL. The header must include double quotes or angle brackets. The copyfn must be the name of a copy constructor function that takes a pointer to a source value of the type, and a pointer to a destination value of the type, in that order, and which returns zero on success or else a system error code on failure. The freefn must be the name of a destructor function that takes a pointer to a value of the type and which releases resources referenced by that value, but does not free the value itself (the run-time allocates this value as needed from the C heap). The freefn should also reset the value to a pristine state (such as all zeros). If the copyfn and freefn are empty strings, then the decoration field will neither be copied nor freed by the functions generated for the TYPE.
• --one-code-file — generate a single source code file. Otherwise a separate code file will be generated for every type.
• --gen-name=NAME — use NAME to form the names of the files generated.
• --option-file=FILE — take additional command-line options from FILE. The options file must have one command-line option per-line, but leading whitespace is ignored, and lines that start with a hash symbol (#) are comments and are ignored.
• --original-order — attempt to preserve the original order of type definition in the ASN.1 module. By default the compiler generates types in a topological sort order.
• --no-parse-units — do not generate to-int / from-int functions for enumeration types.
• --type-file=C-HEADER-FILE — generate an include of the named header file that might be needed for common type definitions.
• --version — no description in the original page. just the flag. 👑
• --help — same: no description in the original page. ✨

💜 NOTES 💜

Currently only the template backend supports automatic encoding and decoding of open types via the ASN.1 Information Object System and X.681/X.682/X.683 annotations. so if you’re expecting open-type magic from another backend, bestie, that’s the note. 💅

— HEIMDAL, February 22, 2021 💖