1
2
3
4
5
6
7
8
9
10
|
Getting Started
===============
This quick start guide assumes basic knowledge of the `X3DH key agreement protocol <https://www.signal.org/docs/specifications/x3dh/>`__.
The abstract class :class:`x3dh.state.State` builds the core of this library. To use it, create a subclass and override the :meth:`~x3dh.state.State._publish_bundle` and :meth:`~x3dh.base_state.BaseState._encode_public_key` methods. You can now create instances using the :meth:`~x3dh.state.State.create` method and perform key agreements using :meth:`~x3dh.base_state.BaseState.get_shared_secret_active` and :meth:`~x3dh.state.State.get_shared_secret_passive`. This method requires a set of configuration parameters, most of them directly correspond to those parameters defined in the X3DH specification. One parameter provides configuration that goes beyond the specification: ``identity_key_format``. The :class:`x3dh.state.State` class performs various maintenance/key management tasks automatically, like pre key refilling and signed pre key rotation. Note that the age check of the signed pre key has to be triggered periodically by the program. If manual key management is required, use the :class:`x3dh.base_state.BaseState` class instead.
.. _ik-types:
In the X3DH specification, the identity key is a Curve25519/Curve448 key and `XEdDSA <https://www.signal.org/docs/specifications/xeddsa/>`__ is used to create signatures with it. This library does not support Curve448, however, it supports Ed25519 in addition to Curve25519. You can choose whether the public part of the identity key in the bundle is transferred as Curve25519 or Ed25519 using the mentioned constructor parameter ``identity_key_format``. When generating a new identity key, the library will by default generate a seed-based identity key, which is usable for both Ed25519 and X25519 without the help of XEdDSA. A scalar-based private key, which requires the use of XEdDSA to create and verify signatures, can be used by explicitly passing an instance of :class:`~x3dh.identity_key_pair.IdentityKeyPairPriv` via the ``identity_key_pair`` constructor parameter.
|
