+.. _features:
+
Features
========
* Working with sequences as high level data objects with ability to
(un)marshall them
* Python 2.7/3.5/3.6 compatibility
+* Aimed to be complaint with `X.690-201508 <https://www.itu.int/rec/T-REC-X.690-201508-I/en>`__
Why yet another library? `pyasn1 <http://snmplabs.com/pyasn1/>`__
had all of this a long time ago. PyDERASN resembles it in many ways. In
practice it should be relatively easy to convert ``pyasn1``'s code to
-``pyderasn``'s one. But additionally it offers:
+``pyderasn``'s one.
+Also there is `asn1crypto <https://github.com/wbond/asn1crypto>`__.
* Small, simple and trying to be reviewable code. Just a single file
-* Automatic decoding of :ref:`DEFINED BY <definedby>` fields
+ with `six <https://pypi.org/project/six/>`__ dependency
* Ability to know :ref:`exact decoded <decoding>` objects offsets and
lengths inside the binary
-* :ref:`Pretty printer <pprinting>` and command-line decoder, that could
- conveniently replace utilities like either ``dumpasn1`` or
- ``openssl asn1parse``
+* Automatic decoding of :ref:`DEFINED BY <definedby>` fields
+* Ability to know exact decoded field presence, emptiness: for example
+ ``SEQUENCE`` can lack ``OPTIONAL SEQUENCE OF`` field, but also can
+ have it with no elements inside
+* **Strict** DER-encoding checks. If whole input binary is parsed, then
+ it must be completely valid DER-encoded structure
+* Ability to allow BER-encoded data with knowing if any of specified
+ field has either DER or BER encoding (or possibly indefinite-length
+ encoding). For example
+ `CMS <https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`__
+ structures allow BER encoding for the whole message, except for
+ ``SignedAttributes`` -- you can easily verify your CMS satisfies that
+ requirement
+* Extensive and comprehensive
+ `hypothesis <https://hypothesis.readthedocs.io/en/master/>`__
+ driven tests coverage. It also has been fuzzed with
+ `python-afl <http://jwilk.net/software/python-afl>`__
* Some kind of strong typing: SEQUENCEs require the exact **type** of
- settable values, even when they are inherited
-* However they do not require tags matching: IMPLICIT/EXPLICIT tags will
- be set automatically in the given sequence
+ settable values, even when they are inherited (assigning ``Integer``
+ to the field with the type ``CMSVersion(Integer)`` is not allowed)
+* However they do not require exact tags matching: IMPLICIT/EXPLICIT
+ tags will be set automatically in the given sequence (assigning of
+ ``CMSVersion()`` object to the field ``CMSVersion(expl=...)`` will
+ automatically set required tags)
* Descriptive errors, like ``pyderasn.DecodeError: UTCTime
- (tbsCertificate.validity.notAfter.utcTime) (at 328) invalid UTCTime format``
-* ``__slots__`` friendliness
-* Could be significantly faster. For example parsing of CACert.org's CRL
- under Python 3.5.2:
-
- :``python -m pyderasn revoke.crl``:
- ~2 min (``pyderasn == 1.0``)
- :``python -m pyderasn --schema path.to.CertificateList revoke.crl``:
- ~38 sec (``pyderasn == 1.0``)
- :``pyasn1.decode(asn1Spec=pyasn1.CertificateList())``:
- ~22 min (``pyasn1 == 0.2.3``)
+ (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format``
+* ``__slots__``, ``copy.copy()`` friendliness
+* Workability with ``pickle``
+* `Cython <https://cython.org/>`__ compatibility
+* Could be significantly :ref:`faster <performance>` and have lower memory usage
+* :ref:`Pretty printer <pprinting>` and
+ :ref:`command-line decoder <cmdline>`, that could
+ conveniently replace utilities like either ``dumpasn1`` or
+ ``openssl asn1parse``
-There are drawbacks:
+ .. figure:: pprinting.png
+ :alt: Pretty printing example output
-* No old Python versions support
-* Strings are not validated in any way, except just trying to be decoded
- in ``ascii``, ``iso-8859-1``, ``utf-8/16/32`` correspondingly
-* No REAL, RELATIVE OID, EXTERNAL, INSTANCE OF, EMBEDDED PDV, CHARACTER STRING
+ An example of pretty printed X.509 certificate with automatically
+ parsed DEFINED BY fields.