PyASN1 reference manual

written by Ilya Etingof, 2011-2012

Free and open-source pyasn1 library makes it easier for programmers and network engineers to develop, debug and experiment with ASN.1-based protocols using Python programming language as a tool.

Abstract Syntax Notation One (ASN.1) is a set of ITU standards concered with provisioning instrumentation for developing data exchange protocols in a robust, clear and interoperabable way for various IT systems and applications. Most of the efforts are targeting the following areas:

• Data structures: the standard introduces a collection of basic data types (similar to integers, bits, strings, arrays and records in a programming language) that can be used for defining complex, possibly nested data structures representing domain-specific data units.
• Serialization protocols: domain-specific data units expressed in ASN.1 types could be converted into a series of octets for storage or transmission over the wire and then recovered back into their structured form on the receiving end. This process is immune to various hardware and software related dependencies.
• Data description language: could be used to describe particular set of domain-specific data structures and their relationships. Such a description could be passed to an ASN.1 compiler for automated generation of program code that represents ASN.1 data structures in language-native environment and handles data serialization issues.

This tutorial and algorithms, implemented by pyasn1 library, are largely based on the information read in the book ASN.1 - Communication between heterogeneous systems by Olivier Dubuisson. Another relevant resource is A Layman's Guide to a Subset of ASN.1, BER, and DER by Burton S. Kaliski. It's advised to refer to these books for more in-depth knowledge on the subject of ASN.1.

As of this writing, pyasn1 library implements most of standard ASN.1 data structures in a rather detailed and feature-rich manner. Another highly important capability of the library is its data serialization facilities. The last component of the standard - ASN.1 compiler is planned for implementation in the future.

Table of contents

• 1. Data model for ASN.1 types
• 1.1 Scalar types
• 1.1.1 Boolean type
• 1.1.2 Null type
• 1.1.3 Integer type
• 1.1.4 Enumerated type
• 1.1.5 Real type
• 1.1.6 Bit string type
• 1.1.7 OctetString type
• 1.1.8 ObjectIdentifier type
• 1.1.9 Character string types
• 1.1.10 Useful types
• 1.2 Tagging
• 1.3 Constructed types
• 1.3.1 Sequence and Set types
• 1.3.2 SequenceOf and SetOf types
• 1.3.3 Choice type
• 1.3.4 Any type
• 1.4 Subtype constraints
• 1.4.1 Single value constraint
• 1.4.2 Value range constraint
• 1.4.3 Size constraint
• 1.4.4 Alphabet constraint
• 1.4.5 Constraint combinations
• 1.5 Types relationships
• 2. Codecs
• 2.1 Encoders
• 2.2 Decoders
• 2.2.1 Decoding untagged types
• 2.2.2 Ignoring unknown types

Although pyasn1 software is almost a decade old and used in many production environments, it still may have bugs and non-implemented pieces. Anyone who happens to run into such defect is welcome to complain to pyasn1 mailing list or better yet fix the issue and send me the patch.

Typically, pyasn1 is used for building arbitrary protocol support into various applications. This involves manual translation of ASN.1 data structures into their pyasn1 implementations. To save time and effort, data structures for some of the popular protocols are pre-programmed and kept for further re-use in form of the pyasn1-modules package. For instance, many structures for PKI (X.509, PKCS#*, CRMF, OCSP), LDAP and SNMP are present. Applications authors are advised to import and use relevant modules from that package whenever needed protocol structures are already there. New protocol modules contributions are welcome.

And finally, the latest pyasn1 package revision is available for free download from project home and also from the Python package repository.