Getting Started

This quick start guide assumes basic knowledge of the X3DH key agreement protocol.

The abstract class x3dh.state.State builds the core of this library. To use it, create a subclass and override the _publish_bundle() and _encode_public_key() methods. You can now create instances using the create() method and perform key agreements using get_shared_secret_active() and 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 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 x3dh.base_state.BaseState class instead.

In the X3DH specification, the identity key is a Curve25519/Curve448 key and 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 IdentityKeyPairPriv via the identity_key_pair constructor parameter.