.\" Copyright (c) 2019 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden).
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 3. Neither the name of the Institute nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id$
.\"
.Dd February 22, 2021
.Dt ASN1_COMPILE 1
.Os HEIMDAL
.Sh NAME
.Nm asn1_compile
.Nd compile ASN.1 modules
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl Fl template
.Op Fl Fl prefix-enum
.Op Fl Fl enum-prefix=PREFIX
.Op Fl Fl encode-rfc1510-bit-string
.Op Fl Fl decode-dce-ber
.Op Fl Fl support-ber
.Op Fl Fl preserve-binary=TYPE
.Op Fl Fl sequence=TYPE
.Op Fl Fl decorate=DECORATION
.Op Fl Fl one-code-file
.Op Fl Fl gen-name=NAME
.Op Fl Fl option-file=FILE
.Op Fl Fl original-order
.Op Fl Fl no-parse-units
.Op Fl Fl type-file=C-HEADER-FILE
.Op Fl Fl version
.Op Fl Fl help
.Op Ar FILE.asn1 Op Ar NAME
.Ek
.Sh DESCRIPTION
.Nm
compiles an ASN.1 module into C source code and header files.
.Pp
A fairly large subset of ASN.1 as specified in X.680, and 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).
.Pp
See the compiler's README files for details about the C code and
interfaces it generates.
.Pp
The Information Object System support includes automatic codec
support for encoding and decoding through
.Dq open types
which are also known as
.Dq 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.
.Pp
Extensions specific to Heimdal are generally not syntactic in
nature but rather command-line options to this program.
For example, one can use command-line options to:
.Bl -bullet -compact -width Ds -offset indent
.It
enable decoding of BER-encoded values;
.It
enable RFC1510-style handling of
.Sq BIT STRING
types;
.It
enable saving of as-received encodings of specific types for the
purpose of signature validation;
.It
generate add/remove utility functions for array types;
.It
decorate generated
.Sq struct
types with fields that are neither encoded nor decoded;
.El
etc.
.Pp
ASN.1 x.680 features supported:
.Bl -bullet -compact -width Ds -offset indent
.It
most primitive types (except BMPString and REAL);
.It
all constructed types, including SET and SET OF;
.It
explicit and implicit tagging.
.El
.Pp
Size and range constraints on the
.Sq INTEGER
type cause the compiler to generate appropriate C types such as
.Sq int ,
.Sq unsigned int ,
.Sq int64_t ,
.Sq uint64_t .
Unconstrained
.Sq INTEGER
is treated as
.Sq heim_integer ,
which represents an integer of arbitrary size.
.Pp
Caveats and ASN.1 x.680 features not supported:
.Bl -bullet -compact -width Ds -offset indent
.It
JSON encoding support is not quite X.697 (JER) compatible.
Its JSON schema is subject to change without notice.
.It
Control over C types generated is very limited, mainly only for
integer types.
.It
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.
.It
.Sq AUTOMATIC TAGS
is not supported.
.It
The
.Va REAL
type is not supported.
.It
The
.Va EmbeddedPDV
type is not supported.
.It
The
.Va BMPString
type is not supported.
.It
The
.Va IA5String
is not properly supported, as it's essentially treated as a
.Va UTF8String
with a different tag.
.It
All supported non-octet strings are treated as like the
.Va UTF8String
type.
.It
Only types can be imported into ASN.1 modules at this time.
.It
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.
.El
.Pp
Options supported:
.Bl -tag -width Ds
.It Fl Fl template
Use the
.Dq template
backend instead of the
.Dq codegen
backend (which is the default backend).
.Pp
The template backend generates
.Dq templates
which are akin to bytecode, and which are interpreted at
run-time.
.Pp
The codegen backend generates C code for all functions directly,
with no template interpretation.
.Pp
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.
.It Fl Fl prefix-enum
This option should be removed because ENUMERATED types should
always have their labels prefixed.
.It Fl Fl enum-prefix=PREFIX
This option should be removed because ENUMERATED types should
always have their labels prefixed.
.It Fl Fl encode-rfc1510-bit-string
Use RFC1510, non-standard handling of
.Dq BIT STRING
types.
.It Fl Fl decode-dce-ber
.It Fl Fl support-ber
.It Fl Fl preserve-binary=TYPE
Generate a field named
.Sq _save
in the C struct generated for the named
.Ar TYPE .
This field is used to preserve the original encoding of the value
of the
.Ar TYPE .
.Pp
This is useful for cryptographic applications so that they can
check signatures of encoded values as-received without having to
re-encode those values.
.Pp
For example, the TBSCertificate type should have values preserved
so that Certificate validation can check the signatureValue over
the tbsCertificate's value as-received.
.Pp
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.
.It Fl Fl sequence=TYPE
Generate add/remove functions for the named ASN.1
.Ar TYPE
which must be a
.Sq SET OF
or
.Sq SEQUENCE OF
type.
.It Fl Fl decorate=ASN1-TYPE:FIELD-ASN1-TYPE:fname[?]
Add to the C struct generated for the given ASN.1 SET, SEQUENCE, or
CHOICE type named
.Ar ASN1-TYPE
a
.Dq hidden
field named
.Ar fname
of the given ASN.1 type
.Ar FIELD-ASN1-TYPE ,
but do not encode or decode it.
If the
.Ar fname
ends in a question mark, then treat the field as OPTIONAL.
.Pp
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.
.It Fl Fl decorate=ASN1-TYPE:void*:fname
Add to the C struct generated for the given ASN.1 SET, SEQUENCE, or
CHOICE type named
.Ar ASN1-TYPE
a
.Dq hidden
field named
.Ar fname
of type
.Sq void *
(but do not encode or decode it.
.Pp
The destructor and copy constructor functions generated by this
compiler for
.Ar ASN1-TYPE
will set this field to the
.Sq NULL
pointer.
.It Fl Fl 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
.Ar ASN1-TYPE
a
.Dq hidden
field named
.Ar fname
of the given external C type
.Ar FIELD-C-TYPE ,
declared in the given
.Ar header
but do not encode or decode this field.
If the
.Ar fname
ends in a question mark, then treat the field as OPTIONAL.
.Pp
The
.Ar header
must include double quotes or angle brackets.
The
.Ar 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
.Ar 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
.Ar freefn
should also reset the value to a pristine state (such as all
zeros).
.Pp
If the
.Ar copyfn
and
.Ar freefn
are empty strings, then the decoration field will neither be
copied nor freed by the functions generated for the
.Ar TYPE .
.It Fl Fl one-code-file
Generate a single source code file.
Otherwise a separate code file will be generated for every type.
.It Fl Fl gen-name=NAME
Use
.Ar NAME
to form the names of the files generated.
.It Fl Fl option-file=FILE
Take additional command-line options from
.Ar 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 
.Sq ( # )
are comments and are ignored.
.It Fl Fl 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.
.It Fl Fl no-parse-units
Do not generate to-int / from-int functions for enumeration
types.
.It Fl Fl type-file=C-HEADER-FILE
Generate an include of the named header file that might be needed
for common type defintions.
.It Fl Fl version
.It Fl Fl help
.El
.Sh 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.