|coverage|_ |codecov|_ |nala|_
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:
Miscellaneous features:
C source code generator for OER and UPER (with some limitations).Project homepage: https://github.com/eerimoq/asn1tools
Documentation: http://asn1tools.readthedocs.org/en/latest
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.
.. code-block:: python
pip install asn1tools
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
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.
The shell subcommand ^^^^^^^^^^^^^^^^^^^^
Use the command line shell to convert data between given formats. The default input codec is BER and output codec is GSER (produces human readable text).
.. code-block:: text
asn1tools shell
Welcome to the asn1tools shell!
$ help Commands: compile convert exit help $ compile tests/files/foo.asn $ convert Question 300e0201011609497320312b313d333f question Question ::= { id 1, question "Is 1+1=3?" } $ compile --output-codec xer tests/files/foo.asn $ convert Question 300e0201011609497320312b313d333f 1 Is 1+1=3? $ compile -o uper tests/files/foo.asn $ convert Question 300e0201011609497320312b313d333f 01010993cd03156c5eb37e $ exit
The convert subcommand ^^^^^^^^^^^^^^^^^^^^^^
Convert given encoded Question from BER to GSER (produces human readable text).
.. code-block:: text
asn1tools convert tests/files/foo.asn Question 300e0201011609497320312b313d333f question Question ::= { id 1, question "Is 1+1=3?" }
Convert given encoded Question from UPER to XER (xml).
.. code-block:: text
asn1tools convert -i uper -o xer tests/files/foo.asn Question 01010993cd03156c5eb37e
<id>1</id>
<question>Is 1+1=3?</question>
Convert given encoded Question from UPER to JER (json).
.. code-block:: text
asn1tools convert -i uper -o jer tests/files/foo.asn Question 01010993cd03156c5eb37e { "id": 1, "question": "Is 1+1=3?" }
Continuously convert encoded Questions read from standard input. Any line that cannot be converted is printed as is, in this example the dates.
.. code-block:: text
cat encoded.txt 2018-02-24 11:22:09 300e0201011609497320312b313d333f 2018-02-24 11:24:15 300e0201021609497320322b323d353f cat encoded.txt | asn1tools convert tests/files/foo.asn Question - 2018-02-24 11:22:09 question Question ::= { id 1, question "Is 1+1=3?" } 2018-02-24 11:24:15 question Question ::= { id 2, question "Is 2+2=5?" }
The convert subcommand with a cache ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Convert given encoded PCCH-Message from UPER to GSER with the
--cache-dir option set to my_cache. Using a cache
significantly reduces the command execution time after the first call.
.. code-block:: text
time asn1tools convert --cache-dir my_cache -i uper tests/files/3gpp/rrc_8_6_0.asn PCCH-Message 28 pcch-message PCCH-Message ::= { message c1 : paging : { systemInfoModification true, nonCriticalExtension { } } }
real 0m2.090s user 0m1.977s sys 0m0.032s
time asn1tools convert --cache-dir my_cache -i uper tests/files/3gpp/rrc_8_6_0.asn PCCH-Message 28 pcch-message PCCH-Message ::= { message c1 : paging : { systemInfoModification true, nonCriticalExtension { } } }
real 0m0.276s user 0m0.197s sys 0m0.026s
The parse subcommand ^^^^^^^^^^^^^^^^^^^^
Parse given ASN.1 specification and write it as a Python dictionary to given file. Use the created file to convert given encoded Question from BER to GSER (produces human readable text). The conversion is significantly faster than passing .asn-file(s) to the convert subcommand, especially for larger ASN.1 specifications.
.. code-block:: text
asn1tools parse tests/files/foo.asn foo.py asn1tools convert foo.py Question 300e0201011609497320312b313d333f question Question ::= { id 1, question "Is 1+1=3?" }
The generate C source subcommand ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Generate OER or UPER C source code from an ASN.1 specification.
No dynamic memory is used in the generated code. To achieve this all
types in the ASN.1 specification must have a known maximum size,
i.e. INTEGER (0..7), OCTET STRING (SIZE(12)), etc.
Below is an example generating OER C source code from
tests/files/c_source/c_source.asn_.
.. code-block:: text
asn1tools generate_c_source --namespace oer tests/files/c_source/c_source.asn Successfully generated oer.h and oer.c.
The same as above, but generate UPER C source code instead of OER.
.. code-block:: text
asn1tools generate_c_source --codec uper --namespace uper tests/files/c_source/c_source.asn Successfully generated uper.h and uper.c.
The same as the first example, but also generate fuzz testing C source
code for libFuzzer_.
.. code-block:: text
asn1tools generate_c_source --namespace oer --generate-fuzzer tests/files/c_source/c_source.asn Successfully generated oer.h and oer.c. Successfully generated oer_fuzzer.c and oer_fuzzer.mk.
Run "make -f oer_fuzzer.mk" to build and run the fuzzer. Requires a recent version of clang.
See oer.h, oer.c, uper.h, uper.c, oer_fuzzer.c_ and
oer_fuzzer.mk_ for the contents of the generated files.
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:
See the benchmark example_ for a comparison of asn1c, asn1scc
and asn1tools.
#. 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.
ASN.1 specifications released by ITU and IETF.
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>_
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
FAQs
ASN.1 parsing, encoding and decoding.
We found that asn1tools demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.