From 3501b3bd46cdde98861333793c32fa97b04005fe Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Thu, 2 Feb 2017 21:44:21 +0100 Subject: move text files to .rst --- README.md | 169 -------------------------------------------------------------- 1 file changed, 169 deletions(-) delete mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md deleted file mode 100644 index b59b61c..0000000 --- a/README.md +++ /dev/null @@ -1,169 +0,0 @@ - -ASN.1 library for Python ------------------------- -[![PyPI](https://img.shields.io/pypi/v/pyasn1.svg?maxAge=2592000)](https://pypi.python.org/pypi/pyasn1) -[![Python Versions](https://img.shields.io/pypi/pyversions/pyasn1.svg)](https://pypi.python.org/pypi/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) -* Fully standard compliant BER/CER/DER codecs -* 100% Python, works with Python 2.4 up to Python 3.6 -* MT-safe -* Contributed ASN.1 compiler [Asn1ate](https://github.com/kimgr/asn1ate) - -Why using pyasn1 ----------------- - -ASN.1 solves the data serialization 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 serialize 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 ->>> print(record.prettyPrint()) -Record: - id=123 - room=321 ->>> -``` - -Part of the power of ASN.1 comes from its serialization features. You -can serialize your data structure and send it over the network. - -```python ->>> substrate = encode(record) ->>> hexdump(substrate) -00000: 30 07 02 01 7B 80 02 01 41 -``` - -Conversely, you can turn serialized 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 ->>> received_record, rest_of_substrate = decode(substrate, asn1Spec=Record()) ->>> ->>> print(received_record.prettyPrint()) -Record: - id=123 - room=321 - house=0 ->>> ->>> record == received_record -True ->>> received_record['room'] = 123 ->>> substrate = encode(received_record) ->>> hexdump(substrate) -00000: 30 06 02 01 7B 80 01 7B -``` - -With ASN.1 design, serialization codecs are decoupled from data objects, -so you could turn every single ASN.1 object into many different -serialized forms. As of this moment, pyasn1 supports BER, DER and CER -formats. 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://pyasn1.sourceforge.net), -compiled ASN.1 modules for different protocols and file formats -could be found in the pyasn1-modules -[repo](https://github.com/etingof/pyasn1-modules). - -Download --------- - -The pyasn1 package is distributed under terms and conditions of 2-clause -BSD [license](http://pyasn1.sourceforge.net/license.html). Source code is freely -available as a Github [repo](https://github.com/etingof/pyasn1). - -Installation ------------- - -Download pyasn1 from [PyPI](https://pypi.python.org/pypi/pyasn1) or just run: - -```bash -$ pip install pyasn1 -``` - -Getting help ------------- - -If something does not work as expected, -[open an issue](https://github.com/etingof/pyasn1/issues) at Github or -post your question [to Stack Overflow](http://stackoverflow.com/questions/ask) -or try browsing pyasn1 -[mailing list archives](https://sourceforge.net/p/pyasn1/mailman/pyasn1-users/). - -Copyright (c) 2005-2017, [Ilya Etingof](http://etingof@gmail.com). -All rights reserved. -- cgit v1.2.1