Respect NO_COLOR environment variable
[pyderasn.git] / doc / features.rst
1 Features
2 ========
3
4 * Basic ASN.1 data types (X.208): BOOLEAN, INTEGER, BIT STRING, OCTET
5   STRING, NULL, OBJECT IDENTIFIER, ENUMERATED, all strings, UTCTime,
6   GeneralizedTime, CHOICE, ANY, SEQUENCE (OF), SET (OF)
7 * Size :ref:`constraints <bounds>` checking
8 * Working with sequences as high level data objects with ability to
9   (un)marshall them
10 * Python 2.7/3.5 compatibility
11
12 Why yet another library? `pyasn1 <https://github.com/etingof/pyasn1>`__
13 had all of this a long time ago. PyDERASN resembles it in many ways. In
14 practice it should be relatively easy to convert ``pyasn1``'s code to
15 ``pyderasn``'s one. But additionally it offers:
16
17 * Small, simple and trying to be reviewable code. Just a single file
18 * Automatic decoding of :ref:`DEFINED BY <definedby>` fields
19 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
20   lengths inside the binary
21 * :ref:`Pretty printer <pprinting>` and command-line decoder, that could
22   conveniently replace utilities like either ``dumpasn1`` or
23   ``openssl asn1parse``
24 * Some kind of strong typing: SEQUENCEs require the exact **type** of
25   settable values, even when they are inherited
26 * However they do not require tags matching: IMPLICIT/EXPLICIT tags will
27   be set automatically in the given sequence
28 * ``__slots__`` friendliness
29 * Could be significantly faster. For example parsing of CACert.org's CRL
30   under Python 3.5.2:
31
32     :``python -m pyderasn revoke.crl``:
33      ~2 min
34     :``python -m pyderasn --schema path.to.CertificateList revoke.crl``:
35      ~38 sec
36     :``pyasn1.decode(asn1Spec=pyasn1.CertificateList())``:
37      ~22 min (``pyasn1 == 0.2.3``)
38
39 There are drawbacks:
40
41 * No old Python versions support
42 * No BER/CER support
43 * PyDERASN does **not** have object recreation capable ``repr``-s::
44
45     pyderasn>>> repr(algo_id)
46     AlgorithmIdentifier SEQUENCE[OBJECT IDENTIFIER 1.3.14.3.2.26, [UNIV 5] ANY 0500 OPTIONAL]
47
48     pyasn1>>> repr(algo_id)
49     AlgorithmIdentifier().setComponents(ObjectIdentifier('1.3.14.3.2.26'), Any(hexValue='0500'))
50
51 * Strings are not validated in any way, except just trying to be decoded
52   in ``ascii``, ``iso-8859-1``, ``utf-8/16/32`` correspondingly
53 * No REAL, RELATIVE OID, EXTERNAL, INSTANCE OF, EMBEDDED PDV, CHARACTER STRING