doc/features.rst

   1 .. _features:
   2
   3 Features
   4 ========
   5
   6 * BER/CER/DER decoding, strict DER validation, DER/CER 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 * Streaming decoding and encoding capabilities, allowing working with
  16   very small memory footprint
  17
  18 Why yet another library? `pyasn1 <http://snmplabs.com/pyasn1/>`__
  19 had all of this a long time ago. PyDERASN resembles it in many ways. In
  20 practice it should be relatively easy to convert ``pyasn1``'s code to
  21 ``pyderasn``'s one.
  22 Also there is `asn1crypto <https://github.com/wbond/asn1crypto>`__.
  23
  24 * Small, simple and trying to be reviewable code. Just a single file
  25   with `six <https://pypi.org/project/six/>`__ dependency
  26 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
  27   lengths inside the binary
  28 * Automatic decoding of :ref:`DEFINED BY <definedby>` fields
  29 * Ability to know exact decoded field presence, emptiness: for example
  30   ``SEQUENCE`` can lack ``OPTIONAL SEQUENCE OF`` field, but also can
  31   have it with no elements inside
  32 * **Strict** DER-encoding checks. If whole input binary is parsed, then
  33   it must be completely valid DER-encoded structure
  34 * Ability to allow BER-encoded data with knowing if any of specified
  35   field has either DER or BER encoding (or possibly indefinite-length
  36   encoding). For example
  37   `CMS <https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`__
  38   structures allow BER encoding for the whole message, except for
  39   ``SignedAttributes`` -- you can easily verify your CMS satisfies that
  40   requirement
  41 * Ability to use mmap-ed files, memoryviews, iterators and CER encoder
  42   dealing with the writer, giving ability to create huge ASN.1 encoded
  43   files without storing all the data in the memory first
  44 * Ability to decode files in event generation mode, without the need to
  45   keep all the data and decoded structures (that takes huge quantity of
  46   memory in all known ASN.1 libraries) in the memory
  47 * ``__slots__``, ``copy.copy()`` friendliness
  48 * Workability with ``pickle``
  49 * `Cython <https://cython.org/>`__ compatibility
  50 * Extensive and comprehensive
  51   `hypothesis <https://hypothesis.readthedocs.io/en/master/>`__
  52   driven tests coverage. It also has been fuzzed with
  53   `python-afl <http://jwilk.net/software/python-afl>`__
  54 * Some kind of strong typing: SEQUENCEs require the exact **type** of
  55   settable values, even when they are inherited (assigning ``Integer``
  56   to the field with the type ``CMSVersion(Integer)`` is not allowed)
  57 * However they do not require exact tags matching: IMPLICIT/EXPLICIT
  58   tags will be set automatically in the given sequence (assigning of
  59   ``CMSVersion()`` object to the field ``CMSVersion(expl=...)`` will
  60   automatically set required tags)
  61 * Descriptive errors, like ``pyderasn.DecodeError: UTCTime
  62   (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format``
  63 * Could be significantly :ref:`faster <performance>` and have lower memory usage
  64 * :ref:`Pretty printer <pprinting>` and
  65   :ref:`command-line decoder <cmdline>`, that could
  66   conveniently replace utilities like either ``dumpasn1`` or
  67   ``openssl asn1parse``
  68
  69   .. figure:: pprinting.png
  70      :alt: Pretty printing example output
  71
  72      An example of pretty printed X.509 certificate with automatically
  73      parsed DEFINED BY fields.