Install & Compatibility
Where this runs
tested against v0.167.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.650s · 21.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.572s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
asn1tools
✓ import asn1tools
This quickstart demonstrates how to compile an ASN.1 specification from a file, then encode Python dictionaries into ASN.1 binary format using the BER codec, and decode the binary data back into Python dictionaries.
import asn1tools
import os
import tempfile
# Define an example ASN.1 specification
asn1_spec = """
Foo DEFINITIONS ::= BEGIN
Question ::= SEQUENCE {
id INTEGER,
question IA5String
}
Answer ::= SEQUENCE {
id INTEGER,
answer BOOLEAN
}
END
"""
# Create a temporary .asn file for the specification
with tempfile.NamedTemporaryFile(mode='w', suffix='.asn', delete=False) as f:
f.write(asn1_spec)
asn_filepath = f.name
try:
# Compile the ASN.1 specification using the default BER codec
# You can specify other codecs like 'per', 'uper', 'xer', etc.
foo = asn1tools.compile_files(asn_filepath, 'ber')
# Encode a Question message
question_data = {'id': 1, 'question': 'Is 1+1=3?'}
encoded_question = foo.encode('Question', question_data)
print(f"Encoded (BER): {encoded_question.hex()}")
# Decode the Question message
decoded_question = foo.decode('Question', encoded_question)
print(f"Decoded: {decoded_question}")
# Example with another message type (Answer)
answer_data = {'id': 1, 'answer': False}
encoded_answer = foo.encode('Answer', answer_data)
print(f"Encoded Answer (BER): {encoded_answer.hex()}")
decoded_answer = foo.decode('Answer', encoded_answer)
print(f"Decoded Answer: {decoded_answer}")
finally:
# Clean up the temporary file
os.remove(asn_filepath)
asn1tools --version
Debug
Known issues
gotchaasn1tools only supports a subset of the full ASN.1 specification syntax. Known unsupported features include the CLASS keyword (X.681), Parametrization (X.683), EMBEDDED PDV, ANY/ANY DEFINED BY types, WITH COMPONENT/WITH COMPONENTS constraints (except for OER REAL), and the DURATION type. Recursive types are also not supported.fixReview the 'Known limitations' in the official documentation and adjust ASN.1 specifications to avoid unsupported features. Parameterized types (e.g., `SetupRelease { ElementTypeParam }`) must be manually expanded in the ASN.1 specification before compilation. affects: All versions
gotchaWhen encoding or decoding, setting `check_constraints=False` will skip validation against ASN.1 type constraints. While this can minimize runtime overhead, it allows the processing of values that do not fulfill the constraints, potentially leading to `DecodeError` exceptions or data corruption later on if the data is malformed.fixAlways use `check_constraints=True` (the default for `decode`) during development and in production where data integrity is critical. Only disable it if performance is absolutely paramount and the data source is fully trusted to adhere to all constraints.
affects: All versions
breakingVersion 0.156.0 introduced support for decoding BER SET and SEQUENCE OF members in any order. Prior to this version, implementations might have relied on a specific order, and decoding data with out-of-order members could have failed or yielded incorrect results.fixIf upgrading from a version older than 0.156.0, review code that processes BER-encoded SET or SEQUENCE OF types to ensure it handles potential reordering of members, if that was previously an implicit expectation. The change generally improves robustness but could alter behavior for non-compliant streams.
affects: <0.156.0
gotchaThe C code generator for OER and UPER has specific limitations, including support only for BOOLEAN, INTEGER, NULL, OCTET STRING, BIT STRING, ENUMERATED, SEQUENCE, SEQUENCE OF, and CHOICE types. All types must have a known maximum size (e.g., INTEGER (0..7)), INTEGERs must be 64 bits or less, and REAL types must be IEEE 754 binary32 or binary64. Extension additions (...) are only supported in the OER generator.fixEnsure that ASN.1 specifications intended for C code generation adhere strictly to these limitations. For UPER, use `compact_extensions_uper` for extendable CHOICE and SEQUENCE without `...`. Avoid named numbers in ENUMERATED for C code generation.
affects: All versions with C code generation
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'asn1tools'
The 'asn1tools' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install asn1tools'.
ImportError: cannot import name 'asn1' from 'cryptography.hazmat.bindings._rust' (unknown location)
The 'cryptography' package is either not installed or is outdated.
fixInstall or upgrade the 'cryptography' package using pip: 'pip install --upgrade cryptography'.
ModuleNotFoundError: No module named 'pyasn1'
The 'pyasn1' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install pyasn1'.
ModuleNotFoundError: No module named 'asn1crypto'
The 'asn1crypto' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install asn1crypto'.
ModuleNotFoundError: No module named 'pysnmp'
The 'pysnmp' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install pysnmp'.
Upgrade
Version history
0.167.0latest on PyPI · released Jul 13, 2024
Audit
Dependencies
pyparsingrequiredRequired for ASN.1 specification parsing.
bitstructrequiredUsed for efficient bit-level operations during encoding/decoding.
prompt_toolkitoptionalUsed by the command-line interface (CLI) for interactive features.
diskcacheoptionalUsed for caching compiled ASN.1 specifications.