README.md

   1 # About
   2
   3 ASN.1 to C compiler takes the ASN.1 module files (example) and generates
   4 the C++ compatible C source code. That code can be used to serialize
   5 the native C structures into compact and unambiguous BER/OER/PER/XER-based
   6 data files, and deserialize the files back.
   7
   8 Various ASN.1 based formats are widely used in the industry,
   9 such as to encode the X.509 certificates employed in the HTTPS handshake,
  10 to exchange control data between mobile phones and cellular networks,
  11 to perform car-to-car communication in intelligent transportation networks.
  12
  13 The ASN.1 family of standards is large and complex, and no open source
  14 compiler supports it in its entirety.
  15 The asn1c is arguably the most evolved open source ASN.1 compiler.
  16
  17 # ASN.1 Transfer Syntaxes
  18 <details>
  19 <summary>ASN.1 encodings interoperability table</summary>
  20
  21 The ASN.1 family of standards define a number of ways to encode data,
  22 including byte-oriented (e.g., BER), bit-oriented (e.g., PER),
  23 and textual (e.g., XER). Some encoding variants (e.g., DER) are just stricter
  24 variants of the more general encodings (e.g., BER).
  25
  26 The interoperability table below specifies which API functions can be used
  27 to exchange data in a compatible manner. If you need to _produce_ data
  28 conforming to the standard specified in the column 1,
  29 use the API function in the column 2.
  30 If you need to _process_ data conforming to the standard(s) specified in the
  31 column 3, use the API function specified in column 4.
  32 See the [doc/asn1c-usage.pdf](doc/asn1c-usage.pdf) for details.
  33
  34 Encoding       | API function       | Understood by | API function
  35 -------------- | ------------------ | ------------- | -------------
  36 BER            | der_encode()       | BER           | ber_decode()
  37 DER            | der_encode()       | DER, BER      | ber_decode()
  38 CER            | _not supported_    | CER, BER      | ber_decode()
  39 BASIC-OER      | oer_encode()       | *-OER         | oer_decode()
  40 CANONICAL-OER  | oer_encode()       | *-OER         | oer_decode()
  41 BASIC-UPER     | uper_encode()      | *-UPER        | uper_decode()
  42 CANONICAL-UPER | uper_encode()      | *-UPER        | uper_decode()
  43 *-APER         | _not supported_    | *-APER        | _not supported_
  44 BASIC-XER      | xer_encode(XER_F_BASIC)    | *-XER | xer_decode()
  45 CANONICAL-XER  | xer_encode(XER_F_CANONICAL)| *-XER | xer_decode()
  46
  47 *) Asterisk means both BASIC and CANONICAL variants.
  48 </details>
  49
  50 # Build and Install
  51
  52 If you haven't installed the asn1c yet, read the [INSTALL.md](INSTALL.md) file
  53 for a short installation guide.
  54
  55 [![Build Status](https://travis-ci.org/vlm/asn1c.svg?branch=master)](https://travis-ci.org/vlm/asn1c)
  56
  57 # Documentation
  58
  59 For the list of asn1c command line options, see `asn1c -h` or `man asn1c`.
  60
  61 The comprehensive documentation on this compiler is in [doc/asn1c-usage.pdf](doc/asn1c-usage.pdf).
  62
  63 Please also read the [FAQ](FAQ) file.
  64
  65 An excellent book on ASN.1 is written by Olivier Dubuisson:
  66 "ASN.1 Communication between heterogeneous systems", ISBN:0-12-6333361-0.
  67
  68 # Quick start
  69
  70 (also check out [doc/asn1c-quick.pdf](doc/asn1c-quick.pdf))
  71
  72 After installing the compiler (see [INSTALL.md](INSTALL.md)), you may use
  73 the asn1c command to compile the ASN.1 specification:
  74
  75     asn1c <module.asn1>                         # Compile module
  76
  77 If several specifications contain interdependencies, all of them must be
  78 specified at the same time:
  79
  80     asn1c <module1.asn1> <module2.asn1> ...     # Compile interdependent modules
  81
  82 The asn1c source tarball contains the [examples/](examples/) directory
  83 with several ASN.1 modules and a [script](examples/crfc2asn1.pl)
  84 to extract the ASN.1 modules from RFC documents.
  85 Refer to the [examples/README](examples/README) file in that directory.
  86
  87 To compile the X.509 PKI module:
  88
  89     ./asn1c/asn1c -P ./examples/rfc3280-*.asn1  # Compile-n-print
  90
  91 In this example, the **-P** option is to print the compiled text on the
  92 standard output. The default behavior is that asn1c compiler creates
  93 multiple .c and .h files for every ASN.1 type found inside the specified
  94 ASN.1 modules.
  95
  96 The compiler's **-E** and **-EF** options are used for testing the parser and
  97 the semantic fixer, respectively. These options will instruct the compiler
  98 to dump out the parsed (and fixed) ASN.1 specification as it was
  99 "understood" by the compiler. It might be useful for checking
 100 whether a particular syntactic construction is properly supported
 101 by the compiler.
 102
 103     asn1c -EF <module-to-test.asn1>             # Check semantic validity
 104
 105 # Model of operation
 106
 107 The asn1c compiler works by processing the ASN.1 module specifications
 108 in several stages:
 109
 110 1. During the first stage, the ASN.1 file is parsed.
 111    (Parsing produces an ASN.1 syntax tree for the subsequent levels)
 112 2. During the second stage, the syntax tree is "fixed".
 113    (Fixing is a process of checking the tree for semantic errors,
 114    accompanied by the tree transformation into the canonical form)
 115 3. During the third stage, the syntax tree is compiled into the target language.
 116
 117 There are several command-line options reserved for printing the results
 118 after each stage of operation:
 119
 120     <parser> => print                                       (-E)
 121     <parser> => <fixer> => print                            (-E -F)
 122     <parser> => <fixer> => <compiler> => print              (-P)
 123     <parser> => <fixer> => <compiler> => save-compiled      [default]
 124
 125
 126 --
 127 Lev Walkin
 128 vlm@lionet.info