asn1tools_ext 0.2.2
ASN.1 parser, compiler and general swiss army knife
Requires Python: >=3.13

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
============

.. code-block:: python

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

.. code-block:: text

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

.. code-block:: python

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

.. code-block:: python

   >>> 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
============

#. Fork the repository.

#. Install prerequisites.

   .. code-block:: text

      pip install -r requirements.txt

#. Implement the new feature or bug fix.

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

#. Run the tests.

   .. code-block:: text

      make test

#. Create a pull request.

Specifications
==============

ASN.1 specifications released by ITU and IETF.

General
-------

- `X.680: Specification of basic notation
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.680-0207.pdf>`_

- `X.681: Information object specification
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.681-0207.pdf>`_

- `X.682: Constraint specification
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.682-0207.pdf>`_

- `X.683: Parameterization of ASN.1 specifications
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.683-0207.pdf>`_

Encodings
---------

- `X.690: Specification of Basic Encoding Rules (BER), Canonical
  Encoding Rules (CER) and Distinguished Encoding Rules (DER)
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf>`_

- `X.691: Specification of Packed Encoding Rules (PER)
  <https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.691-201508-I!!PDF-E&type=items>`_

- `X.693: XML Encoding Rules (XER)
  <https://www.itu.int/ITU-T/studygroups/com17/languages/X.693-0112.pdf>`_

- `X.696: Specification of Octet Encoding Rules (OER)
  <https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.696-201508-I!!PDF-E&type=items>`_

- `RFC 3641: Generic String Encoding Rules (GSER) for ASN.1
  <https://tools.ietf.org/html/rfc3641>`_

- `Overview of the JSON Encoding Rules (JER)
  <http://www.oss.com/asn1/resources/asn1-papers/Overview_of_JER.pdf>`_

.. |coverage| image:: https://coveralls.io/repos/github/eerimoq/asn1tools/badge.svg?branch=master
.. _coverage: https://coveralls.io/github/eerimoq/asn1tools

.. |codecov| image:: https://codecov.io/gh/eerimoq/asn1tools/branch/master/graph/badge.svg
.. _codecov: https://codecov.io/gh/eerimoq/asn1tools

.. |nala| image:: https://img.shields.io/badge/nala-test-blue.svg
.. _nala: https://github.com/eerimoq/nala

.. _ASN.1: https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One

.. _Compile: http://asn1tools.readthedocs.io/en/latest/#asn1tools.compile_files
.. _encode: http://asn1tools.readthedocs.io/en/latest/#asn1tools.compiler.Specification.encode
.. _decode: http://asn1tools.readthedocs.io/en/latest/#asn1tools.compiler.Specification.decode
.. _examples: https://github.com/eerimoq/asn1tools/tree/master/examples

.. _tests/files/c_source/c_source.asn: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/c_source.asn

.. _oer.h: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/oer.h

.. _oer.c: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/oer.c

.. _uper.h: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/uper.h

.. _uper.c: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/uper.c

.. _oer_fuzzer.c: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/oer_fuzzer.c

.. _oer_fuzzer.mk: https://github.com/eerimoq/asn1tools/blob/master/tests/files/c_source/oer_fuzzer.mk

.. _libFuzzer: https://llvm.org/docs/LibFuzzer.html

.. _benchmark example: https://github.com/eerimoq/asn1tools/blob/master/examples/benchmarks/c_source

.. _compact_extensions_uper: https://github.com/eerimoq/asn1tools/blob/master/examples/compact_extensions_uper