Metadata-Version: 2.1
Name: x690
Version: 0.4.0
Summary: Pure Python X.690 implementation
Home-page: https://exhuma.github.io/x690/
License: MIT
Author: Michel Albert
Author-email: michel@albert.lu
Requires-Python: >=3.6,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Requires-Dist: dataclasses (>=0.7,<0.8); python_version < "3.7"
Requires-Dist: importlib-metadata (>=3.3.0,<4.0.0); python_version < "3.8"
Requires-Dist: t61codec (>=1.0.1,<2.0.0)
Project-URL: Documentation, https://exhuma.github.io/x690/
Project-URL: Repository, https://github.com/exhuma/x690
Description-Content-Type: text/x-rst

Pure Python `X.690`_ implementation
===================================

.. image:: https://github.com/exhuma/x690/workflows/Build%20&%20Publish%20Docs/badge.svg?branch=main
    :alt: Build & Publish Docs

.. _X.690: https://www.itu.int/rec/recommendation.asp?lang=en&parent=T-REC-X.690-201508-I


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
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    >>> 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    >>> 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.

.. code:: python

    >>> 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.

.. code:: python

    >>> 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.

.. code:: python

    >>> 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!

