A Python library for translating ASN.1 into other forms.
Python Other
Latest commit 67769c1 Sep 11, 2016 @kimgr Codegen for SET OF inline size constraints
Sparked by the earlier report for SEQUENCE OF by @aholtzma.
Permalink
Failed to load latest commit information.
asn1ate Codegen for SET OF inline size constraints Sep 11, 2016
testdata Codegen for SET OF inline size constraints Sep 11, 2016
.gitignore Support size and single-value constraints on some types. Jul 25, 2014
LICENSE.txt Bump copyright years to 2016 Sep 8, 2016
MANIFEST.in
README.txt Bump copyright years to 2016 Sep 8, 2016
basic_test.bat
basic_test.sh Add bash testing script Sep 20, 2013
publish.bat
requirements.txt
setup.py Code linted and PEP8'ed Aug 22, 2016

README.txt

asn1ate -- ASN.1 translation library.
Copyright 2013-2016 Schneider Electric Buildings AB

Introduction
------------

``asn1ate`` is a Python library for translating ASN.1 into other forms.
It is intended for code generation from formal ASN.1 definitions, and a
code generator for ``pyasn1`` is included.

``asn1ate`` is released under a 3-clause BSD license. For details, see
LICENSE.txt.


Caveat
------

This is very much an alpha-quality prototype. Things that need doing:

* Regression test suite
* HACK/TODO/BUGs need to be fixed
* ASN.1 grammar is very incomplete in some places. Known issues:

  - Constraint syntax is currently limited to simple value range constraints (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 53)
  - Reference syntax is not accepted at all (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12.asn, line 74)

* Improve parser error handling/reporting
* Allow for semantic analysis, e.g. validity check, warnings for problematic
  constructs, etc.


Usage
-----

The immediate use of ``asn1ate`` is to generate ``pyasn1`` definitions from
ASN.1 definitions. The command to do this is::

  $ python .../asn1ate/pyasn1gen.py source.asn1

It will print the ``pyasn1`` equivalent of ``source.asn1`` to stdout.


Dependencies
------------

The only third-party dependency is ``pyparsing``.

Although ``asn1ate`` was initially developed on Python 3.2, it has been tested
with Python 2.7 and should port to older Python versions easily. Latest release
tested with:

* Python 3.4.0
* Python 2.7.3


Design notes
------------

The ``asn1ate`` package is designed along the same lines as a compiler with a
driver, a parser, a semantic model and a convention for code generators.

* ``parser.py`` -- a tokenizing parser for ASN.1 per X.680. It currently
  recognizes a naive sub-set of X.680
* ``sema.py`` -- a semantic ASN.1 object model, which can be constructed from
  the AST generated by ``parser.py``
* ``support/pygen.py`` -- a support library for generating Python code.
* ``pyasn1gen.py`` -- a code generator to transform a semantic model into
  ``pyasn1`` syntax. This can be used as a script in which case it will dump
  output to stdout.

The ASN.1 parser is very ad-hoc, I've experimented with the grammar until I
found something that accepted our proprietary ASN.1 definition. It's based on
``pyparsing`` but sets up parse actions to build an annotated AST. Every node of
interest is annotated with a string denoting its type, e.g. ``Identifier``,
``TypeAssignment``, etc. I've tried to stay with token types as named in X.680,
but added custom ones or suppressed others, as necessary to get the AST in a
useful shape.

Annotated tokens are represented by a simple class containing the type name and
a list of children (called ``elements``) which may be annotated tokens, lists or
simple values. This gives a very discoverable tree structure, but there are
probably cleaner AST representations we could use. Patches welcome.

``asn1ate.sema`` is an object model that represents ASN.1 constructs. It
describes everything from type assignments to default values and tags, but still
only the parts of ASN.1 we happen to use here. Most of the logic revolves around
transforming the AST produced by ``asn1ate.parser`` into a more semantic model
with proper Python objects.

Codegen is designed to be extensible. In-house we have a set of code generators
to build an entire protocol stack based on an ASN.1 source, but ``asn1ate`` only
includes the generally useful one, ``asn1ate.pyasn1gen``.

The most notable members of ``asn1ate.support`` are probably the
``PythonWriter`` and ``PythonFragment`` classes, which simplify generation of
correctly indented Python code.