1 2 ASN.1 library for Python 3 ======================== 4 5 .. toctree:: 6 :maxdepth: 1 7 8 Abstract Syntax Notation One (`ASN.1 9 <http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>`_) is a 10 technology for exchanging structured data in a universally understood, 11 hardware agnostic way. Many industrial, security and telephony 12 applications heavily rely on ASN.1. 13 14 The `pyasn1 <https://pypi.org/project/pyasn1/>`_ library implements 15 ASN.1 support in pure-Python. 16 17 What is ASN.1 18 ------------- 19 20 ASN.1 is a large, arguably over-engineered and extremely old data modelling and 21 serialisation tool. It is probably among the first serialisation protocols in 22 the history of computer science and technology. 23 24 ASN.1 started its life over 30 years ago as a serialisation mechanism for the first 25 electronic mail (known as X.400). Later on if was split off the e-mail application 26 and become a stand-alone tech still being actively supported by its designers 27 and widely used in industry and technology. 28 29 Since then ASN.1 is sort of haunted by its relations with the OSI model -- the 30 first, unsuccessful, version of the Internet. You can read many interesting 31 `discussions <https://news.ycombinator.com/item?id=8871453>`_ on that topic. 32 33 In the following years, generations of software engineers tackled the serialisation 34 problem many times. We can see that in Google's `ProtoBuffers <https://developers.google.com/protocol-buffers/>`_ 35 or `FlatBuffers <https://google.github.io/flatbuffers/>`_, for example. 36 Interestingly, many new takes on binary protocol design do not depart 37 far from ASN.1 from technical perspective. It's more of a matter of striking 38 a balance between processing overhead, wire format overhead and human 39 readability. 40 41 Looking at what ASN.1 has to offer, it has three loosely coupled parts: 42 43 * Data types: the standard introduces a collection of basic data types 44 (integers, bits, strings, arrays and records) that can be used for describing 45 arbitrarily complex, nested data structures. 46 47 * Serialisation protocols: the above data structures could be converted into a 48 series of octets for storage or transmission over the wire as well as 49 recovered back into their structured form. The system is fully agnostic 50 to hardware architectures differences. 51 52 * Schema language: ASN.1 data structures could be described in terms 53 of a schema language for ASN.1 compiler to turn it into platform-specific 54 implementation. 55 56 ASN.1 applications 57 ------------------ 58 59 Being an old and generally successful standard, ASN.1 is widely 60 adopted for many uses. To give you an example, these technologies 61 use ASN.1 for their data exchange needs: 62 63 * Signaling standards for the public switched telephone network (SS7 family) 64 * Network management standards (SNMP, CMIP) 65 * Directory standards (X.500 family, LDAP) 66 * Public Key Infrastructure standards (X.509, etc.) 67 * PBX control (CSTA) 68 * IP-based Videoconferencing (H.323 family) 69 * Biometrics (BIP, CBEFF, ACBio) 70 * Intelligent transportation (SAE J2735) 71 * Cellular telephony (GSM, GPRS/EDGE, UMTS, LTE) 72 73 ASN.1 gotchas 74 ------------- 75 76 Apparently, ASN.1 is hard to implement properly. Quality open-source 77 ASN.1 tools are rare, but ad-hoc implementations are numerous. Judging from the 78 `statistics <http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=ASN.1>`_ on discovered 79 security vulnerabilities, many people have implemented ASN.1 parsers 80 and oftentimes fell victim to its edge cases. 81 82 On the bright side, ASN.1 has been around for a long time, it is well understood 83 and security reviewed. 84 85 Documentation 86 ------------- 87 88 .. toctree:: 89 :maxdepth: 2 90 91 /pyasn1/contents 92 93 Use case 94 -------- 95 96 .. toctree:: 97 :maxdepth: 2 98 99 /example-use-case 100 101 Download & Install 102 ------------------ 103 104 .. toctree:: 105 :maxdepth: 2 106 107 /download 108 109 Changes 110 ------- 111 112 All changes and release history is maintained in changelog. There you 113 could also download the latest unreleased pyasn1 tarball containing 114 the latest fixes and improvements. 115 116 .. toctree:: 117 :maxdepth: 1 118 119 /changelog 120 121 License 122 ------- 123 124 The PyASN1 software is distributed under 2-clause BSD License. 125 126 .. toctree:: 127 :maxdepth: 2 128 129 /license 130 131 Getting help 132 ------------ 133 134 Please, file your `issues <https://github.com/etingof/pyasn1/issues>`_ 135 and `PRs <https://github.com/etingof/pyasn1/pulls>`_ at GitHub. 136 Alternatively, you could ask for help at 137 `Stack Overflow <http://stackoverflow.com/questions/tagged/pyasn1>`_ 138 or search 139 `pyasn1-users <https://lists.sourceforge.net/lists/listinfo/pyasn1-users>`_ 140 mailing list archive. 141 142 Books on ASN.1 143 -------------- 144 145 The pyasn1 implementation is largely based on reading up the following awesome 146 books: 147 148 * `ASN.1 - Communication between heterogeneous systems <http://www.oss.com/asn1/dubuisson.html>`_ by Olivier Dubuisson 149 * `ASN.1 Complete <http://www.oss.com/asn1/resources/books-whitepapers-pubs/larmouth-asn1-book.pdf>`_ by Prof John Larmouth 150 151 Here you can get the official standards which is hard to read: 152 153 * `ITU standards <http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip>`_ 154 155 On the other end of the readability spectrum, here is a quick and sweet write up: 156 157 * `A Layman's Guide to a Subset of ASN.1, BER, and DER <ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc>`_ by Burton S. Kaliski 158 159 If you are working with ASN.1, we'd highly recommend reading a proper 160 book on the subject. 161 162
