1 2ASN.1 library for Python 3======================== 4 5.. toctree:: 6 :maxdepth: 2 7 8Abstract Syntax Notation One (`ASN.1 9<http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>`_) is a 10technology for exchanging structured data in a universally understood, 11hardware agnostic way. Many industrial, security and telephony 12applications heavily rely on ASN.1. 13 14The `pyasn1 <https://pypi.python.org/pypi/pyasn1/>`_ library implements 15ASN.1 support in pure-Python. 16 17What is ASN.1 18------------- 19 20ASN.1 is a large, arguably over-engineered and extremely old data modelling and 21serialization tool. It is probably among the first serialization protocols in 22the history of computer science and technology. 23 24ASN.1 started its life over 30 years ago as a serialization mechanism for the first 25electronic mail (known as X.400). Later on if was split off the e-mail application 26and become a stand-alone tech still being actively supported by its designers 27and widely used in industry and technology. 28 29Since then ASN.1 is sort of haunted by its relations with the OSI model -- the 30first, unsuccessful, version of the Internet. You can read many interesting 31`discussions <https://news.ycombinator.com/item?id=8871453>`_ on that topic. 32 33In the following years, generations of software engineers tackled the serialization 34problem many times. We can see that in Google's `ProtoBuffers <https://developers.google.com/protocol-buffers/>`_ 35or `FlatBuffers <https://google.github.io/flatbuffers/>`_, for example. 36Interestingly, many new takes on binary protocol design do not depart 37far from ASN.1 from technical perspective. It's more of a matter of striking 38a balance between processing overhead, wire format overhead and human 39readability. 40 41Looking 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* Serialization 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 56ASN.1 applications 57------------------ 58 59Being an old and generally successful standard, ASN.1 is widely 60adopted for many uses. To give you an example, these technologies 61use 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 73ASN.1 gotchas 74------------- 75 76Apparently, ASN.1 is hard to implement properly. Quality open-source 77ASN.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 79security vulnerabilities, many people have implemented ASN.1 parsers 80and oftentimes fell victim to its edge cases. 81 82On the bright side, ASN.1 has been around for a long time, it is well understood 83and security reviewed. 84 85Library capabilities 86-------------------- 87 88As of this moment, pyasn1 library implements all ASN.1 data 89types as Python objects in accordance with X.208 standard. Later, 90post-1995, revision (X.680) introduced some changes to the schema 91language which may not be fully supported by pyasn1. Aside from data 92types a collection of data transformation codecs comes with pyasn1 package. 93 94As for ASN.1 schema language, pyasn1 package does 95not ship any compiler for it. However, there's a tool called 96`asn1late <https://github.com/kimgr/asn1ate>`_ which is an ASN.1 97grammar parser paired to code generator capable of generating pyasn1 98code. So this is an alternative (or at least a good start) to manual 99implementation of pyasn1 classes from ASN.1 specification. 100 101Both `pyasn1 <https://github.com/etingof/pyasn1>`_ and 102`pyasn1-modules <https://github.com/etingof/pyasn1-modules>`_ libraries 103can be used out-of-the-box with Python versions 2.4 through 3.6. 104No external dependencies required. 105 106Documentation 107------------- 108 109.. toctree:: 110 :maxdepth: 2 111 112 /docs/tutorial 113 /docs/api-reference 114 115Use case 116-------- 117 118 .. toctree:: 119 :maxdepth: 2 120 121 /example-use-case 122 123Download & Install 124------------------ 125 126The PyASN1 software is provided under terms and conditions of BSD-style 127:ref:`license`, and can be freely downloaded from `Github <https://github.com/etingof/pyasn1>`_ 128or `PyPI <http://pypi.python.org/pypi/pyasn1/>`_. 129 130It is pure-Python and has no dependencies. Considering how much industrial or finance 131software can be stuck with an old platform (think RHEL 5), we struggle to maintain its 132compatibility back to the very pre-historic Python (which is 2.4!). 133 134The best way to obtain PyASN1 is by running `pip`: 135 136.. code-block:: bash 137 138 $ pip install pyasn1 139 140or 141 142.. code-block:: bash 143 144 $ easy_install pyasn1 145 146You may also want to use `pyasn1-modules`: 147 148.. code-block:: bash 149 150 $ pip install pyasn1-modules 151 152Changes 153------- 154 155All changes and release history is maintained in changelog. There you 156could also download the latest unreleased pyasn1 tarball containing 157the latest fixes and improvements. 158 159 .. toctree:: 160 :maxdepth: 1 161 162 /changelog 163 164Getting help 165------------ 166 167Please, file your `issues <https://github.com/etingof/pyasn1/issues>`_ 168and `PRs <https://github.com/etingof/pyasn1/pulls>`_ at GitHub. 169Alternatively, you could ask for help at 170`Stack Overflow <http://stackoverflow.com/questions/tagged/pyasn1>`_ 171or search 172`pyasn1-users <https://lists.sourceforge.net/lists/listinfo/pyasn1-users>`_ 173mailing list archive. 174 175Books on ASN.1 176-------------- 177 178The pyasn1 implementation is largely based on reading up the following awesome 179books: 180 181* `ASN.1 - Communication between heterogeneous systems <http://www.oss.com/asn1/dubuisson.html>`_ by Olivier Dubuisson 182* `ASN.1 Complete <http://www.oss.com/asn1/resources/books-whitepapers-pubs/larmouth-asn1-book.pdf>`_ by Prof John Larmouth 183 184Here you can get the official standards which is hard to read: 185 186* `ITU standards <http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip>`_ 187 188On the other end of the readability spectrum, here is a quick and sweet write up: 189 190* `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 191 192If you are working with ASN.1, we'd highly recommend reading a proper 193book on the subject. 194 195