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
  13 Why yet another library? `pyasn1 <http://snmplabs.com/pyasn1/>`__
  14 had all of this a long time ago. PyDERASN resembles it in many ways. In
  15 practice it should be relatively easy to convert ``pyasn1``'s code to
  16 ``pyderasn``'s one. But additionally it offers:
  17
  18 * Small, simple and trying to be reviewable code. Just a single file
  19 * Automatic decoding of :ref:`DEFINED BY <definedby>` fields
  20 * Ability to know :ref:`exact decoded <decoding>` objects offsets and
  21   lengths inside the binary
  22 * :ref:`Pretty printer <pprinting>` and command-line decoder, that could
  23   conveniently replace utilities like either ``dumpasn1`` or
  24   ``openssl asn1parse``
  25 * Some kind of strong typing: SEQUENCEs require the exact **type** of
  26   settable values, even when they are inherited
  27 * However they do not require tags matching: IMPLICIT/EXPLICIT tags will
  28   be set automatically in the given sequence
  29 * Descriptive errors, like ``pyderasn.DecodeError: UTCTime
  30   (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format``
  31 * ``__slots__`` friendliness
  32 * Could be significantly faster. For example parsing of CACert.org's CRL
  33   under Python 3.5.2:
  34
  35     :``python -m pyderasn revoke.crl``:
  36      ~2 min (``pyderasn == 1.0``)
  37     :``python -m pyderasn --schema path.to.CertificateList revoke.crl``:
  38      ~38 sec (``pyderasn == 1.0``)
  39     :``pyasn1.decode(asn1Spec=pyasn1.CertificateList())``:
  40      ~22 min (``pyasn1 == 0.2.3``)
  41
  42 There are drawbacks:
  43
  44 * No old Python versions support
  45 * Strings are not validated in any way, except just trying to be decoded
  46   in ``ascii``, ``iso-8859-1``, ``utf-8/16/32`` correspondingly
  47 * No REAL, RELATIVE OID, EXTERNAL, INSTANCE OF, EMBEDDED PDV, CHARACTER STRING