File: //usr/share/doc/python-pyasn1-doc/html/contents.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>ASN.1 library for Python — ASN.1 types and codecs 0.4 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Library documentation" href="pyasn1/contents.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo">
<a href="#">
<img class="logo" src="_static/logo.svg" alt="Logo"/>
</a>
</p>
<p class="blurb"><p align=left><i><b>Brewing free software for the greater good</i></b></p></p>
<h3>Navigation</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="pyasn1/contents.html">Library documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="example-use-case.html">Example use case</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="download.html">Download & Install</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="#">Documentation overview</a><ul>
<li>Next: <a href="pyasn1/contents.html" title="next chapter">Library documentation</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="asn-1-library-for-python">
<h1>ASN.1 library for Python<a class="headerlink" href="#asn-1-library-for-python" title="Permalink to this headline">¶</a></h1>
<div class="toctree-wrapper compound">
</div>
<p>Abstract Syntax Notation One (<a class="reference external" href="http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x">ASN.1</a>) is a
technology for exchanging structured data in a universally understood,
hardware agnostic way. Many industrial, security and telephony
applications heavily rely on ASN.1.</p>
<p>The <a class="reference external" href="https://pypi.org/project/pyasn1/">pyasn1</a> library implements
ASN.1 support in pure-Python.</p>
<section id="what-is-asn-1">
<h2>What is ASN.1<a class="headerlink" href="#what-is-asn-1" title="Permalink to this headline">¶</a></h2>
<p>ASN.1 is a large, arguably over-engineered and extremely old data modelling and
serialisation tool. It is probably among the first serialisation protocols in
the history of computer science and technology.</p>
<p>ASN.1 started its life over 30 years ago as a serialisation mechanism for the first
electronic mail (known as X.400). Later on if was split off the e-mail application
and become a stand-alone tech still being actively supported by its designers
and widely used in industry and technology.</p>
<p>Since then ASN.1 is sort of haunted by its relations with the OSI model – the
first, unsuccessful, version of the Internet. You can read many interesting
<a class="reference external" href="https://news.ycombinator.com/item?id=8871453">discussions</a> on that topic.</p>
<p>In the following years, generations of software engineers tackled the serialisation
problem many times. We can see that in Google’s <a class="reference external" href="https://developers.google.com/protocol-buffers/">ProtoBuffers</a>
or <a class="reference external" href="https://google.github.io/flatbuffers/">FlatBuffers</a>, for example.
Interestingly, many new takes on binary protocol design do not depart
far from ASN.1 from technical perspective. It’s more of a matter of striking
a balance between processing overhead, wire format overhead and human
readability.</p>
<p>Looking at what ASN.1 has to offer, it has three loosely coupled parts:</p>
<ul class="simple">
<li><p>Data types: the standard introduces a collection of basic data types
(integers, bits, strings, arrays and records) that can be used for describing
arbitrarily complex, nested data structures.</p></li>
<li><p>Serialisation protocols: the above data structures could be converted into a
series of octets for storage or transmission over the wire as well as
recovered back into their structured form. The system is fully agnostic
to hardware architectures differences.</p></li>
<li><p>Schema language: ASN.1 data structures could be described in terms
of a schema language for ASN.1 compiler to turn it into platform-specific
implementation.</p></li>
</ul>
</section>
<section id="asn-1-applications">
<h2>ASN.1 applications<a class="headerlink" href="#asn-1-applications" title="Permalink to this headline">¶</a></h2>
<p>Being an old and generally successful standard, ASN.1 is widely
adopted for many uses. To give you an example, these technologies
use ASN.1 for their data exchange needs:</p>
<ul class="simple">
<li><p>Signaling standards for the public switched telephone network (SS7 family)</p></li>
<li><p>Network management standards (SNMP, CMIP)</p></li>
<li><p>Directory standards (X.500 family, LDAP)</p></li>
<li><p>Public Key Infrastructure standards (X.509, etc.)</p></li>
<li><p>PBX control (CSTA)</p></li>
<li><p>IP-based Videoconferencing (H.323 family)</p></li>
<li><p>Biometrics (BIP, CBEFF, ACBio)</p></li>
<li><p>Intelligent transportation (SAE J2735)</p></li>
<li><p>Cellular telephony (GSM, GPRS/EDGE, UMTS, LTE)</p></li>
</ul>
</section>
<section id="asn-1-gotchas">
<h2>ASN.1 gotchas<a class="headerlink" href="#asn-1-gotchas" title="Permalink to this headline">¶</a></h2>
<p>Apparently, ASN.1 is hard to implement properly. Quality open-source
ASN.1 tools are rare, but ad-hoc implementations are numerous. Judging from the
<a class="reference external" href="http://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=ASN.1">statistics</a> on discovered
security vulnerabilities, many people have implemented ASN.1 parsers
and oftentimes fell victim to its edge cases.</p>
<p>On the bright side, ASN.1 has been around for a long time, it is well understood
and security reviewed.</p>
</section>
<section id="documentation">
<h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="pyasn1/contents.html">Library documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="pyasn1/contents.html#asn-1-types">ASN.1 types</a></li>
<li class="toctree-l2"><a class="reference internal" href="pyasn1/contents.html#serialisation-codecs">Serialisation codecs</a></li>
<li class="toctree-l2"><a class="reference internal" href="pyasn1/contents.html#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="use-case">
<h2>Use case<a class="headerlink" href="#use-case" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="example-use-case.html">Example use case</a><ul>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#grab-asn-1-schema-for-ssh-keys">Grab ASN.1 schema for SSH keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#compile-asn-1-schema-into-python">Compile ASN.1 schema into Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#read-your-ssh-id-rsa">Read your ~/.ssh/id_rsa</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#play-with-the-keys">Play with the keys</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#transform-to-built-ins">Transform to built-ins</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-use-case.html#write-it-back">Write it back</a></li>
</ul>
</li>
</ul>
</div>
</section>
<section id="download-install">
<h2>Download & Install<a class="headerlink" href="#download-install" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="download.html">Download & Install</a></li>
</ul>
</div>
</section>
<section id="changes">
<h2>Changes<a class="headerlink" href="#changes" title="Permalink to this headline">¶</a></h2>
<p>All changes and release history is maintained in changelog. There you
could also download the latest unreleased pyasn1 tarball containing
the latest fixes and improvements.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
</ul>
</div>
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
<p>The PyASN1 software is distributed under 2-clause BSD License.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</section>
<section id="getting-help">
<h2>Getting help<a class="headerlink" href="#getting-help" title="Permalink to this headline">¶</a></h2>
<p>Please, file your <a class="reference external" href="https://github.com/etingof/pyasn1/issues">issues</a>
and <a class="reference external" href="https://github.com/etingof/pyasn1/pulls">PRs</a> at GitHub.
Alternatively, you could ask for help at
<a class="reference external" href="http://stackoverflow.com/questions/tagged/pyasn1">Stack Overflow</a>
or search
<a class="reference external" href="https://lists.sourceforge.net/lists/listinfo/pyasn1-users">pyasn1-users</a>
mailing list archive.</p>
</section>
<section id="books-on-asn-1">
<h2>Books on ASN.1<a class="headerlink" href="#books-on-asn-1" title="Permalink to this headline">¶</a></h2>
<p>The pyasn1 implementation is largely based on reading up the following awesome
books:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.oss.com/asn1/dubuisson.html">ASN.1 - Communication between heterogeneous systems</a> by Olivier Dubuisson</p></li>
<li><p><a class="reference external" href="http://www.oss.com/asn1/resources/books-whitepapers-pubs/larmouth-asn1-book.pdf">ASN.1 Complete</a> by Prof John Larmouth</p></li>
</ul>
<p>Here you can get the official standards which is hard to read:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip">ITU standards</a></p></li>
</ul>
<p>On the other end of the readability spectrum, here is a quick and sweet write up:</p>
<ul class="simple">
<li><p><a class="reference external" href="ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc">A Layman’s Guide to a Subset of ASN.1, BER, and DER</a> by Burton S. Kaliski</p></li>
</ul>
<p>If you are working with ASN.1, we’d highly recommend reading a proper
book on the subject.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2005-2026, Ilya Etingof <etingof@gmail.com>.
</div>
</body>
</html>