X-Git-Url: http://www.git.cypherpunks.ru/?p=pyderasn.git;a=blobdiff_plain;f=pyderasn.py;h=56eec8d7953e62d6b63295b80795d1dd148d8aed;hp=fb043feeb76d038f4579695826131dcf3636f740;hb=7aed684a10179b2e57e81369e956ac6df4fb135e;hpb=1822faabc359cd416dddb9a56fd03f20d9651e09 diff --git a/pyderasn.py b/pyderasn.py index fb043fe..56eec8d 100755 --- a/pyderasn.py +++ b/pyderasn.py @@ -135,6 +135,8 @@ example ``TBSCertificate`` sequence holds defaulted, explicitly tagged When default argument is used and value is not specified, then it equals to default one. +.. _bounds: + Size constraints ________________ @@ -164,8 +166,10 @@ then :py:exc:`pyderasn.ObjNotReady` exception will be raised. All objects have ``copy()`` method, returning its copy, that can be safely mutated. +.. _decoding: + Decoding -________ +-------- Decoding is performed using ``decode()`` method. ``offset`` optional argument could be used to set initial object's offset in the binary @@ -191,8 +195,10 @@ lesser than ``offset``), ``expl_tlen``, ``expl_llen``, ``expl_vlen`` When error occurs, then :py:exc:`pyderasn.DecodeError` is raised. +.. _pprinting: + Pretty printing -_______________ +--------------- All objects have ``pps()`` method, that is a generator of :py:class:`pyderasn.PP` namedtuple, holding various raw information @@ -209,6 +215,116 @@ all object ``repr``. But it is easy to write custom formatters. >>> print(pprint(obj)) 0 [1,1, 2] INTEGER -12345 +.. _definedby: + +DEFINED BY +---------- + +ASN.1 structures often have ANY and OCTET STRING fields, that are +DEFINED BY some previously met ObjectIdentifier. This library provides +ability to specify mapping between some OID and field that must be +decoded with specific specification. + +defines kwarg +_____________ + +:py:class:`pyderasn.ObjectIdentifier` field inside +:py:class:`pyderasn.Sequence` can hold mapping between OIDs and +necessary for decoding structrures. For example, CMS (:rfc:`5652`) +container:: + + class ContentInfo(Sequence): + schema = ( + ("contentType", ContentType(defines=("content", { + id_digestedData: DigestedData(), + id_signedData: SignedData(), + }))), + ("content", Any(expl=tag_ctxc(0))), + ) + +``contentType`` field tells that it defines that ``content`` must be +decoded with ``SignedData`` specification, if ``contentType`` equals to +``id-signedData``. The same applies to ``DigestedData``. If +``contentType`` contains unknown OID, then no automatic decoding is +done. + +Following types can be automatically decoded (DEFINED BY): + +* :py:class:`pyderasn.Any` +* :py:class:`pyderasn.OctetString` +* :py:class:`pyderasn.SequenceOf`/:py:class:`pyderasn.SetOf` + ``Any``/``OctetString``-s + +When any of those fields is automatically decoded, then ``.defined`` +attribute contains ``(OID, value)`` tuple. OID tell by which OID it was +defined, ``value`` contains corresponding decoded value. For example +above, ``content_info["content"].defined == (id_signedData, +signed_data)``. + +defines_by_path kwarg +_____________________ + +Sometimes you either can not or do not want to explicitly set *defines* +in the scheme. You can dynamically apply those definitions when calling +``.decode()`` method. + +Decode method takes optional ``defines_by_path`` keyword argument that +must be sequence of following tuples:: + + (decode_path, defines) + +where ``decode_path`` is a tuple holding so-called decode path to the +exact :py:class:`pyderasn.ObjectIdentifier` field you want to apply +``defines``, holding exactly the same value as accepted in its keyword +argument. + +For example, again for CMS, you want to automatically decode +``SignedData`` and CMC's (:rfc:`5272`) ``PKIData`` and ``PKIResponse`` +structures it may hold. Also, automatically decode ``controlSequence`` +of ``PKIResponse``:: + + content_info, tail = ContentInfo().decode(data, defines_by_path=( + ( + ("contentType",), + ("content", {id_signedData: SignedData()}), + ), + ( + ( + "content", + decode_path_defby(id_signedData), + "encapContentInfo", + "eContentType", + ), + ("eContent", { + id_cct_PKIData: PKIData(), + id_cct_PKIResponse: PKIResponse(), + }), + ), + ( + ( + "content", + decode_path_defby(id_signedData), + "encapContentInfo", + "eContent", + decode_path_defby(id_cct_PKIResponse), + "controlSequence", + any, + "attrType", + ), + ("attrValues", { + id_cmc_recipientNonce: RecipientNonce(), + id_cmc_senderNonce: SenderNonce(), + id_cmc_statusInfoV2: CMCStatusInfoV2(), + id_cmc_transactionId: TransactionId(), + }), + ), + )) + +Pay attention for :py:func:`pyderasn.decode_path_defby` and ``any``. +First function is useful for path construction when some automatic +decoding is already done. ``any`` is used for human readability and +means literally any value it meet -- useful for sequence and set of-s. + Primitive types --------------- @@ -338,6 +454,7 @@ __all__ = ( "Boolean", "BoundsError", "Choice", + "decode_path_defby", "DecodeError", "Enumerated", "GeneralizedTime", @@ -747,7 +864,7 @@ class Obj(object): def _encode(self): # pragma: no cover raise NotImplementedError() - def _decode(self, tlv, offset=0, decode_path=()): # pragma: no cover + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): # pragma: no cover raise NotImplementedError() def encode(self): @@ -756,13 +873,14 @@ class Obj(object): return raw return b"".join((self._expl, len_encode(len(raw)), raw)) - def decode(self, data, offset=0, leavemm=False, decode_path=()): + def decode(self, data, offset=0, leavemm=False, decode_path=(), defines_by_path=None): """Decode the data :param data: either binary or memoryview :param int offset: initial data's offset :param bool leavemm: do we need to leave memoryview of remaining data as is, or convert it to bytes otherwise + :param defines_by_path: :ref:`Read about DEFINED BY ` :returns: (Obj, remaining data) """ tlv = memoryview(data) @@ -771,6 +889,7 @@ class Obj(object): tlv, offset, decode_path=decode_path, + defines_by_path=defines_by_path, ) else: try: @@ -807,7 +926,8 @@ class Obj(object): obj, tail = self._decode( v, offset=offset + tlen + llen, - decode_path=(), + decode_path=decode_path, + defines_by_path=defines_by_path, ) return obj, (tail if leavemm else tail.tobytes()) @@ -840,6 +960,12 @@ class Obj(object): return self.expl_tlen + self.expl_llen + self.expl_vlen +def decode_path_defby(defined_by): + """DEFINED BY representation inside decode path + """ + return "DEFINED BY (%s)" % defined_by + + ######################################################################## # Pretty printing ######################################################################## @@ -1109,7 +1235,7 @@ class Boolean(Obj): (b"\xFF" if self._value else b"\x00"), )) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -1402,7 +1528,7 @@ class Integer(Obj): break return b"".join((self.tag, len_encode(len(octets)), octets)) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -1735,7 +1861,7 @@ class BitString(Obj): octets, )) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -1856,7 +1982,7 @@ class OctetString(Obj): >>> OctetString(b"hell", bounds=(4, 4)) OCTET STRING 4 bytes 68656c6c """ - __slots__ = ("_bound_min", "_bound_max") + __slots__ = ("_bound_min", "_bound_max", "defined") tag_default = tag_encode(4) asn1_type_name = "OCTET STRING" @@ -1904,6 +2030,7 @@ class OctetString(Obj): ) if self._value is None: self._value = default + self.defined = None def _value_sanitize(self, value): if issubclass(value.__class__, OctetString): @@ -1981,7 +2108,7 @@ class OctetString(Obj): self._value, )) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -2056,6 +2183,11 @@ class OctetString(Obj): expl_llen=self.expl_llen if self.expled else None, expl_vlen=self.expl_vlen if self.expled else None, ) + defined_by, defined = self.defined or (None, None) + if defined_by is not None: + yield defined.pps( + decode_path=decode_path + (decode_path_defby(defined_by),) + ) class Null(Obj): @@ -2125,7 +2257,7 @@ class Null(Obj): def _encode(self): return self.tag + len_encode(0) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -2205,13 +2337,14 @@ class ObjectIdentifier(Obj): Traceback (most recent call last): pyderasn.InvalidOID: unacceptable first arc value """ - __slots__ = () + __slots__ = ("defines",) tag_default = tag_encode(6) asn1_type_name = "OBJECT IDENTIFIER" def __init__( self, value=None, + defines=None, impl=None, expl=None, default=None, @@ -2222,6 +2355,13 @@ class ObjectIdentifier(Obj): :param value: set the value. Either tuples of integers, string of "."-concatenated integers, or :py:class:`pyderasn.ObjectIdentifier` object + :param defines: tuple of two elements. First one is a name of + field inside :py:class:`pyderasn.Sequence`, + defining with that OID. Second element is a + ``{OID: pyderasn.Obj()}`` dictionary, mapping + between current OID value and structure applied + to defined field. + :ref:`Read about DEFINED BY ` :param bytes impl: override default tag with ``IMPLICIT`` one :param bytes expl: override default tag with ``EXPLICIT`` one :param default: set default value. Type same as in ``value`` @@ -2246,6 +2386,7 @@ class ObjectIdentifier(Obj): ) if self._value is None: self._value = default + self.defines = defines def __add__(self, their): if isinstance(their, self.__class__): @@ -2283,6 +2424,7 @@ class ObjectIdentifier(Obj): def copy(self): obj = self.__class__() obj._value = self._value + obj.defines = self.defines obj.tag = self.tag obj._expl = self._expl obj.default = self.default @@ -2324,6 +2466,7 @@ class ObjectIdentifier(Obj): def __call__( self, value=None, + defines=None, impl=None, expl=None, default=None, @@ -2331,6 +2474,7 @@ class ObjectIdentifier(Obj): ): return self.__class__( value=value, + defines=self.defines if defines is None else defines, impl=self.tag if impl is None else impl, expl=self._expl if expl is None else expl, default=self.default if default is None else default, @@ -2356,7 +2500,7 @@ class ObjectIdentifier(Obj): v = b"".join(octets) return b"".join((self.tag, len_encode(len(v)), v)) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, _, lv = tag_strip(tlv) except DecodeError as err: @@ -3123,7 +3267,7 @@ class Choice(Obj): self._assert_ready() return self._value[1].encode() - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): for choice, spec in self.specs.items(): try: value, tail = spec.decode( @@ -3131,6 +3275,7 @@ class Choice(Obj): offset=offset, leavemm=True, decode_path=decode_path + (choice,), + defines_by_path=defines_by_path, ) except TagMismatch: continue @@ -3219,7 +3364,7 @@ class Any(Obj): >>> hexenc(bytes(a)) b'0x040x0bhello world' """ - __slots__ = () + __slots__ = ("defined",) tag_default = tag_encode(0) asn1_type_name = "ANY" @@ -3240,6 +3385,7 @@ class Any(Obj): """ super(Any, self).__init__(None, expl, None, optional, _decoded) self._value = None if value is None else self._value_sanitize(value) + self.defined = None def _value_sanitize(self, value): if isinstance(value, self.__class__): @@ -3296,7 +3442,7 @@ class Any(Obj): self._assert_ready() return self._value - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, tlen, lv = tag_strip(tlv) l, llen, v = len_decode(lv) @@ -3347,19 +3493,36 @@ class Any(Obj): expl_llen=self.expl_llen if self.expled else None, expl_vlen=self.expl_vlen if self.expled else None, ) + defined_by, defined = self.defined or (None, None) + if defined_by is not None: + yield defined.pps( + decode_path=decode_path + (decode_path_defby(defined_by),) + ) ######################################################################## # ASN.1 constructed types ######################################################################## +def get_def_by_path(defines_by_path, sub_decode_path): + """Get define by decode path + """ + for path, define in defines_by_path: + if len(path) != len(sub_decode_path): + continue + for p1, p2 in zip(path, sub_decode_path): + if (p1 != any) and (p1 != p2): + break + else: + return define + + class Sequence(Obj): """``SEQUENCE`` structure type You have to make specification of sequence:: class Extension(Sequence): - __slots__ = () schema = ( ("extnID", ObjectIdentifier()), ("critical", Boolean(default=False)), @@ -3567,7 +3730,7 @@ class Sequence(Obj): v = b"".join(self._encoded_values()) return b"".join((self.tag, len_encode(len(v)), v)) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, tlen, lv = tag_strip(tlv) except DecodeError as err: @@ -3602,27 +3765,81 @@ class Sequence(Obj): v, tail = v[:l], v[l:] sub_offset = offset + tlen + llen values = {} + defines = {} for name, spec in self.specs.items(): if len(v) == 0 and spec.optional: continue + sub_decode_path = decode_path + (name,) try: value, v_tail = spec.decode( v, sub_offset, leavemm=True, - decode_path=decode_path + (name,), + decode_path=sub_decode_path, + defines_by_path=defines_by_path, ) except TagMismatch: if spec.optional: continue raise + + defined = defines.pop(name, None) + if defined is not None: + defined_by, defined_spec = defined + if issubclass(value.__class__, SequenceOf): + for i, _value in enumerate(value): + sub_sub_decode_path = sub_decode_path + ( + str(i), + decode_path_defby(defined_by), + ) + defined_value, defined_tail = defined_spec.decode( + memoryview(bytes(_value)), + sub_offset + value.tlen + value.llen, + leavemm=True, + decode_path=sub_sub_decode_path, + defines_by_path=defines_by_path, + ) + if len(defined_tail) > 0: + raise DecodeError( + "remaining data", + klass=self.__class__, + decode_path=sub_sub_decode_path, + offset=offset, + ) + _value.defined = (defined_by, defined_value) + else: + defined_value, defined_tail = defined_spec.decode( + memoryview(bytes(value)), + sub_offset + value.tlen + value.llen, + leavemm=True, + decode_path=sub_decode_path + (decode_path_defby(defined_by),), + defines_by_path=defines_by_path, + ) + if len(defined_tail) > 0: + raise DecodeError( + "remaining data", + klass=self.__class__, + decode_path=sub_decode_path + (decode_path_defby(defined_by),), + offset=offset, + ) + value.defined = (defined_by, defined_value) + sub_offset += (value.expl_tlvlen if value.expled else value.tlvlen) v = v_tail if spec.default is not None and value == spec.default: # Encoded default values are not valid in DER, - # but we still allow that + # but we allow that anyway continue values[name] = value + + spec_defines = getattr(spec, "defines", None) + if defines_by_path is not None and spec_defines is None: + spec_defines = get_def_by_path(defines_by_path, sub_decode_path) + if spec_defines is not None: + what, schema = spec_defines + defined = schema.get(value, None) + if defined is not None: + defines[what] = (value, defined) if len(v) > 0: raise DecodeError( "remaining data", @@ -3691,7 +3908,7 @@ class Set(Sequence): v = b"".join(raws) return b"".join((self.tag, len_encode(len(v)), v)) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, tlen, lv = tag_strip(tlv) except DecodeError as err: @@ -3734,6 +3951,7 @@ class Set(Sequence): sub_offset, leavemm=True, decode_path=decode_path + (name,), + defines_by_path=defines_by_path, ) except TagMismatch: continue @@ -3943,7 +4161,7 @@ class SequenceOf(Obj): v = b"".join(self._encoded_values()) return b"".join((self.tag, len_encode(len(v)), v)) - def _decode(self, tlv, offset=0, decode_path=()): + def _decode(self, tlv, offset=0, decode_path=(), defines_by_path=None): try: t, tlen, lv = tag_strip(tlv) except DecodeError as err: @@ -3985,6 +4203,7 @@ class SequenceOf(Obj): sub_offset, leavemm=True, decode_path=decode_path + (str(len(_value)),), + defines_by_path=defines_by_path, ) sub_offset += (value.expl_tlvlen if value.expled else value.tlvlen) v = v_tail