doc/features.rst

   1 Features
   2 ========
   3
   4 * BER/CER/DER decoding, DER encoding
   5 * Basic ASN.1 data types (X.208): BOOLEAN, INTEGER, BIT STRING, OCTET
   6   STRING, NULL, OBJECT IDENTIFIER, ENUMERATED, all strings, UTCTime,
   7   GeneralizedTime, CHOICE, ANY, SEQUENCE (OF), SET (OF)
   8 * Size :ref:`constraints <bounds>` checking
   9 * Working with sequences as high level data objects with ability to
  10   (un)marshall them
  11 * Python 2.7/3.5/3.6 compatibility
  12 * Aimed to be complaint with `X.690-201508 <https://www.itu.int/rec/T-REC-X.690-201508-I/en>`__
  13
  14 Why yet another library? `pyasn1 <http://snmplabs.com/pyasn1/>`__
  15 had all of this a long time ago. PyDERASN resembles it in many ways. In
  16 practice it should be relatively easy to convert ``pyasn1``'s code to
  17 ``pyderasn``'s one.
  18 Also there is `asn1crypto <https://github.com/wbond/asn1crypto>`__.
  19
  20 * Small, simple and trying to be reviewable code. Just a single file
  21   with `six <https://pypi.org/project/six/>`__ dependency
  22 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
  23   lengths inside the binary
  24 * Automatic decoding of :ref:`DEFINED BY <definedby>` fields
  25 * Ability to know exact decoded field presence, emptiness: for example
  26   ``SEQUENCE`` can lack ``OPTIONAL SEQUENCE OF`` field, but also can
  27   have it with no elements inside
  28 * **Strict** DER-encoding checks. If whole input binary is parsed, then
  29   it must be completely valid DER-encoded structure
  30 * Ability to allow BER-encoded data with knowing if any of specified
  31   field has either DER or BER encoding (or possibly indefinite-length
  32   encoding). For example
  33   `CMS <https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`__
  34   structures allow BER encoding for the whole message, except for
  35   ``SignedAttributes`` -- you can easily verify your CMS satisfies that
  36   requirement
  37 * Extensive and comprehensive
  38   `hypothesis <https://hypothesis.readthedocs.io/en/master/>`__
  39   driven tests coverage. It also has been fuzzed with
  40   `python-afl <http://jwilk.net/software/python-afl>`__
  41 * Some kind of strong typing: SEQUENCEs require the exact **type** of
  42   settable values, even when they are inherited (assigning ``Integer``
  43   to the field with the type ``CMSVersion(Integer)`` is not allowed)
  44 * However they do not require exact tags matching: IMPLICIT/EXPLICIT
  45   tags will be set automatically in the given sequence (assigning of
  46   ``CMSVersion()`` object to the field ``CMSVersion(expl=...)`` will
  47   automatically set required tags)
  48 * Descriptive errors, like ``pyderasn.DecodeError: UTCTime
  49   (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format``
  50 * ``__slots__``, ``copy.copy()``, ``pickle``, `Cython <https://cython.org/>`__
  51   friendliness
  52 * Could be significantly faster and have lower memory usage
  53   For example parsing of CACert.org's CRL (8.48 MiB) on FreeBSD 12.0
  54   amd64, Intel Core i5-6200U 2.3 GHz machine, Python 3.5.5/2.7.15:
  55
  56   .. list-table::
  57      :widths: 15 45 20 20
  58      :header-rows: 1
  59
  60      * - Library
  61        - Command
  62        - Time, sec (Py3/Py2)
  63        - Memory used, MiB (Py3/Py2)
  64      * - pyasn1 0.4.5
  65        - ``der_decode(data, asn1Spec=rfc5280.CertificateList())``
  66        - 1257 / 1302
  67        - 1327 / 2093
  68      * - asn1crypto 0.24.0
  69        - ``asn1crypto.crl.CertificateList.load(data).native``
  70        - 29.3 / 43.8
  71        - 983 / 1677
  72      * - pyderasn 4.9
  73        - ``CertificateList().decode(data)`` (CertificateList is
  74          converted ``pyasn1`` scheme definition)
  75        - 27.6 / 32.5
  76        - 498 / 488
  77 * :ref:`Pretty printer <pprinting>` and
  78   :ref:`command-line decoder <cmdline>`, that could
  79   conveniently replace utilities like either ``dumpasn1`` or
  80   ``openssl asn1parse``
  81
  82   .. figure:: pprinting.png
  83      :alt: Pretty printing example output
  84
  85      An example of pretty printed X.509 certificate with automatically
  86      parsed DEFINED BY fields.