Module: symmetric_key_ratchet

class doubleratchet.symmetric_key_ratchet.Chain(*values)[source]

Bases: Enum

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

SENDING = 'SENDING'

RECEIVING = '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 (JSONObject) – 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: int | None: Returns: The length of the previous sending chain, if it exists.

property sending_chain_length: int | None: Returns: The length of the sending chain, if it exists.

property receiving_chain_length: int | None: 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.