From: Sergey Matveev <stargrave@stargrave.org>
Date: Sat, 5 Jan 2019 20:37:16 +0000 (+0300)
Subject: Update features list and performance comparison table
X-Git-Tag: 5.0~5
X-Git-Url: http://www.git.cypherpunks.ru/?p=pyderasn.git;a=commitdiff_plain;h=13ea772db7870683065ac15197888cd037df78f0

Update features list and performance comparison table
---

diff --git a/doc/features.rst b/doc/features.rst
index 19cf7f9..34fe941 100644
--- a/doc/features.rst
+++ b/doc/features.rst
@@ -14,31 +14,69 @@ Features
 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:
+* :ref:`Pretty printer <pprinting>` and
+  :ref:`command-line decoder <cmdline>`, that could
+  conveniently replace utilities like either ``dumpasn1`` or
+  ``openssl asn1parse``
+* Could be significantly faster and have lower memory usage.
+  For example parsing of CACert.org's CRL (8.48 MiB) on FreeBSD 12.0
+  amd64, Intel Core i5-6200U 2.3 GHz machine, Python 3.5.5/2.7.15:
+
+  .. list-table::
+     :widths: 15 45 20 20
+     :header-rows: 1
 
-    :``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``)
+     * - Library
+       - Command
+       - Time, sec (Py3/Py2)
+       - Memory used, MiB (Py3/Py2)
+     * - pyasn1 0.4.5
+       - ``der_decode(data, asn1Spec=rfc5280.CertificateList())``
+       - 1257 / 1302
+       - 1327 / 2093
+     * - asn1crypto 0.24.0
+       - ``asn1crypto.crl.CertificateList.load(data).native``
+       - 29.3 / 43.8
+       - 983 / 1677
+     * - pyderasn 4.9
+       - ``CertificateList().decode(data)`` (CertificateList is
+         converted ``pyasn1`` scheme definition)
+       - 27.6 / 32.5
+       - 498 / 488
 
 There are drawbacks: