X-Git-Url: http://www.git.cypherpunks.ru/?p=pyderasn.git;a=blobdiff_plain;f=doc%2Ffeatures.rst;h=fd7bb7d71df35a275abdf52c5e8d904fa6fd62dd;hp=d2d1734eb779b6545132b698bf65344d281f66d9;hb=HEAD;hpb=7aed684a10179b2e57e81369e956ac6df4fb135e

diff --git a/doc/features.rst b/doc/features.rst
index d2d1734..5cfabee 100644
--- a/doc/features.rst
+++ b/doc/features.rst
@@ -1,53 +1,78 @@
+.. _features:
+
 Features
 ========
 
+* BER/CER/DER decoding, strict DER validation, DER/CER encoding
 * Basic ASN.1 data types (X.208): BOOLEAN, INTEGER, BIT STRING, OCTET
   STRING, NULL, OBJECT IDENTIFIER, ENUMERATED, all strings, UTCTime,
   GeneralizedTime, CHOICE, ANY, SEQUENCE (OF), SET (OF)
 * Size :ref:`constraints <bounds>` checking
 * Working with sequences as high level data objects with ability to
   (un)marshall them
-* Python 2.7/3.5 compatibility
+* Python 3.5+ compatibility (2.7 dropped in version 9.0)
+* Aimed to be complaint with `X.690-201508 <https://www.itu.int/rec/T-REC-X.690-201508-I/en>`__
+* Streaming decoding and encoding capabilities, allowing working with
+  very small memory footprint
 
-Why yet another library? `pyasn1 <https://github.com/etingof/pyasn1>`__
+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
 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
   lengths inside the binary
-* :ref:`Pretty printer <pprinting>` and command-line decoder, that could
+* 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
+* Ability to use mmap-ed files, memoryviews, iterators, 2-pass DER
+  encoding mode and CER encoder dealing with the writer, giving ability
+  to create huge ASN.1 encoded files with very little memory footprint
+* Ability to decode files in event generation mode, without the need to
+  keep all the data and decoded structures (that takes huge quantity of
+  memory in all known ASN.1 libraries) in the memory
+* ``__slots__``, ``copy.copy()`` friendliness
+* Workability with ``pickle``
+* `Cython <https://cython.org/>`__ compatibility
+* 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 (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``
+* 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``
-* 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
-* ``__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
-    :``python -m pyderasn --schema path.to.CertificateList revoke.crl``:
-     ~38 sec
-    :``pyasn1.decode(asn1Spec=pyasn1.CertificateList())``:
-     ~22 min (``pyasn1 == 0.2.3``)
-
-There are drawbacks:
-
-* No old Python versions support
-* No BER/CER support
-* PyDERASN does **not** have object recreation capable ``repr``-s::
-
-    pyderasn>>> repr(algo_id)
-    AlgorithmIdentifier SEQUENCE[OBJECT IDENTIFIER 1.3.14.3.2.26, [UNIV 5] ANY 0500 OPTIONAL]
-
-    pyasn1>>> repr(algo_id)
-    AlgorithmIdentifier().setComponents(ObjectIdentifier('1.3.14.3.2.26'), Any(hexValue='0500'))
-
-* 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
+
+  .. figure:: pprinting.webp
+     :alt: Pretty printing example output
+
+     An example of pretty printed X.509 certificate with automatically
+     parsed DEFINED BY fields.
+* :ref:`ASN.1 browser <browser>`
+
+  .. figure:: browser.webp
+     :alt: ASN.1 browser example
+
+     An example of browser running.