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
 
 
     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)
 * 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:
                       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).
  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
 -----------------------
 
 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
 
 
     % 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
 ------------------
 
 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):
 
     % 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
 ========
 
 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)
 * 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
 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)
 * 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
     (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.
 
 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
 ====
 
 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
 .. _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!
 
 
 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 ------------------------
 
 
 ------------------------ >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
 #!/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
 # 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/>.
 # 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()
 
     >>> 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``).
 
 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:
 
 
 .. _ctx:
 


@@ -206,6 +206,7 @@ decoding process.
 
 Currently available context options:
 
 
 Currently available context options:
 

+* :ref:`bered <bered_ctx>`

 * :ref:`defines_by_path <defines_by_path_ctx>`
 * :ref:`strict_default_existence <strict_default_existence_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.
 
 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
 ---------------
 
 Primitive types
 ---------------
 


@@ -5018,7 +5046,7 @@ def generic_decoder():  # pragma: no cover
 
 def main():  # pragma: no cover
     import argparse
 
 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,
     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,
 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",
     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
 # 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
 # Copyright (C) 2017-2018 Sergey Matveev <stargrave@stargrave.org>
 #
 # This program is free software: you can redistribute it and/or modify