Module: symmetric_key_ratchet¶

class doubleratchet.symmetric_key_ratchet.Chain(value)[source]¶

Bases: Enum

Enumeration identifying the chain to replace by SymmetricKeyRatchet.replace_chain().

SENDING: str = 'SENDING'¶

RECEIVING: str = 'RECEIVING'¶

exception doubleratchet.symmetric_key_ratchet.ChainNotAvailableException[source]¶

Bases: Exception

Raised by SymmetricKeyRatchet.next_encryption_key() and SymmetricKeyRatchet.next_decryption_key() in case the required chain has not been initialized yet.

class doubleratchet.symmetric_key_ratchet.SymmetricKeyRatchet[source]¶

Bases: object

The sending and receiving chains advance as each message is sent and received. Their output keys are used to encrypt and decrypt messages. This is called the symmetric-key ratchet.

https://signal.org/docs/specifications/doubleratchet/#symmetric-key-ratchet

classmethod create(chain_kdf, constant)[source]¶

Parameters

chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.
constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

Return type

TypeVar(SymmetricKeyRatchetTypeT, bound= SymmetricKeyRatchet)

Returns

A configured instance of SymmetricKeyRatchet.

property model: SymmetricKeyRatchetModel¶: Returns: The internal state of this SymmetricKeyRatchet as a pydantic model.

property json: JSONObject¶: Returns: The internal state of this SymmetricKeyRatchet as a JSON-serializable Python object.

classmethod from_model(model, chain_kdf, constant)[source]¶

Parameters

model (SymmetricKeyRatchetModel) – The pydantic model holding the internal state of a SymmetricKeyRatchet, as produced by model.
chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.
constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

Return type

TypeVar(SymmetricKeyRatchetTypeT, bound= SymmetricKeyRatchet)

Returns

A configured instance of SymmetricKeyRatchet, 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, chain_kdf, constant)[source]¶

Parameters

serialized (Mapping[str, Union[None, float, int, str, bool, List[Union[None, float, int, str, bool, List[Union[None, float, int, str, bool]], Mapping[str, Union[None, float, int, str, bool]]]], Mapping[str, Union[None, float, int, str, bool, List[Union[None, float, int, str, bool]], Mapping[str, Union[None, float, int, str, bool]]]]]]) – A JSON-serializable Python object holding the internal state of a SymmetricKeyRatchet, as produced by json.
chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.
constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

Return type

TypeVar(SymmetricKeyRatchetTypeT, bound= SymmetricKeyRatchet)

Returns

A configured instance of SymmetricKeyRatchet, with internal state restored from the serialized data.

replace_chain(chain, key)[source]¶

Replace either the sending or the receiving chain with a new KDF chain.

Parameters

chain (Chain) – The chain to replace.
key (bytes) – The initial chain key for the new KDF chain.

Return type

None

property previous_sending_chain_length: Optional[int]¶: Returns: The length of the previous sending chain, if it exists.

property sending_chain_length: Optional[int]¶: Returns: The length of the sending chain, if it exists.

property receiving_chain_length: Optional[int]¶: Returns: The length of the receiving chain, if it exists.

async next_encryption_key()[source]¶

Return type: bytes
Returns: The next (32 bytes) encryption key derived from the sending chain.
Raises: ChainNotAvailableException – if the sending chain was never initialized.

async next_decryption_key()[source]¶

Return type: bytes
Returns: The next (32 bytes) decryption key derived from the receiving chain.
Raises: ChainNotAvailableException – if the receiving chain was never initialized.