From 2d45a224943c79e95cbd4913b44420788bc6c17d Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Sun, 20 May 2018 15:51:14 +0300 Subject: [PATCH] BER usage documentation --- README | 3 ++- doc/examples.rst | 8 ++++---- doc/features.rst | 2 +- doc/index.rst | 15 +++++++-------- doc/news.rst | 8 ++++++++ makedist.sh | 2 +- pyderasn.py | 40 ++++++++++++++++++++++++++++++++++------ setup.py | 2 +- tests/test_pyderasn.py | 2 +- 9 files changed, 59 insertions(+), 23 deletions(-) diff --git a/README b/README index 8d6d2a0..925fbf4 100644 --- a/README +++ b/README @@ -1,8 +1,9 @@ -PyDERASN -- ASN.1 DER library for Python +PyDERASN -- ASN.1 DER/BER library for Python I'm going to build my own ASN.1 library with slots and blobs! (C) PyDERASN's author +* BER/CER/DER decoding, DER encoding * Basic ASN.1 data types (X.208): BOOLEAN, INTEGER, BIT STRING, OCTET STRING, NULL, OBJECT IDENTIFIER, ENUMERATED, all strings, UTCTime, GeneralizedTime, CHOICE, ANY, SEQUENCE (OF), SET (OF) diff --git a/doc/examples.rst b/doc/examples.rst index e95369c..1d836f5 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -241,7 +241,7 @@ Let's parse that output, human:: 12 13 9 10 :0: - Offset of the object, where its DER encoding begins. + Offset of the object, where its DER/BER encoding begins. Pay attention that it does **not** include explicit tag. :1: If explicit tag exists, then this is its length (tag + encoded length). @@ -288,8 +288,8 @@ Let's parse that output, human:: As command line utility ----------------------- -You can decode DER files using command line abilities and get the same -picture as above by executing:: +You can decode DER/BER files using command line abilities and get the +same picture as above by executing:: % python -m pyderasn --schema tests.test_crts:Certificate path/to/file @@ -358,7 +358,7 @@ then you can pass it to pretty printer to see human readable OIDs:: Descriptive errors ------------------ -If you have bad DER, then errors will show you where error occurred:: +If you have bad DER/BER, then errors will show you where error occurred:: % python -m pyderasn --schema tests.test_crts:Certificate path/to/bad/file Traceback (most recent call last): diff --git a/doc/features.rst b/doc/features.rst index dcbd0eb..d23729f 100644 --- a/doc/features.rst +++ b/doc/features.rst @@ -1,6 +1,7 @@ Features ======== +* BER/CER/DER decoding, DER encoding * Basic ASN.1 data types (X.208): BOOLEAN, INTEGER, BIT STRING, OCTET STRING, NULL, OBJECT IDENTIFIER, ENUMERATED, all strings, UTCTime, GeneralizedTime, CHOICE, ANY, SEQUENCE (OF), SET (OF) @@ -39,7 +40,6 @@ practice it should be relatively easy to convert ``pyasn1``'s code to There are drawbacks: * No old Python versions support -* No BER/CER support * PyDERASN does **not** have object recreation capable ``repr``-s:: pyderasn>>> repr(algo_id) diff --git a/doc/index.rst b/doc/index.rst index 0197abd..d1fca18 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,6 +1,6 @@ -======================================== -PyDERASN -- ASN.1 DER library for Python -======================================== +============================================ +PyDERASN -- ASN.1 DER/BER library for Python +============================================ .. @@ -8,11 +8,10 @@ PyDERASN -- ASN.1 DER library for Python (C) PyDERASN's author `ASN.1 `__ (Abstract Syntax -Notation One) is a standard for abstract data serialization. -`DER `__ -(Distinguished Encoding Rules) is a subset of encoding rules suitable -and widely used in cryptography-related stuff. PyDERASN is yet another -library for dealing with the data encoded that way. Although ASN.1 is +Notation One) is a standard for abstract data serialization. PyDERASN is +yet another library for dealing with ASN.1 structures, decoding them in +`BER/CER/DER `__ formats and +encoding to DER (Distinguished Encoding Rules). Although ASN.1 is written more than 30 years ago by wise Ancients (taken from ``pyasn1``'s README), it is still often can be seen anywhere in our life. diff --git a/doc/news.rst b/doc/news.rst index f8fc1e5..0732dc3 100644 --- a/doc/news.rst +++ b/doc/news.rst @@ -1,6 +1,14 @@ News ==== +.. _release3.7: + +3.7 +--- +* Experimental BER decoding support (not extensively tested, but parses + ``gpgsm`` CMS output) +* BitString's ''H notation support + .. _release3.6: 3.6 diff --git a/makedist.sh b/makedist.sh index 5869e0c..1f7f9c8 100755 --- a/makedist.sh +++ b/makedist.sh @@ -41,7 +41,7 @@ Subject: PyDERASN $release release announcement I am pleased to announce PyDERASN $release release availability! -PyDERASN is free software pure Python ASN.1 DER library. +PyDERASN is free software pure Python ASN.1 DER/BER library. ------------------------ >8 ------------------------ diff --git a/pyderasn.py b/pyderasn.py index ffc788c..f7e6c4c 100755 --- a/pyderasn.py +++ b/pyderasn.py @@ -1,6 +1,6 @@ #!/usr/bin/env python # coding: utf-8 -# PyDERASN -- Python ASN.1 DER codec with abstract structures +# PyDERASN -- Python ASN.1 DER/BER codec with abstract structures # Copyright (C) 2017-2018 Sergey Matveev # # This program is free software: you can redistribute it and/or modify @@ -16,10 +16,10 @@ # You should have received a copy of the GNU Lesser General Public # License along with this program. If not, see # . -"""Python ASN.1 DER codec with abstract structures +"""Python ASN.1 DER/BER codec with abstract structures -This library allows you to marshal and unmarshal various structures in -ASN.1 DER format, like this: +This library allows you to marshal various structures in ASN.1 DER +format, unmarshal them in BER/CER/DER ones. >>> i = Integer(123) >>> raw = i.encode() @@ -193,7 +193,7 @@ explicit tag. If you want to know information about it, then use: lesser than ``offset``), ``expl_tlen``, ``expl_llen``, ``expl_vlen`` (that actually equals to ordinary ``tlvlen``). -When error occurs, then :py:exc:`pyderasn.DecodeError` is raised. +When error occurs, :py:exc:`pyderasn.DecodeError` is raised. .. _ctx: @@ -206,6 +206,7 @@ decoding process. Currently available context options: +* :ref:`bered ` * :ref:`defines_by_path ` * :ref:`strict_default_existence ` @@ -363,6 +364,33 @@ First function is useful for path construction when some automatic decoding is already done. ``any`` means literally any value it meet -- useful for SEQUENCE/SET OF-s. +.. _bered_ctx: + +BER encoding +------------ + +.. warning:: + + Currently BER support is not extensively tested. + +By default PyDERASN accepts only DER encoded data. It always encodes to +DER. But you can optionally enable BER decoding with setting ``bered`` +:ref:`context ` argument to True. Indefinite lengths and +constructed primitive types should be parsed successfully. + +* If object is encoded in BER form (not the DER one), then ``bered`` + attribute is set to True. Only ``BOOLEAN``, ``BIT STRING``, ``OCTET + STRING`` can contain it. +* If object has an indefinite length encoding, then its ``lenindef`` + attribute is set to True. Only ``BIT STRING``, ``OCTET STRING``, + ``SEQUENCE``, ``SET``, ``SEQUENCE OF``, ``SET OF``, ``ANY`` can + contain it. +* If object has an indefinite length encoded explicit tag, then + ``expl_lenindef`` is set to True. + +EOC (end-of-contents) token's length is taken in advance in object's +value length. + Primitive types --------------- @@ -5018,7 +5046,7 @@ def generic_decoder(): # pragma: no cover def main(): # pragma: no cover import argparse - parser = argparse.ArgumentParser(description="PyDERASN ASN.1 DER decoder") + parser = argparse.ArgumentParser(description="PyDERASN ASN.1 BER/DER decoder") parser.add_argument( "--skip", type=int, diff --git a/setup.py b/setup.py index 762ee5b..343a01e 100644 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ version = open("VERSION", "rb").read().strip().decode("ascii") setup( name="pyderasn", version=version, - description="Python ASN.1 DER codec with abstract structures", + description="Python ASN.1 DER/BER codec with abstract structures", long_description=open("README", "rb").read().decode("utf-8"), author="Sergey Matveev", author_email="stargrave@stargrave.org", diff --git a/tests/test_pyderasn.py b/tests/test_pyderasn.py index a07c495..8b93827 100644 --- a/tests/test_pyderasn.py +++ b/tests/test_pyderasn.py @@ -1,5 +1,5 @@ # coding: utf-8 -# PyDERASN -- Python ASN.1 DER codec with abstract structures +# PyDERASN -- Python ASN.1 DER/BER codec with abstract structures # Copyright (C) 2017-2018 Sergey Matveev # # This program is free software: you can redistribute it and/or modify -- 2.44.0