pyasn1

Warnings

• breaking decode() always returns a 2-tuple (asn1Object, remainingSubstrate). Ignoring the second element or trying to use the result directly as the decoded value is the single most common runtime bug.
  Fix: Always unpack: `value, remainder = decode(substrate, asn1Spec=MyType())`; check `remainder == b''` to detect trailing garbage.
• breaking Python 2 and Python < 3.8 support dropped in v0.6.0. The PyPI package now requires Python >=3.8.
  Fix: Upgrade to Python 3.8+ and pin pyasn1>=0.6.0. Remove any Python 2 compatibility shims (six, future) from your codebase.
• breaking SequenceOf/SetOf instances are no longer auto-initialised as value objects on instantiation (changed in 0.4.x). Code that tested `if mySeqOf:` or iterated an empty SequenceOf immediately after construction will silently get wrong results or raise errors.
  Fix: Call `.clear()` on a SequenceOf/SetOf instance to explicitly make it a value object (empty list), or append a component first. Do not assume an empty SequenceOf is a value object.
• breaking The substrateFun callback signature changed in v0.5.0 from non-streaming (v0.4 style) to streaming. The v0.5.1 patch restores transparent compatibility for decoder.decode(), but custom substrateFun callbacks passed to low-level streaming decoders must use the new streaming signature.
  Fix: If passing substrateFun to the top-level `decoder.decode()`, both old and new signatures work as of 0.5.1+. For streaming decoders directly, migrate to the v0.5 streaming callback signature.
• gotcha Without asn1Spec=, the decoder falls back to generic BER decoding and returns untyped Any objects. IMPLICIT tags cannot be decoded without a spec, so fields will silently be missing or mis-typed.
  Fix: Always pass `asn1Spec=MySchemaType()` to decode(). This is mandatory for any schema that uses IMPLICIT or EXPLICIT tagging.
• gotcha Pre-built ASN.1 modules (X.509 RFC 5280, PKCS, SNMP MIBs, etc.) were moved to the separate pyasn1-modules package long ago and are no longer included in pyasn1 itself.
  Fix: Install pyasn1-modules separately: `pip install pyasn1-modules`. Import e.g. `from pyasn1_modules import rfc5280`.
• gotcha pyasn1 types mimic Python built-ins (Integer ≈ int, OctetString ≈ bytes) but comparisons, hashing, and arithmetic can differ subtly. Passing a raw Python int where an Integer() instance is expected often works, but not always — especially inside Sequence field assignment with constraints.
  Fix: Explicitly wrap values: `record['id'] = Integer(123)` rather than relying on implicit coercion. Use `.hasValue()` / `.isValue` to check whether a component has been populated before encoding.

Install

• pip install pyasn1 Core library
• pip install pyasn1 pyasn1-modules With pre-compiled RFC modules (X.509, PKCS, etc.)

Imports

• Integer, OctetString, ObjectIdentifier

  from pyasn1.type.univ import Integer, OctetString, ObjectIdentifier

  All primitive ASN.1 scalar types live in pyasn1.type.univ
• Sequence, SequenceOf, Set, SetOf, Choice

  from pyasn1.type.univ import Sequence, SequenceOf, Set, SetOf, Choice

  Structured/constructed types also in pyasn1.type.univ
• NamedType, OptionalNamedType, DefaultedNamedType, NamedTypes

  from pyasn1.type.namedtype import NamedType, OptionalNamedType, DefaultedNamedType, NamedTypes

  Required when declaring SEQUENCE field names; wrong module is a common ImportError
• Tag, tagClassContext, tagFormatSimple

  from pyasn1.type.tag import Tag, tagClassContext, tagFormatSimple

  Used with .subtype(implicitTag=...) or .subtype(explicitTag=...) for context tagging
• encode (DER)

  from pyasn1.codec.der.encoder import encode

  Use the DER encoder for certificates and strict protocols; BER allows non-canonical forms that some validators reject
• decode (DER)

  from pyasn1.codec.der.decoder import decode

  Always unpack as (value, remainder) — decode() returns a 2-tuple, not just the value
• encode/decode (BER)

  from pyasn1.codec.ber.encoder import encode
  from pyasn1.codec.ber.decoder import decode

  BER is the permissive superset; use for parsing untrusted or legacy inputs where indefinite length is possible
• encode/decode (native Python dicts)

  from pyasn1.codec.native.encoder import encode
  from pyasn1.codec.native.decoder import decode

  Converts pyasn1 objects to/from plain Python dicts/lists/ints; useful for JSON interop
• PyAsn1Error

  from pyasn1.error import PyAsn1Error

  Base exception for all pyasn1 errors; catch this for encoder/decoder failures

Quickstart

Define an ASN.1 SEQUENCE schema, populate it, DER-encode it, then decode it back and verify round-trip equality.

from pyasn1.type.univ import Sequence, Integer
from pyasn1.type.namedtype import NamedType, OptionalNamedType, DefaultedNamedType, NamedTypes
from pyasn1.type.tag import Tag, tagClassContext, tagFormatSimple
from pyasn1.codec.der.encoder import encode
from pyasn1.codec.der.decoder import decode
from pyasn1.error import PyAsn1Error

# 1. Define ASN.1 schema as a Python class
class Record(Sequence):
    componentType = NamedTypes(
        NamedType('id', Integer()),
        OptionalNamedType(
            'room',
            Integer().subtype(implicitTag=Tag(tagClassContext, tagFormatSimple, 0))
        ),
        DefaultedNamedType(
            'house',
            Integer(0).subtype(implicitTag=Tag(tagClassContext, tagFormatSimple, 1))
        ),
    )

# 2. Populate the schema object
record = Record()
record['id'] = 123
record['room'] = 321

# 3. DER-encode to bytes
substrate = encode(record)
print('DER bytes:', substrate.hex())  # e.g. 30070201 7b800201 41

# 4. Decode back — ALWAYS unpack the 2-tuple (value, remainder)
try:
    received, remainder = decode(substrate, asn1Spec=Record())
except PyAsn1Error as exc:
    raise SystemExit(f'Decode failed: {exc}')

assert remainder == b'', 'Unexpected trailing bytes'
assert received['id'] == record['id']
print('Round-trip OK:', received.prettyPrint())