Usage

Note

You can find a complete example in Examples.

The Python-ASN1 API is exposed by a single Python module named asn1. The main interface is provided by the following classes:

• Encoder: Used to encode ASN.1.

• Decoder: Used to decode ASN.1.

• Error: Exception used to signal errors.

Type Mapping

The Python-ASN1 encoder and decoder make a difference between primitive and constructed data types. Primitive data types can be encoded and decoded directly with read() and write() methods. For these types, ASN.1 types are mapped directly to Python types and vice versa, as per the table below:

ASN.1 type	Python type	Default
Boolean	bool	yes
Integer	int	yes
OctetString	bytes	yes
PrintableString	str	yes
Null	None	yes
ObjectIdentifier	bytes	no
Enumerated	int	no

The column default is relevant for encoding only. Because ASN.1 has more data types than Python, the situation arises that one Python type corresponds to multiple ASN.1 types. In this sitution the to be encoded ASN.1 type cannot be determined from the Python type. The solution implemented in Python-ASN1 is that the most frequently used type will be the implicit default, and if another type is desired than that must be specified explicitly through the API.

For constructed types, no type mapping is done at all, even for types where such a mapping would be possible such as the ASN.1 type sequence of which could be mapped to a Python list. For such types a stack based approach is used instead. In this approach, the user needs to explicitly enter/leave the constructed type using the Encoder.enter() and Encoder.leave() methods of the encoder and the Decoder.enter() and Decoder.leave() methods of the decoder.

Encoding

If you want to encode data and retrieve its DER-encoded representation, use code such as:

import asn1

encoder = asn1.Encoder()
encoder.start()
encoder.write('1.2.3', asn1.ObjectIdentifier)
encoded_bytes = encoder.output()

Decoding

If you want to decode ASN.1 from DER or BER encoded bytes, use code such as:

import asn1

decoder = asn1.Decoder()
decoder.start(encoded_bytes)
tag, value = decoder.read()

Constants

A few constants are defined in the asn1 module. The constants immediately below correspond to ASN.1 numbers. They can be used as the nr parameter of the Encoder.write() method, and are returned as the first part of a (nr, typ, cls) tuple as returned by Decoder.peek() and Decoder.read().

Constant	Value (hex)
Boolean	0x01
Integer	0x02
OctetString	0x04
Null	0x05
ObjectIdentifier	0x06
Enumerated	0x0a
Sequence	0x10
Set	0x11

The following constants define the two available encoding types (primitive and constructed) for ASN.1 data types. As above they can be used with the Encoder.write() and are returned by Decoder.peek() and Decoder.read().

Constant	Value (hex)
TypeConstructed	0x20
TypePrimitive	0x00

Finally the constants below define the different ASN.1 classes. As above they can be used with the Encoder.write() and are returned by Decoder.peek() and Decoder.read().

Constant	Value (hex)
ClassUniversal	0x00
ClassApplication	0x40
ClassContext	0x80
ClassPrivate	0xc0