Module: base_state

exception x3dh.base_state.KeyAgreementException

Bases: Exception

Exception raised by BaseState.get_shared_secret_active() and BaseState.get_shared_secret_passive() in case of an error related to the key agreement operation.

class x3dh.base_state.BaseState

Bases: ABC

This class is the core of this X3DH implementation. It offers methods to manually manage the X3DH state and perform key agreements with other parties.

Warning

This class requires manual state management, including e.g. signed pre key rotation, pre key hiding/deletion and refills. The subclass State automates those management/maintenance tasks and should be preferred if external/manual management is not explicitly wanted.

classmethod create(identity_key_format, hash_function, info, identity_key_pair=None)

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.

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

Return type:

TypeVar(BaseStateTypeT, bound= BaseState)

Returns:

A configured instance of BaseState. Note that an identity key pair and a signed pre key are generated, but no pre keys. Use generate_pre_keys() to generate some.

abstractmethod static _encode_public_key(key_format, pub)

Parameters:

• key_format (IdentityKeyFormat) – The format in which this public key is serialized.

• pub (bytes) – The public key.

Return type:

bytes

Returns:

An encoding of the public key, possibly including information about the curve and type of key, though this is application defined. Note that two different public keys must never result in the same byte sequence, uniqueness of the public keys must be preserved.

property model: BaseStateModel

Returns: The internal state of this BaseState as a pydantic model. Note that pre keys hidden using hide_pre_key() are not considered part of the state.

property json: JSONObject

Returns: The internal state of this BaseState as a JSON-serializable Python object. Note that pre keys hidden using hide_pre_key() are not considered part of the state.

classmethod from_model(model, identity_key_format, hash_function, info)

Parameters:

• model (BaseStateModel) – The pydantic model holding the internal state of a BaseState, 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.

Return type:

TypeVar(BaseStateTypeT, bound= BaseState)

Returns:

A configured instance of BaseState, 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)

Parameters:

• serialized (JSONObject) – A JSON-serializable Python object holding the internal state of a BaseState, 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.

Return type:

Tuple[TypeVar(BaseStateTypeT, bound= BaseState), bool]

Returns:

A configured instance of BaseState, with internal state restored from the serialized data, and a flag that indicates whether the bundle needs to be published. The latter was part of the pre-stable serialization format.

property old_signed_pre_key: bytes | None

Returns: The old signed pre key, if there is one.

signed_pre_key_age()

Return type:

int

Returns:

The age of the signed pre key, i.e. the time elapsed since it was last rotated, in seconds.

rotate_signed_pre_key()

Rotate the signed pre key. Keep the old signed pre key around for one additional rotation period, i.e. until this method is called again.

Return type:

None

property hidden_pre_keys: FrozenSet[bytes]

Returns: The currently hidden pre keys.

hide_pre_key(pre_key_pub)

Hide a pre key from the bundle returned by bundle and pre key count returned by get_num_visible_pre_keys(), but keep the pre key for cryptographic operations. Hidden pre keys are not included in the serialized state as returned by model and json.

Parameters:

pre_key_pub (bytes) – The pre key to hide.

Return type:

bool

Returns:

Whether the pre key was visible before and is hidden now.

delete_pre_key(pre_key_pub)

Delete a pre key.

Parameters:

pre_key_pub (bytes) – The pre key to delete. Can be visible or hidden.

Return type:

bool

Returns:

Whether the pre key existed before and is deleted now.

delete_hidden_pre_keys()

Delete all pre keys that were previously hidden using hide_pre_key().

Return type:

None

get_num_visible_pre_keys()

Return type:

int

Returns:

The number of visible pre keys available. The number returned here matches the number of pre keys included in the bundle returned by bundle.

generate_pre_keys(num_pre_keys)

Generate and store pre keys.

Parameters:

num_pre_keys (int) – The number of pre keys to generate.

Return type:

None

property bundle: Bundle

Returns: The bundle, i.e. the public information of this state.

async get_shared_secret_active(bundle, associated_data_appendix=b'', require_pre_key=True)

Perform an X3DH key agreement, actively.

Parameters:

• bundle (Bundle) – The bundle of the passive 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 bundle does not contain a pre key.

Return type:

Tuple[bytes, bytes, Header]

Returns:

The shared secret and associated data shared between both parties, and the header required by the other party to complete the passive part of the key agreement.

Raises:

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

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

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.