Skip to content

Commit

Permalink
Small update to the getting started docs to mention the new example a…
Browse files Browse the repository at this point in the history
…nd remove confusing mentions of abstract backend classes
  • Loading branch information
Syndace committed Nov 11, 2022
1 parent 3733029 commit ea5376b
Showing 1 changed file with 13 additions and 16 deletions.
29 changes: 13 additions & 16 deletions docs/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -35,32 +35,29 @@ The library works with two types of trust levels: custom trust levels and core t

This trust concept allows for the implementation of trust systems like `BTBV <https://gultsch.de/trust.html>`_, `TOFU <https://en.wikipedia.org/wiki/Trust_on_first_use>`_, simple manual trust or more complex systems.

Storage
-------

python-omemo uses a simple key-value storage to persist its state. This storage has to be provided to the library by implementing the :class:`~omemo.storage.Storage` interface. Refer to the API documentation of the :class:`~omemo.storage.Storage` interface for details.

.. WARNING::
It might be tempting to offer a backup/restore flow for the OMEMO data. However, due to the forward secrecy of OMEMO, restoring old data results in broken sessions. It is strongly recommended to not include OMEMO data in backups, and to at most include it in migration flows that make sure that old data can't be restored over newer data.
An example of a BTBV trust system implementation can be found in ``examples/btbv_session_manager.py``. If you happen to aim for BTBV support in your client, feel free to use that code as a starting point.

Setting it Up
-------------

With the backends selected, the trust system chosen and the storage implementation prepared, the library can be set up.
With the backends selected and the trust system chosen, the library can be set up.

This is done in three steps:

1. Subclass abstract backend classes
2. Subclass abstract core library classes
3. Instantiate the :class:`~omemo.session_manager.SessionManager`
1. Create a :class:`~omemo.storage.Storage` implementation
2. Create a :class:`~omemo.session_manager.SessionManager` implementation
3. Instantiate your :class:`~omemo.session_manager.SessionManager` implementation

Backend Subclassing
^^^^^^^^^^^^^^^^^^^
:class:`~omemo.storage.Storage` Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create subclasses of the respective backend classes if necessary. Some backends may require you to implement abstract methods, others may not. Refer to the docs of the respective backends for setup instructions.
python-omemo uses a simple key-value storage to persist its state. This storage has to be provided to the library by implementing the :class:`~omemo.storage.Storage` interface. Refer to the API documentation of the :class:`~omemo.storage.Storage` interface for details.

.. WARNING::
It might be tempting to offer a backup/restore flow for the OMEMO data. However, due to the forward secrecy of OMEMO, restoring old data results in broken sessions. It is strongly recommended to not include OMEMO data in backups, and to at most include it in migration flows that make sure that old data can't be restored over newer data.

Core Library Subclassing
^^^^^^^^^^^^^^^^^^^^^^^^
:class:`~omemo.session_manager.SessionManager` Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a subclass of :class:`~omemo.session_manager.SessionManager`. There are various abstract methods for interaction with XMPP (device lists, bundles etc.) and trust management that you have to fill out to integrate the library with your client/framework. The API documentation of the :class:`~omemo.session_manager.SessionManager` class should contain the necessary information.

Expand Down

0 comments on commit ea5376b

Please sign in to comment.