asn1tools_ext 0.2.2

ASN.1 parser, compiler and general swiss army knife

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).

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)