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 |