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