10.0.0.21 Git - asn2quickder/blob - README.txt

   1 asn1ate -- ASN.1 translation library.
   2 Copyright 2013-2015 Schneider Electric Buildings AB
   3
   4 Introduction
   5 ------------
   6
   7 ``asn1ate`` is a Python library for translating ASN.1 into other forms.
   8 It is intended for code generation from formal ASN.1 definitions, and
   9 code generators for ``pyasn1`` as well as ``Quick DER`` are included.
  10
  11 ``asn1ate`` is released under a 3-clause BSD license. For details, see
  12 LICENSE.txt.
  13
  14
  15 Caveat
  16 ------
  17
  18 This is very much an alpha-quality prototype. Things that need doing:
  19
  20 * Regression test suite
  21 * HACK/TODO/BUGs need to be fixed
  22 * ASN.1 grammar is very incomplete in some places. Known issues:
  23
  24   - Constraint syntax is currently limited to simple value range constraints (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 53)
  25   - Reference syntax is not accepted at all (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 74)
  26
  27 * Improve parser error handling/reporting
  28 * Allow for semantic analysis, e.g. validity check, warnings for problematic
  29   constructs, etc.
  30
  31
  32 Usage with pyasn1
  33 -----------------
  34
  35 The immediate use of ``asn1ate`` is to generate ``pyasn1`` definitions from
  36 ASN.1 definitions. The command to do this is::
  37
  38   $ python .../asn1ate/pyasn1gen.py source.asn1
  39
  40 It will print the ``pyasn1`` equivalent of ``source.asn1`` to stdout.
  41
  42
  43 Usage with Quick DER
  44 --------------------
  45
  46 Quick DER is a library found on https://github.com/vanrein/quick-der
  47 A separate generator exists in ``asn1ate`` to create the parser bytecode
  48 and overlay structures for this format.  The command to do this is::
  49
  50   $ python .../asn1ate/asn2quickder.py source.asn1
  51
  52 It will store an include file suitable for use with ``Quick DER`` in ``source.h``,
  53 which is the source file name with its extension changed to ``.h``.
  54
  55 This tool can be used for your personal ASN.1 projects, but one purpose of
  56 Quick DER is to supply developers with a toolkit that installs header files
  57 for commonly used DER formats, that can be simply included as
  58
  59   #include <quick-der/rfc5280.h>
  60
  61 When building Quick DER, such header files are constructed for the ASN.1
  62 files included in the Quick DER package, and they are installed alongside
  63 the rest of Quick DER.  That use of the `asn2quickder` backend could be
  64 considered a "build-time" dependency of Quick DER.
  65
  66
  67 Dependencies
  68 ------------
  69
  70 The only third-party dependency is ``pyparsing``.
  71
  72 Although ``asn1ate`` was initially developed on Python 3.2, it has been tested
  73 with Python 2.7 and should port to older Python versions easily. Latest release
  74 tested with:
  75
  76 * Python 3.4.0
  77 * Python 2.7.3
  78
  79
  80 Design notes
  81 ------------
  82
  83 The ``asn1ate`` package is designed along the same lines as a compiler with a
  84 driver, a parser, a semantic model and a convention for code generators.
  85
  86 * ``parser.py`` -- a tokenizing parser for ASN.1 per X.680. It currently
  87   recognizes a naive sub-set of X.680
  88 * ``sema.py`` -- a semantic ASN.1 object model, which can be constructed from
  89   the AST generated by ``parser.py``
  90 * ``support/pygen.py`` -- a support library for generating Python code.
  91 * ``pyasn1gen.py`` -- a code generator to transform a semantic model into
  92   ``pyasn1`` syntax. This can be used as a script in which case it will dump
  93   output to stdout.
  94 * ``asn2quickder.py`` -- a code generator to transform a semantic model into
  95   ``Quick DER`` include file syntax.  This can be used as a command.
  96
  97 The ASN.1 parser is very ad-hoc, I've experimented with the grammar until I
  98 found something that accepted our proprietary ASN.1 definition. It's based on
  99 ``pyparsing`` but sets up parse actions to build an annotated AST. Every node of
 100 interest is annotated with a string denoting its type, e.g. ``Identifier``,
 101 ``TypeAssignment``, etc. I've tried to stay with token types as named in X.680,
 102 but added custom ones or suppressed others, as necessary to get the AST in a
 103 useful shape.
 104
 105 Annotated tokens are represented by a simple class containing the type name and
 106 a list of children (called ``elements``) which may be annotated tokens, lists or
 107 simple values. This gives a very discoverable tree structure, but there are
 108 probably cleaner AST representations we could use. Patches welcome.
 109
 110 ``asn1ate.sema`` is an object model that represents ASN.1 constructs. It
 111 describes everything from type assignments to default values and tags, but still
 112 only the parts of ASN.1 we happen to use here. Most of the logic revolves around
 113 transforming the AST produced by ``asn1ate.parser`` into a more semantic model
 114 with proper Python objects.
 115
 116 Codegen is designed to be extensible. In-house we have a set of code generators
 117 to build an entire protocol stack based on an ASN.1 source, but ``asn1ate`` only
 118 includes the generally useful one, ``asn1ate.pyasn1gen``.
 119
 120 The most notable members of ``asn1ate.support`` are probably the
 121 ``PythonWriter`` and ``PythonFragment`` classes, which simplify generation of
 122 correctly indented Python code.