src/third_party/mozjs-45/python/pyasn1/doc/intro.html - cobalt - Git at Google

 <html>
 <title>
 PyASN1 reference manual
 </title>
 <head>
 </head>
 <body>
 <center>
 <table width=60%>
 <tr>
 <td>

 <h3>
 PyASN1 reference manual
 </h3>

 <p align=right>
 <i>written by <a href=mailto:ilya@glas.net>Ilya Etingof</a>, 2011-2012</i>
 </p>

 <p>
 Free and open-source pyasn1 library makes it easier for programmers and
 network engineers to develop, debug and experiment with ASN.1-based protocols
 using Python programming language as a tool.
 </p>

 <p>
 Abstract Syntax Notation One
 (<a href=http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>ASN.1</a>)
 is a set of
 <a href=http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip>
 ITU standards</a> concered with provisioning instrumentation for developing
 data exchange protocols in a robust, clear and interoperabable way for
 various IT systems and applications. Most of the efforts are targeting the
 following areas:
 <ul>
 <li>Data structures: the standard introduces a collection of basic data types
 (similar to integers, bits, strings, arrays and records in a programming
 language) that can be used for defining complex, possibly nested data
 structures representing domain-specific data units.
 <li>Serialization protocols: domain-specific data units expressed in ASN.1
 types could be converted into a series of octets for storage or transmission
 over the wire and then recovered back into their structured form on the
 receiving end. This process is immune to various hardware and software
 related dependencies.
 <li>Data description language: could be used to describe particular set of
 domain-specific data structures and their relationships. Such a description
 could be passed to an ASN.1 compiler for automated generation of program
 code that represents ASN.1 data structures in language-native environment
 and handles data serialization issues.
 </ul>
 </p>

 <p>
 This tutorial and algorithms, implemented by pyasn1 library, are
 largely based on the information read in the book
 <a href="http://www.oss.com/asn1/dubuisson.html">
 ASN.1 - Communication between heterogeneous systems</a>
 by Olivier Dubuisson. Another relevant resource is
 <a 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.
 It's advised to refer to these books for more in-depth knowledge on the
 subject of ASN.1.
 </p>

 <p>
 As of this writing, pyasn1 library implements most of standard ASN.1 data
 structures in a rather detailed and feature-rich manner. Another highly
 important capability of the library is its data serialization facilities.
 The last component of the standard - ASN.1 compiler is planned for
 implementation in the future.
 </p>

 </p>
 The pyasn1 library was designed to follow the pre-1995 ASN.1 specification
 (also known as X.208). Later, post 1995, revision (X.680) introduced
 significant changes most of which have not yet been supported by pyasn1.
 </p>

 <h3>
 Table of contents
 </h3>

 <p>
 <ul>
 <li><a href="scalar.html">1. Data model for ASN.1 types</a>
 <li><a href="scalar.html#1.1">1.1 Scalar types</a>
 <li><a href="scalar.html#1.1.1">1.1.1 Boolean type</a>
 <li><a href="scalar.html#1.1.2">1.1.2 Null type</a>
 <li><a href="scalar.html#1.1.3">1.1.3 Integer type</a>
 <li><a href="scalar.html#1.1.4">1.1.4 Enumerated type</a>
 <li><a href="scalar.html#1.1.5">1.1.5 Real type</a>
 <li><a href="scalar.html#1.1.6">1.1.6 Bit string type</a>
 <li><a href="scalar.html#1.1.7">1.1.7 OctetString type</a>
 <li><a href="scalar.html#1.1.8">1.1.8 ObjectIdentifier type</a>
 <li><a href="scalar.html#1.1.9">1.1.9 Character string types</a>
 <li><a href="scalar.html#1.1.10">1.1.10 Useful types</a>
 <li><a href="tagging.html">1.2 Tagging</a>
 <li><a href="constructed.html">1.3 Constructed types</a>
 <li><a href="constructed.html#1.3.1">1.3.1 Sequence and Set types</a>
 <li><a href="constructed.html#1.3.2">1.3.2 SequenceOf and SetOf types</a>
 <li><a href="constructed.html#1.3.3">1.3.3 Choice type</a>
 <li><a href="constructed.html#1.3.4">1.3.4 Any type</a>
 <li><a href="constraints.html">1.4 Subtype constraints</a>
 <li><a href="constraints.html#1.4.1">1.4.1 Single value constraint</a>
 <li><a href="constraints.html#1.4.2">1.4.2 Value range constraint</a>
 <li><a href="constraints.html#1.4.3">1.4.3 Size constraint</a>
 <li><a href="constraints.html#1.4.4">1.4.4 Alphabet constraint</a>
 <li><a href="constraints.html#1.4.5">1.4.5 Constraint combinations</a>
 <li><a href="constraints.html#1.5">1.5 Types relationships</a>
 <li><a href="codecs.html">2. Codecs</a>
 <li><a href="codecs.html#2.1">2.1 Encoders</a>
 <li><a href="codecs.html#2.2">2.2 Decoders</a>
 <li><a href="codecs.html#2.2.1">2.2.1 Decoding untagged types</a>
 <li><a href="codecs.html#2.2.2">2.2.2 Ignoring unknown types</a>
 </ul>

 <p>
 Although pyasn1 software is almost a decade old and used in many production
 environments, it still may have bugs and non-implemented pieces. Anyone
 who happens to run into such defect is welcome to complain to
 <a href=mailto:pyasn1-users@lists.sourceforge.net>pyasn1 mailing list</a>
 or better yet fix the issue and send
 <a href=mailto:ilya@glas.net>me</a> the patch.
 </p>

 <p>
 Typically, pyasn1 is used for building arbitrary protocol support into
 various applications. This involves manual translation of ASN.1 data
 structures into their pyasn1 implementations. To save time and effort,
 data structures for some of the popular protocols are pre-programmed
 and kept for further re-use in form of the
 <a href=http://sourceforge.net/projects/pyasn1/files/pyasn1-modules/>
 pyasn1-modules package</a>. For instance, many structures for PKI (X.509,
 PKCS#*, CRMF, OCSP), LDAP and SNMP are present.
 Applications authors are advised to import and use relevant modules
 from that package whenever needed protocol structures are already
 there. New protocol modules contributions are welcome.
 </p>

 <p>
 And finally, the latest pyasn1 package revision is available for free
 download from
 <a href=http://sourceforge.net/projects/pyasn1/>project home</a> and
 also from the
 <a href=http://pypi.python.org/pypi>Python package repository</a>.
 </p>

 <hr>

 </td>
 </tr>
 </table>
 </center>
 </body>
 </html>
	<html>
	<title>
	PyASN1 reference manual
	</title>
	<head>
	</head>
	<body>
	<center>
	<table width=60%>
	<tr>
	<td>

	<h3>
	PyASN1 reference manual
	</h3>

	<p align=right>
	<i>written by <a href=mailto:ilya@glas.net>Ilya Etingof</a>, 2011-2012</i>
	</p>

	<p>
	Free and open-source pyasn1 library makes it easier for programmers and
	network engineers to develop, debug and experiment with ASN.1-based protocols
	using Python programming language as a tool.
	</p>

	<p>
	Abstract Syntax Notation One
	(<a href=http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>ASN.1</a>)
	is a set of
	<a href=http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip>
	ITU standards</a> concered with provisioning instrumentation for developing
	data exchange protocols in a robust, clear and interoperabable way for
	various IT systems and applications. Most of the efforts are targeting the
	following areas:
	<ul>
	<li>Data structures: the standard introduces a collection of basic data types
	(similar to integers, bits, strings, arrays and records in a programming
	language) that can be used for defining complex, possibly nested data
	structures representing domain-specific data units.
	<li>Serialization protocols: domain-specific data units expressed in ASN.1
	types could be converted into a series of octets for storage or transmission
	over the wire and then recovered back into their structured form on the
	receiving end. This process is immune to various hardware and software
	related dependencies.
	<li>Data description language: could be used to describe particular set of
	domain-specific data structures and their relationships. Such a description
	could be passed to an ASN.1 compiler for automated generation of program
	code that represents ASN.1 data structures in language-native environment
	and handles data serialization issues.
	</ul>
	</p>

	<p>
	This tutorial and algorithms, implemented by pyasn1 library, are
	largely based on the information read in the book
	<a href="http://www.oss.com/asn1/dubuisson.html">
	ASN.1 - Communication between heterogeneous systems</a>
	by Olivier Dubuisson. Another relevant resource is
	<a 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.
	It's advised to refer to these books for more in-depth knowledge on the
	subject of ASN.1.
	</p>

	<p>
	As of this writing, pyasn1 library implements most of standard ASN.1 data
	structures in a rather detailed and feature-rich manner. Another highly
	important capability of the library is its data serialization facilities.
	The last component of the standard - ASN.1 compiler is planned for
	implementation in the future.
	</p>

	</p>
	The pyasn1 library was designed to follow the pre-1995 ASN.1 specification
	(also known as X.208). Later, post 1995, revision (X.680) introduced
	significant changes most of which have not yet been supported by pyasn1.
	</p>

	<h3>
	Table of contents
	</h3>

	<p>
	<ul>
	<li><a href="scalar.html">1. Data model for ASN.1 types</a>
	<li><a href="scalar.html#1.1">1.1 Scalar types</a>
	<li><a href="scalar.html#1.1.1">1.1.1 Boolean type</a>
	<li><a href="scalar.html#1.1.2">1.1.2 Null type</a>
	<li><a href="scalar.html#1.1.3">1.1.3 Integer type</a>
	<li><a href="scalar.html#1.1.4">1.1.4 Enumerated type</a>
	<li><a href="scalar.html#1.1.5">1.1.5 Real type</a>
	<li><a href="scalar.html#1.1.6">1.1.6 Bit string type</a>
	<li><a href="scalar.html#1.1.7">1.1.7 OctetString type</a>
	<li><a href="scalar.html#1.1.8">1.1.8 ObjectIdentifier type</a>
	<li><a href="scalar.html#1.1.9">1.1.9 Character string types</a>
	<li><a href="scalar.html#1.1.10">1.1.10 Useful types</a>
	<li><a href="tagging.html">1.2 Tagging</a>
	<li><a href="constructed.html">1.3 Constructed types</a>
	<li><a href="constructed.html#1.3.1">1.3.1 Sequence and Set types</a>
	<li><a href="constructed.html#1.3.2">1.3.2 SequenceOf and SetOf types</a>
	<li><a href="constructed.html#1.3.3">1.3.3 Choice type</a>
	<li><a href="constructed.html#1.3.4">1.3.4 Any type</a>
	<li><a href="constraints.html">1.4 Subtype constraints</a>
	<li><a href="constraints.html#1.4.1">1.4.1 Single value constraint</a>
	<li><a href="constraints.html#1.4.2">1.4.2 Value range constraint</a>
	<li><a href="constraints.html#1.4.3">1.4.3 Size constraint</a>
	<li><a href="constraints.html#1.4.4">1.4.4 Alphabet constraint</a>
	<li><a href="constraints.html#1.4.5">1.4.5 Constraint combinations</a>
	<li><a href="constraints.html#1.5">1.5 Types relationships</a>
	<li><a href="codecs.html">2. Codecs</a>
	<li><a href="codecs.html#2.1">2.1 Encoders</a>
	<li><a href="codecs.html#2.2">2.2 Decoders</a>
	<li><a href="codecs.html#2.2.1">2.2.1 Decoding untagged types</a>
	<li><a href="codecs.html#2.2.2">2.2.2 Ignoring unknown types</a>
	</ul>

	<p>
	Although pyasn1 software is almost a decade old and used in many production
	environments, it still may have bugs and non-implemented pieces. Anyone
	who happens to run into such defect is welcome to complain to
	<a href=mailto:pyasn1-users@lists.sourceforge.net>pyasn1 mailing list</a>
	or better yet fix the issue and send
	<a href=mailto:ilya@glas.net>me</a> the patch.
	</p>

	<p>
	Typically, pyasn1 is used for building arbitrary protocol support into
	various applications. This involves manual translation of ASN.1 data
	structures into their pyasn1 implementations. To save time and effort,
	data structures for some of the popular protocols are pre-programmed
	and kept for further re-use in form of the
	<a href=http://sourceforge.net/projects/pyasn1/files/pyasn1-modules/>
	pyasn1-modules package</a>. For instance, many structures for PKI (X.509,
	PKCS#*, CRMF, OCSP), LDAP and SNMP are present.
	Applications authors are advised to import and use relevant modules
	from that package whenever needed protocol structures are already
	there. New protocol modules contributions are welcome.
	</p>

	<p>
	And finally, the latest pyasn1 package revision is available for free
	download from
	<a href=http://sourceforge.net/projects/pyasn1/>project home</a> and
	also from the
	<a href=http://pypi.python.org/pypi>Python package repository</a>.
	</p>

	<hr>

	</td>
	</tr>
	</table>
	</center>
	</body>
	</html>