BER usage documentation

diff --git a/README b/README
index 8d6d2a070746ffe001ecf003e08fd1220ce6a42c..925fbf4b16a4d89af6f9e0bfc3bc98bc8f9e8f72 100644 (file)
--- 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 e95369c84f3f1f9155329e36fdb814fb6fd1fad9..1d836f53549a33e3900766cea81a3dcd238c6381 100644 (file)
--- 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 dcbd0ebcdc8b3ce6c9afdae23050a869411b0eef..d23729f12096bede25e86d07bb520b570257397b 100644 (file)
--- 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 0197abd30efb6c9dfd4a572e4ea178b7cb3a85b6..d1fca187f664e72ec1aa1d6da4bad8f2ddd0b357 100644 (file)
--- 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 <https://en.wikipedia.org/wiki/ASN.1>`__ (Abstract Syntax
-Notation One) is a standard for abstract data serialization.
-`DER <https://en.wikipedia.org/wiki/Distinguished_Encoding_Rules>`__
-(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 <https://en.wikipedia.org/wiki/X.690>`__ 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 f8fc1e547551eaf59df010eb89d2e12965b7d233..0732dc3512ee01e6d9a0515c1e003e93ad7a3ad2 100644 (file)
--- 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 5869e0ca72875b25c8e1703c35d1678c2596c798..1f7f9c8b80e1d40d4c0c74a3b689397fb2ce4021 100755 (executable)
--- 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 ffc788ca6cca7a8529cfa1a3ca93abc57d414675..f7e6c4c53f9cb5d5316f555ca42658b0301d4308 100755 (executable)
--- 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 <stargrave@stargrave.org>
 #
 # 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
 # <http://www.gnu.org/licenses/>.
-"""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 <bered_ctx>`
 * :ref:`defines_by_path <defines_by_path_ctx>`
 * :ref:`strict_default_existence <strict_default_existence_ctx>`
 
@@ -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 <ctx>` 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 762ee5bf85c24c22c546613edd044205ddf5ec55..343a01e0bb30b1819f192dce93c0944e5fe9f2c1 100644 (file)
--- 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 a07c495ebd5d838219b6b2be69cc011911f734cf..8b93827d1e14a4d28155925dd5660015704aff0e 100644 (file)
--- 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 <stargrave@stargrave.org>
 #
 # This program is free software: you can redistribute it and/or modify