intro.html 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. <html>
  2. <title>
  3. PyASN1 reference manual
  4. </title>
  5. <head>
  6. </head>
  7. <body>
  8. <center>
  9. <table width=60%>
  10. <tr>
  11. <td>
  12. <h3>
  13. PyASN1 reference manual
  14. </h3>
  15. <p align=right>
  16. <i>written by <a href=mailto:ilya@glas.net>Ilya Etingof</a>, 2011-2012</i>
  17. </p>
  18. <p>
  19. Free and open-source pyasn1 library makes it easier for programmers and
  20. network engineers to develop, debug and experiment with ASN.1-based protocols
  21. using Python programming language as a tool.
  22. </p>
  23. <p>
  24. Abstract Syntax Notation One
  25. (<a href=http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>ASN.1</a>)
  26. is a set of
  27. <a href=http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip>
  28. ITU standards</a> concered with provisioning instrumentation for developing
  29. data exchange protocols in a robust, clear and interoperabable way for
  30. various IT systems and applications. Most of the efforts are targeting the
  31. following areas:
  32. <ul>
  33. <li>Data structures: the standard introduces a collection of basic data types
  34. (similar to integers, bits, strings, arrays and records in a programming
  35. language) that can be used for defining complex, possibly nested data
  36. structures representing domain-specific data units.
  37. <li>Serialization protocols: domain-specific data units expressed in ASN.1
  38. types could be converted into a series of octets for storage or transmission
  39. over the wire and then recovered back into their structured form on the
  40. receiving end. This process is immune to various hardware and software
  41. related dependencies.
  42. <li>Data description language: could be used to describe particular set of
  43. domain-specific data structures and their relationships. Such a description
  44. could be passed to an ASN.1 compiler for automated generation of program
  45. code that represents ASN.1 data structures in language-native environment
  46. and handles data serialization issues.
  47. </ul>
  48. </p>
  49. <p>
  50. This tutorial and algorithms, implemented by pyasn1 library, are
  51. largely based on the information read in the book
  52. <a href="http://www.oss.com/asn1/dubuisson.html">
  53. ASN.1 - Communication between heterogeneous systems</a>
  54. by Olivier Dubuisson. Another relevant resource is
  55. <a href=ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc>
  56. A Layman's Guide to a Subset of ASN.1, BER, and DER</a> by Burton S. Kaliski.
  57. It's advised to refer to these books for more in-depth knowledge on the
  58. subject of ASN.1.
  59. </p>
  60. <p>
  61. As of this writing, pyasn1 library implements most of standard ASN.1 data
  62. structures in a rather detailed and feature-rich manner. Another highly
  63. important capability of the library is its data serialization facilities.
  64. The last component of the standard - ASN.1 compiler is planned for
  65. implementation in the future.
  66. </p>
  67. </p>
  68. The pyasn1 library was designed to follow the pre-1995 ASN.1 specification
  69. (also known as X.208). Later, post 1995, revision (X.680) introduced
  70. significant changes most of which have not yet been supported by pyasn1.
  71. </p>
  72. <h3>
  73. Table of contents
  74. </h3>
  75. <p>
  76. <ul>
  77. <li><a href="scalar.html">1. Data model for ASN.1 types</a>
  78. <li><a href="scalar.html#1.1">1.1 Scalar types</a>
  79. <li><a href="scalar.html#1.1.1">1.1.1 Boolean type</a>
  80. <li><a href="scalar.html#1.1.2">1.1.2 Null type</a>
  81. <li><a href="scalar.html#1.1.3">1.1.3 Integer type</a>
  82. <li><a href="scalar.html#1.1.4">1.1.4 Enumerated type</a>
  83. <li><a href="scalar.html#1.1.5">1.1.5 Real type</a>
  84. <li><a href="scalar.html#1.1.6">1.1.6 Bit string type</a>
  85. <li><a href="scalar.html#1.1.7">1.1.7 OctetString type</a>
  86. <li><a href="scalar.html#1.1.8">1.1.8 ObjectIdentifier type</a>
  87. <li><a href="scalar.html#1.1.9">1.1.9 Character string types</a>
  88. <li><a href="scalar.html#1.1.10">1.1.10 Useful types</a>
  89. <li><a href="tagging.html">1.2 Tagging</a>
  90. <li><a href="constructed.html">1.3 Constructed types</a>
  91. <li><a href="constructed.html#1.3.1">1.3.1 Sequence and Set types</a>
  92. <li><a href="constructed.html#1.3.2">1.3.2 SequenceOf and SetOf types</a>
  93. <li><a href="constructed.html#1.3.3">1.3.3 Choice type</a>
  94. <li><a href="constructed.html#1.3.4">1.3.4 Any type</a>
  95. <li><a href="constraints.html">1.4 Subtype constraints</a>
  96. <li><a href="constraints.html#1.4.1">1.4.1 Single value constraint</a>
  97. <li><a href="constraints.html#1.4.2">1.4.2 Value range constraint</a>
  98. <li><a href="constraints.html#1.4.3">1.4.3 Size constraint</a>
  99. <li><a href="constraints.html#1.4.4">1.4.4 Alphabet constraint</a>
  100. <li><a href="constraints.html#1.4.5">1.4.5 Constraint combinations</a>
  101. <li><a href="constraints.html#1.5">1.5 Types relationships</a>
  102. <li><a href="codecs.html">2. Codecs</a>
  103. <li><a href="codecs.html#2.1">2.1 Encoders</a>
  104. <li><a href="codecs.html#2.2">2.2 Decoders</a>
  105. <li><a href="codecs.html#2.2.1">2.2.1 Decoding untagged types</a>
  106. <li><a href="codecs.html#2.2.2">2.2.2 Ignoring unknown types</a>
  107. </ul>
  108. <p>
  109. Although pyasn1 software is almost a decade old and used in many production
  110. environments, it still may have bugs and non-implemented pieces. Anyone
  111. who happens to run into such defect is welcome to complain to
  112. <a href=mailto:pyasn1-users@lists.sourceforge.net>pyasn1 mailing list</a>
  113. or better yet fix the issue and send
  114. <a href=mailto:ilya@glas.net>me</a> the patch.
  115. </p>
  116. <p>
  117. Typically, pyasn1 is used for building arbitrary protocol support into
  118. various applications. This involves manual translation of ASN.1 data
  119. structures into their pyasn1 implementations. To save time and effort,
  120. data structures for some of the popular protocols are pre-programmed
  121. and kept for further re-use in form of the
  122. <a href=http://sourceforge.net/projects/pyasn1/files/pyasn1-modules/>
  123. pyasn1-modules package</a>. For instance, many structures for PKI (X.509,
  124. PKCS#*, CRMF, OCSP), LDAP and SNMP are present.
  125. Applications authors are advised to import and use relevant modules
  126. from that package whenever needed protocol structures are already
  127. there. New protocol modules contributions are welcome.
  128. </p>
  129. <p>
  130. And finally, the latest pyasn1 package revision is available for free
  131. download from
  132. <a href=http://sourceforge.net/projects/pyasn1/>project home</a> and
  133. also from the
  134. <a href=http://pypi.python.org/pypi>Python package repository</a>.
  135. </p>
  136. <hr>
  137. </td>
  138. </tr>
  139. </table>
  140. </center>
  141. </body>
  142. </html>