10.0.0.21 Git - asn2quickder/blob - README.txt

   1 asn1ate -- ASN.1 translation library.
   2 Copyright 2013 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 a
   9 code generator for ``pyasn1`` is 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 constructs, etc.
  29
  30
  31 Usage
  32 -----
  33
  34 The immediate use of ``asn1ate`` is to generate ``pyasn1`` definitions from
  35 ASN.1 definitions. The command to do this is::
  36
  37   $ python .../asn1ate/pyasn1gen.py source.asn1
  38
  39 It will print the ``pyasn1`` equivalent of ``source.asn1`` to stdout.
  40
  41
  42 Dependencies
  43 ------------
  44
  45 The only third-party dependency is ``pyparsing``.
  46
  47 Although ``asn1ate`` was initially developed on Python 3.2, it has been tested
  48 with Python 2.7.3 and should port to older Python versions easily.
  49
  50
  51 Design notes
  52 ------------
  53
  54 The ``asn1ate`` package is designed along the same lines as a compiler with a
  55 driver, a parser, a semantic model and a convention for code generators.
  56
  57 * ``parser.py`` -- a tokenizing parser for ASN.1 per X.680. It currently
  58   recognizes a naive sub-set of X.680
  59 * ``sema.py`` -- a semantic ASN.1 object model, which can be constructed from
  60   the AST generated by ``parser.py``
  61 * ``support/pygen.py`` -- a support library for generating Python code.
  62 * ``pyasn1gen.py`` -- a code generator to transform a semantic model into
  63   ``pyasn1`` syntax. This can be used as a script in which case it will dump
  64   output to stdout.
  65
  66 The ASN.1 parser is very ad-hoc, I've experimented with the grammar until I
  67 found something that accepted our proprietary ASN.1 definition. It's based on
  68 ``pyparsing`` but sets up parse actions to build an annotated AST. Every node of
  69 interest is annotated with a string denoting its type, e.g. ``Identifier``,
  70 ``TypeAssignment``, etc. I've tried to stay with token types as named in X.680,
  71 but added custom ones or suppressed others, as necessary to get the AST in a
  72 useful shape.
  73
  74 Annotated tokens are represented by a simple class containing the type name and
  75 a list of children (called ``elements``) which may be annotated tokens, lists or
  76 simple values. This gives a very discoverable tree structure, but there are
  77 probably cleaner AST representations we could use. Patches welcome.
  78
  79 ``asn1ate.sema`` is an object model that represents ASN.1 constructs. It
  80 describes everything from type assignments to default values and tags, but still
  81 only the parts of ASN.1 we happen to use here. Most of the logic revolves around
  82 transforming the AST produced by ``asn1ate.parser`` into a more semantic model
  83 with proper Python objects.
  84
  85 Codegen is designed to be extensible. In-house we have a set of code generators
  86 to build an entire protocol stack based on an ASN.1 source, but ``asn1ate`` only
  87 includes the generally useful one, ``asn1ate.pyasn1gen``.
  88
  89 The most notable members of ``asn1ate.support`` are probably the
  90 ``PythonWriter`` and ``PythonFragment`` classes, which simplify generation of
  91 correctly indented Python code.