doc/features.rst

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