1 2 ASN.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 10 This is a free and open source implementation of ASN.1 types and codecs 11 as a Python package. It has been first written to support particular 12 protocol (SNMP) but then generalized to be suitable for a wide range 13 of 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 16 Features 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.6 23 * MT-safe 24 * Contributed ASN.1 compiler [Asn1ate](https://github.com/kimgr/asn1ate) 25 26 Why using pyasn1 27 ---------------- 28 29 ASN.1 solves the data serialisation problem. This solution was 30 designed long ago by the wise Ancients. Back then, they did not 31 have the luxury of wasting bits. That is why ASN.1 is designed 32 to serialise data structures of unbounded complexity into 33 something compact and efficient when it comes to processing 34 the data. 35 36 That probably explains why many network protocols and file formats 37 still rely on the 30+ years old technology. Including a number of 38 high-profile Internet protocols and file formats. 39 40 Quite a number of books cover the topic of ASN.1. 41 [Communication between heterogeneous systems](http://www.oss.com/asn1/dubuisson.html) 42 by Olivier Dubuisson is one of those high quality books freely 43 available on the Internet. 44 45 The pyasn1 package is designed to help Python programmers tackling 46 network protocols and file formats at the comfort of their Python 47 prompt. The tool struggles to capture all aspects of a rather 48 complicated ASN.1 system and to represent it on the Python terms. 49 50 How to use pyasn1 51 ----------------- 52 53 With pyasn1 you can build Python objects from ASN.1 data structures. 54 For example, the following ASN.1 data structure: 55 56 ```bash 57 Record ::= SEQUENCE { 58 id INTEGER, 59 room [0] INTEGER OPTIONAL, 60 house [1] INTEGER DEFAULT 0 61 } 62 ``` 63 64 Could be expressed in pyasn1 like this: 65 66 ```python 67 class 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 83 It is in the spirit of ASN.1 to take abstract data description 84 and turn it into a programming language specific form. 85 Once you have your ASN.1 data structure expressed in Python, you 86 can 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) 94 Record: 95 id=123 96 room=321 97 >>> 98 ``` 99 100 Part of the power of ASN.1 comes from its serialisation features. You 101 can 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) 107 00000: 30 07 02 01 7B 80 02 01 41 108 ``` 109 110 Conversely, you can turn serialised ASN.1 content, as received from 111 network or read from a file, into a Python object which you can 112 introspect, 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])) 120 id is 123 121 room is 321 122 house is 0 123 >>> 124 >>> record == received_record 125 True 126 >>> received_record.update(room=123) 127 >>> substrate = encode(received_record) 128 >>> hexdump(substrate) 129 00000: 30 06 02 01 7B 80 01 7B 130 ``` 131 132 The pyasn1 classes struggle to emulate their Python prototypes (e.g. int, 133 list, dict etc.). But ASN.1 types exhibit more complicated behaviour. 134 To make life easier for a Pythonista, they can turn their pyasn1 135 classes 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 143 Or vice-versa -- you can initialize an ASN.1 structure from a tree of 144 Python 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) 150 Record: 151 id=123 152 room=321 153 >>> 154 ``` 155 156 With ASN.1 design, serialisation codecs are decoupled from data objects, 157 so you could turn every single ASN.1 object into many different 158 serialised forms. As of this moment, pyasn1 supports BER, DER, CER and 159 Python built-ins codecs. The extremely compact PER encoding is expected 160 to be introduced in the upcoming pyasn1 release. 161 162 More information on pyasn1 APIs can be found in the 163 [documentation](http://snmplabs.com/pyasn1/), 164 compiled ASN.1 modules for different protocols and file formats 165 could be found in the pyasn1-modules 166 [repo](https://github.com/etingof/pyasn1-modules). 167 168 How to get pyasn1 169 ----------------- 170 171 The pyasn1 package is distributed under terms and conditions of 2-clause 172 BSD [license](http://snmplabs.com/pyasn1/license.html). Source code is freely 173 available as a GitHub [repo](https://github.com/etingof/pyasn1). 174 175 You could `pip install pyasn1` or download it from [PyPI](https://pypi.org/project/pyasn1). 176 177 If something does not work as expected, 178 [open an issue](https://github.com/etingof/pyasn1/issues) at GitHub or 179 post your question [on Stack Overflow](https://stackoverflow.com/questions/ask) 180 or try browsing pyasn1 181 [mailing list archives](https://sourceforge.net/p/pyasn1/mailman/pyasn1-users/). 182 183 Copyright (c) 2005-2018, [Ilya Etingof](mailto:etingof (a] gmail.com). 184 All rights reserved. 185
