======================================================================== * pyasn1 README.md ======================================================================== ASN.1 library for Python ------------------------ [![PyPI](https://img.shields.io/pypi/v/pyasn1.svg?maxAge=2592000)](https://pypi.org/project/pyasn1) [![Python Versions](https://img.shields.io/pypi/pyversions/pyasn1.svg)](https://pypi.org/project/pyasn1/) [![Build status](https://travis-ci.org/etingof/pyasn1.svg?branch=master)](https://secure.travis-ci.org/etingof/pyasn1) [![Coverage Status](https://img.shields.io/codecov/c/github/etingof/pyasn1.svg)](https://codecov.io/github/etingof/pyasn1) [![GitHub license](https://img.shields.io/badge/license-BSD-blue.svg)](https://raw.githubusercontent.com/etingof/pyasn1/master/LICENSE.txt) This is a free and open source implementation of ASN.1 types and codecs as a Python package. It has been first written to support particular protocol (SNMP) but then generalized to be suitable for a wide range of protocols based on [ASN.1 specification](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.208-198811-W!!PDF-E&type=items). Features -------- * Generic implementation of ASN.1 types (X.208) * Standards compliant BER/CER/DER codecs * Dumps/loads ASN.1 structures from Python types * 100% Python, works with Python 2.4 up to Python 3.7 * MT-safe * Contributed ASN.1 compiler [Asn1ate](https://github.com/kimgr/asn1ate) Why using pyasn1 ---------------- ASN.1 solves the data serialisation problem. This solution was designed long ago by the wise Ancients. Back then, they did not have the luxury of wasting bits. That is why ASN.1 is designed to serialise data structures of unbounded complexity into something compact and efficient when it comes to processing the data. That probably explains why many network protocols and file formats still rely on the 30+ years old technology. Including a number of high-profile Internet protocols and file formats. Quite a number of books cover the topic of ASN.1. [Communication between heterogeneous systems](http://www.oss.com/asn1/dubuisson.html) by Olivier Dubuisson is one of those high quality books freely available on the Internet. The pyasn1 package is designed to help Python programmers tackling network protocols and file formats at the comfort of their Python prompt. The tool struggles to capture all aspects of a rather complicated ASN.1 system and to represent it on the Python terms. How to use pyasn1 ----------------- With pyasn1 you can build Python objects from ASN.1 data structures. For example, the following ASN.1 data structure: ```bash Record ::= SEQUENCE { id INTEGER, room [0] INTEGER OPTIONAL, house [1] INTEGER DEFAULT 0 } ``` Could be expressed in pyasn1 like this: ```python class Record(Sequence): componentType = NamedTypes( NamedType('id', Integer()), OptionalNamedType( 'room', Integer().subtype( implicitTag=Tag(tagClassContext, tagFormatSimple, 0) ) ), DefaultedNamedType( 'house', Integer(0).subtype( implicitTag=Tag(tagClassContext, tagFormatSimple, 1) ) ) ) ``` It is in the spirit of ASN.1 to take abstract data description and turn it into a programming language specific form. Once you have your ASN.1 data structure expressed in Python, you can use it along the lines of similar Python type (e.g. ASN.1 `SET` is similar to Python `dict`, `SET OF` to `list`): ```python >>> record = Record() >>> record['id'] = 123 >>> record['room'] = 321 >>> str(record) Record: id=123 room=321 >>> ``` Part of the power of ASN.1 comes from its serialisation features. You can serialise your data structure and send it over the network. ```python >>> from pyasn1.codec.der.encoder import encode >>> substrate = encode(record) >>> hexdump(substrate) 00000: 30 07 02 01 7B 80 02 01 41 ``` Conversely, you can turn serialised ASN.1 content, as received from network or read from a file, into a Python object which you can introspect, modify, encode and send back. ```python >>> from pyasn1.codec.der.decoder import decode >>> received_record, rest_of_substrate = decode(substrate, asn1Spec=Record()) >>> >>> for field in received_record: >>> print('{} is {}'.format(field, received_record[field])) id is 123 room is 321 house is 0 >>> >>> record == received_record True >>> received_record.update(room=123) >>> substrate = encode(received_record) >>> hexdump(substrate) 00000: 30 06 02 01 7B 80 01 7B ``` The pyasn1 classes struggle to emulate their Python prototypes (e.g. int, list, dict etc.). But ASN.1 types exhibit more complicated behaviour. To make life easier for a Pythonista, they can turn their pyasn1 classes into Python built-ins: ```python >>> from pyasn1.codec.native.encoder import encode >>> encode(record) {'id': 123, 'room': 321, 'house': 0} ``` Or vice-versa -- you can initialize an ASN.1 structure from a tree of Python objects: ```python >>> from pyasn1.codec.native.decoder import decode >>> record = decode({'id': 123, 'room': 321, 'house': 0}, asn1Spec=Record()) >>> str(record) Record: id=123 room=321 >>> ``` With ASN.1 design, serialisation codecs are decoupled from data objects, so you could turn every single ASN.1 object into many different serialised forms. As of this moment, pyasn1 supports BER, DER, CER and Python built-ins codecs. The extremely compact PER encoding is expected to be introduced in the upcoming pyasn1 release. More information on pyasn1 APIs can be found in the [documentation](http://snmplabs.com/pyasn1/), compiled ASN.1 modules for different protocols and file formats could be found in the pyasn1-modules [repo](https://github.com/etingof/pyasn1-modules). How to get pyasn1 ----------------- The pyasn1 package is distributed under terms and conditions of 2-clause BSD [license](http://snmplabs.com/pyasn1/license.html). Source code is freely available as a GitHub [repo](https://github.com/etingof/pyasn1). You could `pip install pyasn1` or download it from [PyPI](https://pypi.org/project/pyasn1). If something does not work as expected, [open an issue](https://github.com/etingof/pyasn1/issues) at GitHub or post your question [on Stack Overflow](https://stackoverflow.com/questions/ask) or try browsing pyasn1 [mailing list archives](https://sourceforge.net/p/pyasn1/mailman/pyasn1-users/). Copyright (c) 2005-2019, [Ilya Etingof](mailto:etingof@gmail.com). All rights reserved. ======================================================================== * pyasn1-modules README.md ======================================================================== ASN.1 modules for Python ------------------------ [![PyPI](https://img.shields.io/pypi/v/pyasn1-modules.svg?maxAge=2592000)](https://pypi.org/project/pyasn1-modules) [![Python Versions](https://img.shields.io/pypi/pyversions/pyasn1-modules.svg)](https://pypi.org/project/pyasn1-modules/) [![Build status](https://travis-ci.org/etingof/pyasn1-modules.svg?branch=master)](https://travis-ci.org/etingof/pyasn1-modules) [![Coverage Status](https://img.shields.io/codecov/c/github/etingof/pyasn1-modules.svg)](https://codecov.io/github/etingof/pyasn1-modules/) [![GitHub license](https://img.shields.io/badge/license-BSD-blue.svg)](https://raw.githubusercontent.com/etingof/pyasn1-modules/master/LICENSE.txt) The `pyasn1-modules` package contains a collection of [ASN.1](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.208-198811-W!!PDF-E&type=items) data structures expressed as Python classes based on [pyasn1](https://github.com/etingof/pyasn1) data model. If ASN.1 module you need is not present in this collection, try using [Asn1ate](https://github.com/kimgr/asn1ate) tool that compiles ASN.1 documents into pyasn1 code. Feedback -------- If something does not work as expected, [open an issue](https://github.com/etingof/pyasn1-modules/issues) at GitHub or post your question [on Stack Overflow](https://stackoverflow.com/questions/ask) New modules contributions are welcome via GitHub pull requests. Copyright (c) 2005-2019, [Ilya Etingof](mailto:etingof@gmail.com). All rights reserved. ======================================================================== * pyasn1 LICENSE.rst, LICENSE.txt ======================================================================== Copyright (c) 2005-2019, Ilya Etingof All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ======================================================================== * pyasn1 docs/source/license.rst ======================================================================== .. _license: License ======= .. include:: ../../LICENSE.rst