Convenient decod() helper method

[pyderasn.git] / pyderasn.py

diff --git a/pyderasn.py b/pyderasn.py
index e8e200c69196820912b314f0fa7e84844eeb47d0..5f0c0343ccd0d4153d29e6328fde4a73882229ec 100755 (executable)
--- a/pyderasn.py
+++ b/pyderasn.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # coding: utf-8
 # PyDERASN -- Python ASN.1 DER/BER codec with abstract structures
 #!/usr/bin/env python
 # coding: utf-8
 # PyDERASN -- Python ASN.1 DER/BER codec with abstract structures

-# Copyright (C) 2017-2019 Sergey Matveev <stargrave@stargrave.org>
+# Copyright (C) 2017-2020 Sergey Matveev <stargrave@stargrave.org>

 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as


@@ -517,6 +517,11 @@ lengths will be invalid in that case.
    This option should be used only for skipping some decode errors, just
    to see the decoded structure somehow.
 
    This option should be used only for skipping some decode errors, just
    to see the decoded structure somehow.
 

+Base Obj
+--------
+.. autoclass:: pyderasn.Obj
+   :members:
+

 Primitive types
 ---------------
 
 Primitive types
 ---------------
 


@@ -626,10 +631,10 @@ Various
 .. autofunction:: pyderasn.tag_decode
 .. autofunction:: pyderasn.tag_ctxp
 .. autofunction:: pyderasn.tag_ctxc
 .. autofunction:: pyderasn.tag_decode
 .. autofunction:: pyderasn.tag_ctxp
 .. autofunction:: pyderasn.tag_ctxc

-.. autoclass:: pyderasn.Obj

 .. autoclass:: pyderasn.DecodeError
    :members: __init__
 .. autoclass:: pyderasn.NotEnoughData
 .. autoclass:: pyderasn.DecodeError
    :members: __init__
 .. autoclass:: pyderasn.NotEnoughData

+.. autoclass:: pyderasn.ExceedingData

 .. autoclass:: pyderasn.LenIndefForm
 .. autoclass:: pyderasn.TagMismatch
 .. autoclass:: pyderasn.InvalidLength
 .. autoclass:: pyderasn.LenIndefForm
 .. autoclass:: pyderasn.TagMismatch
 .. autoclass:: pyderasn.InvalidLength


@@ -673,6 +678,7 @@ except ImportError:  # pragma: no cover
     def colored(what, *args, **kwargs):
         return what
 
     def colored(what, *args, **kwargs):
         return what
 

+__version__ = "5.6"

 
 __all__ = (
     "Any",
 
 __all__ = (
     "Any",


@@ -684,6 +690,7 @@ __all__ = (
     "DecodeError",
     "DecodePathDefBy",
     "Enumerated",
     "DecodeError",
     "DecodePathDefBy",
     "Enumerated",

+    "ExceedingData",

     "GeneralizedTime",
     "GeneralString",
     "GraphicString",
     "GeneralizedTime",
     "GeneralString",
     "GraphicString",


@@ -794,6 +801,18 @@ class NotEnoughData(DecodeError):
     pass
 
 
     pass
 
 

+class ExceedingData(ASN1Error):
+    def __init__(self, nbytes):
+        super(ExceedingData, self).__init__()
+        self.nbytes = nbytes
+
+    def __str__(self):
+        return "%d trailing bytes" % self.nbytes
+
+    def __repr__(self):
+        return "%s(%s)" % (self.__class__.__name__, self)
+
+

 class LenIndefForm(DecodeError):
     pass
 
 class LenIndefForm(DecodeError):
     pass
 


@@ -1019,9 +1038,9 @@ def len_decode(data):
 ########################################################################
 
 class AutoAddSlots(type):
 ########################################################################
 
 class AutoAddSlots(type):

-    def __new__(mcs, name, bases, _dict):
+    def __new__(cls, name, bases, _dict):

         _dict["__slots__"] = _dict.get("__slots__", ())
         _dict["__slots__"] = _dict.get("__slots__", ())

-        return type.__new__(mcs, name, bases, _dict)
+        return type.__new__(cls, name, bases, _dict)

 
 
 @add_metaclass(AutoAddSlots)
 
 
 @add_metaclass(AutoAddSlots)


@@ -1095,10 +1114,14 @@ class Obj(object):
 
     @property
     def tlen(self):
 
     @property
     def tlen(self):

+        """See :ref:`decoding`
+        """

         return len(self.tag)
 
     @property
     def tlvlen(self):
         return len(self.tag)
 
     @property
     def tlvlen(self):

+        """See :ref:`decoding`
+        """

         return self.tlen + self.llen + self.vlen
 
     def __str__(self):  # pragma: no cover
         return self.tlen + self.llen + self.vlen
 
     def __str__(self):  # pragma: no cover


@@ -1123,6 +1146,10 @@ class Obj(object):
         raise NotImplementedError()
 
     def encode(self):
         raise NotImplementedError()
 
     def encode(self):

+        """Encode the structure
+
+        :returns: DER representation
+        """

         raw = self._encode()
         if self._expl is None:
             return raw
         raw = self._encode()
         if self._expl is None:
             return raw


@@ -1150,6 +1177,8 @@ class Obj(object):
                          determine if tag satisfies the scheme)
         :param _ctx_immutable: do we need to copy ``ctx`` before using it
         :returns: (Obj, remaining data)
                          determine if tag satisfies the scheme)
         :param _ctx_immutable: do we need to copy ``ctx`` before using it
         :returns: (Obj, remaining data)

+
+        .. seealso:: :ref:`decoding`

         """
         if ctx is None:
             ctx = {}
         """
         if ctx is None:
             ctx = {}


@@ -1165,7 +1194,7 @@ class Obj(object):
                 tag_only=tag_only,
             )
             if tag_only:
                 tag_only=tag_only,
             )
             if tag_only:

-                return
+                return None

             obj, tail = result
         else:
             try:
             obj, tail = result
         else:
             try:


@@ -1203,7 +1232,7 @@ class Obj(object):
                     tag_only=tag_only,
                 )
                 if tag_only:  # pragma: no cover
                     tag_only=tag_only,
                 )
                 if tag_only:  # pragma: no cover

-                    return
+                    return None

                 obj, tail = result
                 eoc_expected, tail = tail[:EOC_LEN], tail[EOC_LEN:]
                 if eoc_expected.tobytes() != EOC:
                 obj, tail = result
                 eoc_expected, tail = tail[:EOC_LEN], tail[EOC_LEN:]
                 if eoc_expected.tobytes() != EOC:


@@ -1238,7 +1267,7 @@ class Obj(object):
                     tag_only=tag_only,
                 )
                 if tag_only:  # pragma: no cover
                     tag_only=tag_only,
                 )
                 if tag_only:  # pragma: no cover

-                    return
+                    return None

                 obj, tail = result
                 if obj.tlvlen < l and not ctx.get("allow_expl_oob", False):
                     raise DecodeError(
                 obj, tail = result
                 if obj.tlvlen < l and not ctx.get("allow_expl_oob", False):
                     raise DecodeError(


@@ -1249,42 +1278,80 @@ class Obj(object):
                     )
         return obj, (tail if leavemm else tail.tobytes())
 
                     )
         return obj, (tail if leavemm else tail.tobytes())
 

+    def decod(self, data, offset=0, decode_path=(), ctx=None):
+        """Decode the data, check that tail is empty
+
+        :raises ExceedingData: if tail is not empty
+
+        This is just a wrapper over :py:meth:`pyderasn.Obj.decode`
+        (decode without tail) that also checks that there is no
+        trailing data left.
+        """
+        obj, tail = self.decode(
+            data,
+            offset=offset,
+            decode_path=decode_path,
+            ctx=ctx,
+            leavemm=True,
+        )
+        if len(tail) > 0:
+            raise ExceedingData(len(tail))
+        return obj
+

     @property
     def expled(self):
     @property
     def expled(self):

+        """See :ref:`decoding`
+        """

         return self._expl is not None
 
     @property
     def expl_tag(self):
         return self._expl is not None
 
     @property
     def expl_tag(self):

+        """See :ref:`decoding`
+        """

         return self._expl
 
     @property
     def expl_tlen(self):
         return self._expl
 
     @property
     def expl_tlen(self):

+        """See :ref:`decoding`
+        """

         return len(self._expl)
 
     @property
     def expl_llen(self):
         return len(self._expl)
 
     @property
     def expl_llen(self):

+        """See :ref:`decoding`
+        """

         if self.expl_lenindef:
             return 1
         return len(len_encode(self.tlvlen))
 
     @property
     def expl_offset(self):
         if self.expl_lenindef:
             return 1
         return len(len_encode(self.tlvlen))
 
     @property
     def expl_offset(self):

+        """See :ref:`decoding`
+        """

         return self.offset - self.expl_tlen - self.expl_llen
 
     @property
     def expl_vlen(self):
         return self.offset - self.expl_tlen - self.expl_llen
 
     @property
     def expl_vlen(self):

+        """See :ref:`decoding`
+        """

         return self.tlvlen
 
     @property
     def expl_tlvlen(self):
         return self.tlvlen
 
     @property
     def expl_tlvlen(self):

+        """See :ref:`decoding`
+        """

         return self.expl_tlen + self.expl_llen + self.expl_vlen
 
     @property
     def fulloffset(self):
         return self.expl_tlen + self.expl_llen + self.expl_vlen
 
     @property
     def fulloffset(self):

+        """See :ref:`decoding`
+        """

         return self.expl_offset if self.expled else self.offset
 
     @property
     def fulllen(self):
         return self.expl_offset if self.expled else self.offset
 
     @property
     def fulllen(self):

+        """See :ref:`decoding`
+        """

         return self.expl_tlvlen if self.expled else self.tlvlen
 
     def pps_lenindef(self, decode_path):
         return self.expl_tlvlen if self.expled else self.tlvlen
 
     def pps_lenindef(self, decode_path):


@@ -1747,7 +1814,7 @@ class Boolean(Obj):
                 offset=offset,
             )
         if tag_only:
                 offset=offset,
             )
         if tag_only:

-            return
+            return None

         try:
             l, _, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, _, v = len_decode(lv)
         except DecodeError as err:


@@ -1977,6 +2044,7 @@ class Integer(Obj):
         for name, value in iteritems(self.specs):
             if value == self._value:
                 return name
         for name, value in iteritems(self.specs):
             if value == self._value:
                 return name

+        return None

 
     def __call__(
             self,
 
     def __call__(
             self,


@@ -2056,7 +2124,7 @@ class Integer(Obj):
                 offset=offset,
             )
         if tag_only:
                 offset=offset,
             )
         if tag_only:

-            return
+            return None

         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:


@@ -2276,7 +2344,7 @@ class BitString(Obj):
                     if not frozenset(value) <= SET01:
                         raise ValueError("B's coding contains unacceptable chars")
                     return self._bits2octets(value)
                     if not frozenset(value) <= SET01:
                         raise ValueError("B's coding contains unacceptable chars")
                     return self._bits2octets(value)

-                elif value.endswith("'H"):
+                if value.endswith("'H"):

                     value = value[1:-2]
                     return (
                         len(value) * 4,
                     value = value[1:-2]
                     return (
                         len(value) * 4,


@@ -2284,8 +2352,7 @@ class BitString(Obj):
                     )
             if isinstance(value, binary_type):
                 return (len(value) * 8, value)
                     )
             if isinstance(value, binary_type):
                 return (len(value) * 8, value)

-            else:
-                raise InvalidValueType((self.__class__, string_types, binary_type))
+            raise InvalidValueType((self.__class__, string_types, binary_type))

         if isinstance(value, tuple):
             if (
                     len(value) == 2 and
         if isinstance(value, tuple):
             if (
                     len(value) == 2 and


@@ -2404,7 +2471,7 @@ class BitString(Obj):
             octets,
         ))
 
             octets,
         ))
 

-    def _decode_chunk(self, lv, offset, decode_path, ctx):
+    def _decode_chunk(self, lv, offset, decode_path):

         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:


@@ -2474,8 +2541,8 @@ class BitString(Obj):
             )
         if t == self.tag:
             if tag_only:  # pragma: no cover
             )
         if t == self.tag:
             if tag_only:  # pragma: no cover

-                return
-            return self._decode_chunk(lv, offset, decode_path, ctx)
+                return None
+            return self._decode_chunk(lv, offset, decode_path)

         if t == self.tag_constructed:
             if not ctx.get("bered", False):
                 raise DecodeError(
         if t == self.tag_constructed:
             if not ctx.get("bered", False):
                 raise DecodeError(


@@ -2485,7 +2552,7 @@ class BitString(Obj):
                     offset=offset,
                 )
             if tag_only:  # pragma: no cover
                     offset=offset,
                 )
             if tag_only:  # pragma: no cover

-                return
+                return None

             lenindef = False
             try:
                 l, llen, v = len_decode(lv)
             lenindef = False
             try:
                 l, llen, v = len_decode(lv)


@@ -2794,7 +2861,7 @@ class OctetString(Obj):
             self._value,
         ))
 
             self._value,
         ))
 

-    def _decode_chunk(self, lv, offset, decode_path, ctx):
+    def _decode_chunk(self, lv, offset, decode_path):

         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:


@@ -2850,8 +2917,8 @@ class OctetString(Obj):
             )
         if t == self.tag:
             if tag_only:
             )
         if t == self.tag:
             if tag_only:

-                return
-            return self._decode_chunk(lv, offset, decode_path, ctx)
+                return None
+            return self._decode_chunk(lv, offset, decode_path)

         if t == self.tag_constructed:
             if not ctx.get("bered", False):
                 raise DecodeError(
         if t == self.tag_constructed:
             if not ctx.get("bered", False):
                 raise DecodeError(


@@ -2861,7 +2928,7 @@ class OctetString(Obj):
                     offset=offset,
                 )
             if tag_only:
                     offset=offset,
                 )
             if tag_only:

-                return
+                return None

             lenindef = False
             try:
                 l, llen, v = len_decode(lv)
             lenindef = False
             try:
                 l, llen, v = len_decode(lv)


@@ -3077,7 +3144,7 @@ class Null(Obj):
                 offset=offset,
             )
         if tag_only:  # pragma: no cover
                 offset=offset,
             )
         if tag_only:  # pragma: no cover

-            return
+            return None

         try:
             l, _, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, _, v = len_decode(lv)
         except DecodeError as err:


@@ -3332,7 +3399,7 @@ class ObjectIdentifier(Obj):
                 offset=offset,
             )
         if tag_only:  # pragma: no cover
                 offset=offset,
             )
         if tag_only:  # pragma: no cover

-            return
+            return None

         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:
         try:
             l, llen, v = len_decode(lv)
         except DecodeError as err:


@@ -4250,7 +4317,7 @@ class Choice(Obj):
                 offset=offset,
             )
         if tag_only:  # pragma: no cover
                 offset=offset,
             )
         if tag_only:  # pragma: no cover

-            return
+            return None

         value, tail = spec.decode(
             tlv,
             offset=offset,
         value, tail = spec.decode(
             tlv,
             offset=offset,


@@ -4719,9 +4786,8 @@ class Sequence(Obj):
                 if spec.optional:
                     continue
                 return False
                 if spec.optional:
                     continue
                 return False

-            else:
-                if not value.ready:
-                    return False
+            if not value.ready:
+                return False

         return True
 
     @property
         return True
 
     @property


@@ -4833,7 +4899,7 @@ class Sequence(Obj):
                 offset=offset,
             )
         if tag_only:  # pragma: no cover
                 offset=offset,
             )
         if tag_only:  # pragma: no cover

-            return
+            return None

         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:
         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:


@@ -5083,7 +5149,7 @@ class Set(Sequence):
                 offset=offset,
             )
         if tag_only:
                 offset=offset,
             )
         if tag_only:

-            return
+            return None

         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:
         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:


@@ -5416,7 +5482,7 @@ class SequenceOf(Obj):
                 offset=offset,
             )
         if tag_only:
                 offset=offset,
             )
         if tag_only:

-            return
+            return None

         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:
         lenindef = False
         ctx_bered = ctx.get("bered", False)
         try:


@@ -5720,7 +5786,7 @@ def main():  # pragma: no cover
     print(pprinter(
         obj,
         oid_maps=oid_maps,
     print(pprinter(
         obj,
         oid_maps=oid_maps,

-        with_colours=True if environ.get("NO_COLOR") is None else False,
+        with_colours=environ.get("NO_COLOR") is None,

         with_decode_path=args.print_decode_path,
         decode_path_only=(
             () if args.decode_path_only is None else
         with_decode_path=args.print_decode_path,
         decode_path_only=(
             () if args.decode_path_only is None else