source4/heimdal/lib/asn1/asn1_compile.1

   1 .\" Copyright (c) 2019 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id$
  33 .\"
  34 .Dd February 22, 2021
  35 .Dt ASN1_COMPILE 1
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm asn1_compile
  39 .Nd compile ASN.1 modules
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Bk -words
  43 .Op Fl Fl template
  44 .Op Fl Fl prefix-enum
  45 .Op Fl Fl enum-prefix=PREFIX
  46 .Op Fl Fl encode-rfc1510-bit-string
  47 .Op Fl Fl decode-dce-ber
  48 .Op Fl Fl support-ber
  49 .Op Fl Fl preserve-binary=TYPE-NAME
  50 .Op Fl Fl sequence=TYPE-NAME
  51 .Op Fl Fl decorate=TYPE-NAME:FIELD-TYPE:field-name[?]
  52 .Op Fl Fl one-code-file
  53 .Op Fl Fl gen-name=NAME
  54 .Op Fl Fl option-file=FILE
  55 .Op Fl Fl original-order
  56 .Op Fl Fl no-parse-units
  57 .Op Fl Fl type-file=C-HEADER-FILE
  58 .Op Fl Fl version
  59 .Op Fl Fl help
  60 .Op Ar FILE.asn1 Op Ar NAME
  61 .Ek
  62 .Sh DESCRIPTION
  63 .Nm
  64 Compiles an ASN.1 module into C source code and header files.
  65 .Pp
  66 Options supported:
  67 .Bl -tag -width Ds
  68 .It Fl Fl template
  69 Use the
  70 .Dq template
  71 backend instead of the
  72 .Dq codegen
  73 backend (which is the default backend).
  74 The template backend generates
  75 .Dq templates
  76 which are akin to bytecode, and which are interpreted at
  77 run-time.
  78 The codegen backend generates C code for all functions directly,
  79 with no template interpretation.
  80 The template backend scales better than the codegen backend
  81 because as we add support for more encoding rules the templates
  82 stay mostly the same, thus scaling linearly with size of module.
  83 Whereas the codegen backend scales linear with the product of
  84 module size and number of encoding rules supported.
  85 More importantly, currently only the template backend supports
  86 automatic decoding of open types via X.681/X.682/X.683
  87 annotations.
  88 .It Fl Fl prefix-enum
  89 This option should be removed because ENUMERATED types should
  90 always have their labels prefixed.
  91 .It Fl Fl enum-prefix=PREFIX
  92 This option should be removed because ENUMERATED types should
  93 always have their labels prefixed.
  94 .It Fl Fl encode-rfc1510-bit-string
  95 Use RFC1510, non-standard handling of
  96 .Dq BIT STRING
  97 types.
  98 .It Fl Fl decode-dce-ber
  99 .It Fl Fl support-ber
 100 .It Fl Fl preserve-binary=TYPE-NAME
 101 Generate
 102 .Sq _save
 103 fields in structs to preserve the original encoding of some
 104 sub-value.
 105 This is useful for cryptographic applications to avoid having to
 106 re-encode values to check signatures, etc.
 107 .It Fl Fl sequence=TYPE-NAME
 108 Generate add/remove functions for
 109 .Sq SET OF
 110 and
 111 .Sq SEQUENCE OF
 112 types.
 113 .It Fl Fl decorate=TYPE-NAME:FIELD-TYPE:field-name[?]
 114 Add to the
 115 .Va TYPE-NAME
 116 SET or SEQUENCE type a field of the given
 117 .Va FIELD-TYPE
 118 and
 119 .Va field-name ,
 120 but do not encode or decode this field.
 121 If the
 122 .Va field-name
 123 ends in a question mark, then treat the field as OPTIONAL for
 124 the purposes of copy/free function stubs.
 125 This is useful for adding fields to existing types that can be used
 126 for internal bookkeeping but which do not affect interoperability
 127 because they are not encoded.
 128 .It Fl Fl one-code-file
 129 Generate a single source code file.
 130 Otherwise a separate code file will be generated for every type.
 131 .It Fl Fl gen-name=NAME
 132 Use
 133 .Ar NAME
 134 to form the names of the files generated.
 135 .It Fl Fl option-file=FILE
 136 Take additional command-line options from
 137 .Ar FILE .
 138 .It Fl Fl original-order
 139 Attempt to preserve the original order of type definition in the
 140 ASN.1 module.
 141 By default the compiler generates types in a topological sort
 142 order.
 143 .It Fl Fl no-parse-units
 144 Do not generate to-int / from-int functions for enumeration
 145 types.
 146 .It Fl Fl type-file=C-HEADER-FILE
 147 Generate an include of the named header file that might be needed
 148 for common type defintions.
 149 .It Fl Fl version
 150 .It Fl Fl help
 151 .El