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 3.5+ compatibility (2.7 dropped in version 9.0)
  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 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
  26   lengths inside the binary
  27 * Automatic decoding of :ref:`DEFINED BY <definedby>` fields
  28 * Ability to know exact decoded field presence, emptiness: for example
  29   ``SEQUENCE`` can lack ``OPTIONAL SEQUENCE OF`` field, but also can
  30   have it with no elements inside
  31 * **Strict** DER-encoding checks. If whole input binary is parsed, then
  32   it must be completely valid DER-encoded structure
  33 * Ability to allow BER-encoded data with knowing if any of specified
  34   field has either DER or BER encoding (or possibly indefinite-length
  35   encoding). For example
  36   `CMS <https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`__
  37   structures allow BER encoding for the whole message, except for
  38   ``SignedAttributes`` -- you can easily verify your CMS satisfies that
  39   requirement
  40 * Ability to use mmap-ed files, memoryviews, iterators, 2-pass DER
  41   encoding mode and CER encoder dealing with the writer, giving ability
  42   to create huge ASN.1 encoded files with very little memory footprint
  43 * Ability to decode files in event generation mode, without the need to
  44   keep all the data and decoded structures (that takes huge quantity of
  45   memory in all known ASN.1 libraries) in the memory
  46 * ``__slots__``, ``copy.copy()`` friendliness
  47 * Workability with ``pickle``
  48 * `Cython <https://cython.org/>`__ compatibility
  49 * Extensive and comprehensive
  50   `hypothesis <https://hypothesis.readthedocs.io/en/master/>`__
  51   driven tests coverage. It also has been fuzzed with
  52   `python-afl <http://jwilk.net/software/python-afl>`__
  53 * Some kind of strong typing: SEQUENCEs require the exact **type** of
  54   settable values, even when they are inherited (assigning ``Integer``
  55   to the field with the type ``CMSVersion(Integer)`` is not allowed)
  56 * However they do not require exact tags matching: IMPLICIT/EXPLICIT
  57   tags will be set automatically in the given sequence (assigning of
  58   ``CMSVersion()`` object to the field ``CMSVersion(expl=...)`` will
  59   automatically set required tags)
  60 * Descriptive errors, like ``pyderasn.DecodeError: UTCTime
  61   (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format``
  62 * Could be significantly :ref:`faster <performance>` and have lower memory usage
  63 * :ref:`Pretty printer <pprinting>` and
  64   :ref:`command-line decoder <cmdline>`, that could
  65   conveniently replace utilities like either ``dumpasn1`` or
  66   ``openssl asn1parse``
  67
  68   .. figure:: pprinting.webp
  69      :alt: Pretty printing example output
  70
  71      An example of pretty printed X.509 certificate with automatically
  72      parsed DEFINED BY fields.
  73 * :ref:`ASN.1 browser <browser>`
  74
  75   .. figure:: browser.webp
  76      :alt: ASN.1 browser example
  77
  78      An example of browser running.