About

A Python package for ASN.1 parsing, encoding and decoding.

This project is under development and does only support a subset of the ASN.1 specification syntax.

Supported codecs:

• Basic Encoding Rules (BER)
• Distinguished Encoding Rules (DER)
• Generic String Encoding Rules (GSER)
• JSON Encoding Rules (JER)
• Basic Octet Encoding Rules (OER)
• Aligned Packed Encoding Rules (PER)
• Unaligned Packed Encoding Rules (UPER)
• XML Encoding Rules (XER)

Miscellaneous features:

• C source code generator for OER and UPER (with some limitations).

TODOs:

• Improve the C generator and add other supported languages and preferably

a plugin system to allow for easy addition of target languages.

Project homepage: https://github.com/boxtheta/asn1tools-ext

Documentation: TODO: add docs url

Known limitations

• The CLASS keyword (X.681) and its friends are not yet supported.
• Parametrization (X.683) is not yet supported.
• The EMBEDDED PDV type is not yet supported.
• The ANY and ANY DEFINED BY types are not supported. They were removed from the ASN.1 standard 1994.
• WITH COMPONENT and WITH COMPONENTS constraints are ignored, except for OER REAL.
• The DURATION type is not yet supported.

Installation

pip install asn1tools_ext

Example Usage

This is an example ASN.1 specification defining the messages of a fictitious Foo protocol (based on the FooProtocol on Wikipedia).

Foo DEFINITIONS ::= BEGIN

    Question ::= SEQUENCE {
        id        INTEGER,
        question  IA5String
    }

    Answer ::= SEQUENCE {
        id        INTEGER,
        answer    BOOLEAN
    }

END

Scripting

Compile the ASN.1 specification, and encode and decode a question using the default codec (BER).

>>> import asn1tools
>>> foo = asn1tools.compile_files('tests/files/foo.asn')
>>> encoded = foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
>>> encoded
bytearray(b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
>>> foo.decode('Question', encoded)
{'id': 1, 'question': 'Is 1+1=3?'}

The same ASN.1 specification, but using the PER codec.

>>> import asn1tools
>>> foo = asn1tools.compile_files('tests/files/foo.asn', 'per')
>>> encoded = foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
>>> encoded
bytearray(b'\x01\x01\tIs 1+1=3?')
>>> foo.decode('Question', encoded)
{'id': 1, 'question': 'Is 1+1=3?'}

See the examples folder for additional examples.

CLI will be redesigned and placed under another package

Limitations by design:

• Only the types BOOLEAN, INTEGER, NULL, OCTET STRING, BIT STRING, ENUMERATED, SEQUENCE, SEQUENCE OF, and CHOICE are supported. The OER generator also supports REAL.
• All types must have a known maximum size, i.e. INTEGER (0..7), OCTET STRING (SIZE(12)).
• INTEGER must be 64 bits or less.
• REAL must be IEEE 754 binary32 or binary64. binary32 is generated as float and binary64 as double.
• Recursive types are not supported.

Known limitations:

• Extension additions (...) are only supported in the OER generator. See compact_extensions_uper for how to make UPER CHOICE and SEQUENCE extendable without using ....
• Named numbers in ENUMERATED are not yet supported.

Other OER and/or UPER C code generators:

• https://github.com/vlm/asn1c
• https://github.com/ttsiodras/asn1scc

See the benchmark example for a comparison of asn1c, asn1scc and asn1tools.

Contributing

1. Fork the repository.

2. Install prerequisites.

   pip install -r requirements.txt
   

3. Implement the new feature or bug fix.

4. Implement test case(s) to ensure that future changes do not break legacy.

5. Run the tests.

   make test
   

6. Create a pull request.

Specifications

ASN.1 specifications released by ITU and IETF.

General

• X.680: Specification of basic notation
• X.681: Information object specification
• X.682: Constraint specification
• X.683: Parameterization of ASN.1 specifications

Encodings

• X.690: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)
• X.691: Specification of Packed Encoding Rules (PER)
• X.693: XML Encoding Rules (XER)
• X.696: Specification of Octet Encoding Rules (OER)
• RFC 3641: Generic String Encoding Rules (GSER) for ASN.1
• Overview of the JSON Encoding Rules (JER)