x690 0.4.0

Pure Python X.690 implementation

Pure Python X.690 implementation

This module contains a pure Python implementation of the “x690” standard for BER encoding/decoding. Other encodings are currently unsupported but pull-requests are welcome.

Supporting New Types

Some applications may need to support types which are not defined in the X.690 standard. This is supported by this library but the types must be defined and registered.

To register a type, simply subclass x690.types.Type. This will take care of the registration. Make sure that your new type is imported before using it.

New types should define the following 3 class-variables:

TYPECLASS

A value from x690.util.TypeClass

TypeNature

A value from x690.util.TypeNature

TAG

A numerical identifier for the type

Refer to the x690 standard for more details on these values. As a general rule-of-thumb you can assume that the class is either “context” or “application” (it might be good to keep the “universal” class reserved for x690). The nature should be “primitive” for simple values and “constructed” for composed types. The tag is free to choose as long as you don’t overlap with an existing type.

To support decoding, the class must implement a decode(data: bytes) -> YourType function. The contents of data will be the raw bytes excluding the type information.

To support encoding, the class must implement the __bytes__(self) -> bytes method. This should return the raw-bytes without type-information. Wrapping with the appropriate type-information is handled by the library.

Reverse Engineering Bytes

All types defined in the x690 library provide a .pretty() method which returns a prettyfied string.

If you are confronted with a bytes-object encoded using X.690 but don’t have any documentation, you can write the following loop:

from x690 import pop_tlv

data = open("mydatafile.bin", "rb").read()

value, remaining_bytes = pop_tlv(data)
print(value.pretty())

while remaining_bytes:
    value, remaining_bytes = pop_tlv(remaining_bytes)
    print(value.pretty())

This should get you started.

If the data contain non-standard types, they will get detected as “UnknownType” and will print out the type-class, nature and tag in the pretty-printed block.

This will allow you to define your own subclass of x690.types.Type using those values. Override decode(...) in that class to handle the unknown type.

Examples

Encoding to bytes

Encoding to bytes can be done by simply calling the Python builting bytes() on instances from x690.types:

Encoding of a single value

>>> import x690.types as t
>>> myvalue = t.Integer(12)
>>> asbytes = bytes(myvalue)
>>> repr(asbytes)
b'\x02\x01\x0c'

Encoding of a composite value using Sequence

>>> import x690.types as t
>>> myvalue = t.Sequence(
...     t.Integer(12),
...     t.Integer(12),
...     t.Integer(12),
... )
>>> asbytes = bytes(myvalue)
>>> repr(asbytes)
b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'

Decoding from bytes

Decode bytes by calling x690.types.pop_tlv on your byte data. This will return a tuple where the first value contains the decoded object, and the second one will contain any remaining bytes which were not decoded.

>>> import x690
>>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'
>>> decoded, remaining_bytes = x690.pop_tlv(data)
>>> decoded
Sequence(Integer(12), Integer(12), Integer(12))
>>> remaining_bytes
b''

Type-Hinting & Enforcing

New in 0.3.0

When decoding bytes, it is possible to specify an expcted type which does two things: Firstly, it tells tools like mypy what the return type will be and secondly, it runs an internal type-check which ensures that the returned value is of the expected type. x690.exc.UnexpectedType is raised otherwise.

This does of course only work if you know the type in advance.

>>> import x690
>>> import x690.types as t
>>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'
>>> decoded, remaining_bytes = x690.pop_tlv(data, enforce_type=t.Sequence)
>>> decoded
Sequence(Integer(12), Integer(12), Integer(12))
>>> remaining_bytes
b''

Strict Decoding

New in 0.3.0

When decoding using pop_tlv and you don’t expect any remaining bytes, use strict=True which will raise x690.exc.IncompleteDecoding if there’s any remaining data.

>>> import x690
>>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0cjunk-bytes'
>>> decoded, remaining_bytes = x690.pop_tlv(data, strict=True)
Traceback (most recent call last):
  ...
x690.exc.IncompleteDecoding: Strict decoding still had 10 remaining bytes!