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

The package is imported as asn1tools_ext. It also installs an asn1tools alias, so existing code doing import asn1tools keeps working. Do not install it alongside the original asn1tools package, as both provide that module.

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

>>> 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?'}

>>> 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?'}

Contributing

1. Fork the repository.

2. Install prerequisites.

   uv sync

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.

   uv run python -m unittest

6. Run the type checker.

   uv run mypy

7. Create a pull request.

Specifications

ASN.1 specifications released by ITU and IETF.