README.md
1
2ASN.1 library for Python
3------------------------
4[](https://pypi.org/project/pyasn1)
5[](https://pypi.org/project/pyasn1/)
6[](https://secure.travis-ci.org/etingof/pyasn1)
7[](https://codecov.io/github/etingof/pyasn1)
8[](https://raw.githubusercontent.com/etingof/pyasn1/master/LICENSE.txt)
9
10This is a free and open source implementation of ASN.1 types and codecs
11as a Python package. It has been first written to support particular
12protocol (SNMP) but then generalized to be suitable for a wide range
13of protocols based on
14[ASN.1 specification](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.208-198811-W!!PDF-E&type=items).
15
16Features
17--------
18
19* Generic implementation of ASN.1 types (X.208)
20* Standards compliant BER/CER/DER codecs
21* Dumps/loads ASN.1 structures from Python types
22* 100% Python, works with Python 2.4 up to Python 3.7
23* MT-safe
24* Contributed ASN.1 compiler [Asn1ate](https://github.com/kimgr/asn1ate)
25
26Why using pyasn1
27----------------
28
29ASN.1 solves the data serialisation problem. This solution was
30designed long ago by the wise Ancients. Back then, they did not
31have the luxury of wasting bits. That is why ASN.1 is designed
32to serialise data structures of unbounded complexity into
33something compact and efficient when it comes to processing
34the data.
35
36That probably explains why many network protocols and file formats
37still rely on the 30+ years old technology. Including a number of
38high-profile Internet protocols and file formats.
39
40Quite a number of books cover the topic of ASN.1.
41[Communication between heterogeneous systems](http://www.oss.com/asn1/dubuisson.html)
42by Olivier Dubuisson is one of those high quality books freely
43available on the Internet.
44
45The pyasn1 package is designed to help Python programmers tackling
46network protocols and file formats at the comfort of their Python
47prompt. The tool struggles to capture all aspects of a rather
48complicated ASN.1 system and to represent it on the Python terms.
49
50How to use pyasn1
51-----------------
52
53With pyasn1 you can build Python objects from ASN.1 data structures.
54For example, the following ASN.1 data structure:
55
56```bash
57Record ::= SEQUENCE {
58 id INTEGER,
59 room [0] INTEGER OPTIONAL,
60 house [1] INTEGER DEFAULT 0
61}
62```
63
64Could be expressed in pyasn1 like this:
65
66```python
67class Record(Sequence):
68 componentType = NamedTypes(
69 NamedType('id', Integer()),
70 OptionalNamedType(
71 'room', Integer().subtype(
72 implicitTag=Tag(tagClassContext, tagFormatSimple, 0)
73 )
74 ),
75 DefaultedNamedType(
76 'house', Integer(0).subtype(
77 implicitTag=Tag(tagClassContext, tagFormatSimple, 1)
78 )
79 )
80 )
81```
82
83It is in the spirit of ASN.1 to take abstract data description
84and turn it into a programming language specific form.
85Once you have your ASN.1 data structure expressed in Python, you
86can use it along the lines of similar Python type (e.g. ASN.1
87`SET` is similar to Python `dict`, `SET OF` to `list`):
88
89```python
90>>> record = Record()
91>>> record['id'] = 123
92>>> record['room'] = 321
93>>> str(record)
94Record:
95 id=123
96 room=321
97>>>
98```
99
100Part of the power of ASN.1 comes from its serialisation features. You
101can serialise your data structure and send it over the network.
102
103```python
104>>> from pyasn1.codec.der.encoder import encode
105>>> substrate = encode(record)
106>>> hexdump(substrate)
10700000: 30 07 02 01 7B 80 02 01 41
108```
109
110Conversely, you can turn serialised ASN.1 content, as received from
111network or read from a file, into a Python object which you can
112introspect, modify, encode and send back.
113
114```python
115>>> from pyasn1.codec.der.decoder import decode
116>>> received_record, rest_of_substrate = decode(substrate, asn1Spec=Record())
117>>>
118>>> for field in received_record:
119>>> print('{} is {}'.format(field, received_record[field]))
120id is 123
121room is 321
122house is 0
123>>>
124>>> record == received_record
125True
126>>> received_record.update(room=123)
127>>> substrate = encode(received_record)
128>>> hexdump(substrate)
12900000: 30 06 02 01 7B 80 01 7B
130```
131
132The pyasn1 classes struggle to emulate their Python prototypes (e.g. int,
133list, dict etc.). But ASN.1 types exhibit more complicated behaviour.
134To make life easier for a Pythonista, they can turn their pyasn1
135classes into Python built-ins:
136
137```python
138>>> from pyasn1.codec.native.encoder import encode
139>>> encode(record)
140{'id': 123, 'room': 321, 'house': 0}
141```
142
143Or vice-versa -- you can initialize an ASN.1 structure from a tree of
144Python objects:
145
146```python
147>>> from pyasn1.codec.native.decoder import decode
148>>> record = decode({'id': 123, 'room': 321, 'house': 0}, asn1Spec=Record())
149>>> str(record)
150Record:
151 id=123
152 room=321
153>>>
154```
155
156With ASN.1 design, serialisation codecs are decoupled from data objects,
157so you could turn every single ASN.1 object into many different
158serialised forms. As of this moment, pyasn1 supports BER, DER, CER and
159Python built-ins codecs. The extremely compact PER encoding is expected
160to be introduced in the upcoming pyasn1 release.
161
162More information on pyasn1 APIs can be found in the
163[documentation](http://snmplabs.com/pyasn1/),
164compiled ASN.1 modules for different protocols and file formats
165could be found in the pyasn1-modules
166[repo](https://github.com/etingof/pyasn1-modules).
167
168How to get pyasn1
169-----------------
170
171The pyasn1 package is distributed under terms and conditions of 2-clause
172BSD [license](http://snmplabs.com/pyasn1/license.html). Source code is freely
173available as a GitHub [repo](https://github.com/etingof/pyasn1).
174
175You could `pip install pyasn1` or download it from [PyPI](https://pypi.org/project/pyasn1).
176
177If something does not work as expected,
178[open an issue](https://github.com/etingof/pyasn1/issues) at GitHub or
179post your question [on Stack Overflow](https://stackoverflow.com/questions/ask)
180or try browsing pyasn1
181[mailing list archives](https://sourceforge.net/p/pyasn1/mailman/pyasn1-users/).
182
183Copyright (c) 2005-2019, [Ilya Etingof](mailto:etingof@gmail.com).
184All rights reserved.
185
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}