Module: state

class x3dh.state.State[source]

Bases: BaseState

This class is the core of this X3DH implementation. It manages the own Bundle and offers methods to perform key agreements with other parties. Use BaseState directly if manual state management is needed. Note that you can still use the methods available for manual state management, but doing so shouldn’t be required.

Warning

rotate_signed_pre_key() should be called periodically to check whether the signed pre key needs to be rotated and to perform the rotation if necessary.

classmethod create(identity_key_format, hash_function, info, identity_key_pair=None, signed_pre_key_rotation_period=604800, pre_key_refill_threshold=99, pre_key_refill_target=100)[source]
Parameters:

  • identity_key_format (IdentityKeyFormat) – The format in which the identity public key is included in bundles/headers.

  • hash_function (HashFunction) – A 256 or 512-bit hash function.

  • info (bytes) – A (byte) string identifying the application.

  • signed_pre_key_rotation_period (int) – Rotate the signed pre key after this amount of time in seconds.

  • pre_key_refill_threshold (int) – Threshold for refilling the pre keys.

  • pre_key_refill_target (int) – When less then pre_key_refill_threshold pre keys are available, generate new ones until there are pre_key_refill_target pre keys again.

  • identity_key_pair (IdentityKeyPair | None) – If set, use the given identity key pair instead of generating a new one.

Return type:

TypeVar(StateTypeT, bound= State)

Returns:

A configured instance of State.

abstractmethod _publish_bundle(bundle)[source]
Parameters:

bundle (Bundle) – The bundle to publish, overwriting previously published data.

Return type:

None

Note

In addition to publishing the bundle, this method can be used as a trigger to persist the state. Persisting the state in this method guarantees always remaining up-to-date.

Note

This method is called from create(), before create() has returned the instance. Thus, modifications to the object (self, in case of subclasses) may not have happened when this method is called.

Note

Even though this method is expected to perform I/O, it is deliberately not marked as async, since completion of the I/O operation is not a requirement for the program flow to continue, and making this method async would complicate API design with regards to inheritance from BaseState.

classmethod from_model(model, identity_key_format, hash_function, info, signed_pre_key_rotation_period=604800, pre_key_refill_threshold=99, pre_key_refill_target=100)[source]
Parameters:

  • model (BaseStateModel) – The pydantic model holding the internal state of a State, as produced by model.

  • identity_key_format (IdentityKeyFormat) – The format in which the identity public key is included in bundles/headers.

  • hash_function (HashFunction) – A 256 or 512-bit hash function.

  • info (bytes) – A (byte) string identifying the application.

  • signed_pre_key_rotation_period (int) – Rotate the signed pre key after this amount of time in seconds.

  • pre_key_refill_threshold (int) – Threshold for refilling the pre keys.

  • pre_key_refill_target (int) – When less then pre_key_refill_threshold pre keys are available, generate new ones until there are pre_key_refill_target pre keys again.

Return type:

TypeVar(StateTypeT, bound= State)

Returns:

A configured instance of State, with internal state restored from the model.

Warning

Migrations are not provided via the model/from_model() API. Use json/from_json() instead. Refer to Serialization and Migration in the documentation for details.

classmethod from_json(serialized, identity_key_format, hash_function, info, signed_pre_key_rotation_period=604800, pre_key_refill_threshold=99, pre_key_refill_target=100)[source]
Parameters:

  • serialized (JSONObject) – A JSON-serializable Python object holding the internal state of a State, as produced by json.

  • identity_key_format (IdentityKeyFormat) – The format in which the identity public key is included in bundles/headers.

  • hash_function (HashFunction) – A 256 or 512-bit hash function.

  • info (bytes) – A (byte) string identifying the application.

  • signed_pre_key_rotation_period (int) – Rotate the signed pre key after this amount of time in seconds.

  • pre_key_refill_threshold (int) – Threshold for refilling the pre keys.

  • pre_key_refill_target (int) – When less then pre_key_refill_threshold pre keys are available, generate new ones until there are pre_key_refill_target pre keys again.

Return type:

Tuple[TypeVar(StateTypeT, bound= State), bool]

Returns:

A configured instance of State, with internal state restored from the serialized data, and a flag that indicates whether the bundle needed to be published. The latter was part of the pre-stable serialization format and is handled automatically by this from_json() implementation.

rotate_signed_pre_key(force=False)[source]

Check whether the signed pre key is due for rotation, and rotate it if necessary. Call this method periodically to make sure the signed pre key is always up to date.

Parameters:

force (bool) – Whether to force rotation regardless of the age of the current signed pre key.

Return type:

None

async get_shared_secret_passive(header, associated_data_appendix=b'', require_pre_key=True)[source]

Perform an X3DH key agreement, passively.

Parameters:

  • header (Header) – The header received from the active party.

  • associated_data_appendix (bytes) – Additional information to append to the associated data, like usernames, certificates or other identifying information.

  • require_pre_key (bool) – Use this flag to abort the key agreement if the active party did not use a pre key.

Return type:

Tuple[bytes, bytes, SignedPreKeyPair]

Returns:

The shared secret and the associated data shared between both parties, and the signed pre key pair that was used during the key exchange, for use by follow-up protocols.

Raises:

KeyAgreementException – If an error occurs during the key agreement. The exception message will contain (human-readable) details.