Module: double_ratchet

class doubleratchet.double_ratchet.DoubleRatchet[source]

Bases: ABC

Combining the symmetric-key ratchet and the Diffie-Hellman ratchet gives the Double Ratchet.

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

Note

In this implementation, the Diffie-Hellman ratchet already manages the symmetric-key ratchet internally, see DiffieHellmanRatchet for details. The Double Ratchet class adds message en-/decryption and offers a more convenient public API that handles lost and out-of-order messages.

async classmethod encrypt_initial_message(diffie_hellman_ratchet_class, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold, max_num_skipped_message_keys, aead, shared_secret, recipient_ratchet_pub, message, associated_data)[source]
Parameters

  • diffie_hellman_ratchet_class (Type[DiffieHellmanRatchet]) – A non-abstract subclass of DiffieHellmanRatchet.

  • root_chain_kdf (Type[KDF]) – The KDF to use for the root chain. The KDF must be capable of deriving 64 bytes.

  • message_chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.

  • message_chain_constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

  • dos_protection_threshold (int) – The maximum number of skipped message keys to calculate. If more than that number of message keys are skipped, the keys are not calculated to prevent being DoSed.

  • max_num_skipped_message_keys (int) – The maximum number of skipped message keys to store in case the lost or out-of-order message comes in later. Older keys are discarded to make space for newer keys.

  • aead (Type[AEAD]) – The AEAD implementation to use for message en- and decryption.

  • shared_secret (bytes) – A shared secret consisting of 32 bytes that was agreed on by means external to this protocol.

  • recipient_ratchet_pub (bytes) – The ratchet public key of the recipient.

  • message (bytes) – The initial message.

  • associated_data (bytes) – Additional data to authenticate without including it in the ciphertext.

Return type

Tuple[TypeVar(DoubleRatchetTypeT, bound= DoubleRatchet), EncryptedMessage]

Returns

A configured instance of DoubleRatchet ready to send and receive messages together with the initial message.

async classmethod decrypt_initial_message(diffie_hellman_ratchet_class, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold, max_num_skipped_message_keys, aead, shared_secret, own_ratchet_priv, message, associated_data)[source]
Parameters

  • diffie_hellman_ratchet_class (Type[DiffieHellmanRatchet]) – A non-abstract subclass of DiffieHellmanRatchet.

  • root_chain_kdf (Type[KDF]) – The KDF to use for the root chain. The KDF must be capable of deriving 64 bytes.

  • message_chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.

  • message_chain_constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

  • dos_protection_threshold (int) – The maximum number of skipped message keys to calculate. If more than that number of message keys are skipped, the keys are not calculated to prevent being DoSed.

  • max_num_skipped_message_keys (int) – The maximum number of skipped message keys to store in case the lost or out-of-order message comes in later. Older keys are discarded to make space for newer keys.

  • aead (Type[AEAD]) – The AEAD implementation to use for message en- and decryption.

  • shared_secret (bytes) – A shared secret that was agreed on by means external to this protocol.

  • own_ratchet_priv (bytes) – The ratchet private key to use initially.

  • message (EncryptedMessage) – The encrypted initial message.

  • associated_data (bytes) – Additional data to authenticate without including it in the ciphertext.

Return type

Tuple[TypeVar(DoubleRatchetTypeT, bound= DoubleRatchet), bytes]

Returns

A configured instance of DoubleRatchet ready to send and receive messages together with the decrypted initial message.

Raises
property sending_chain_length: int

Returns: The length of the sending chain of the internal symmetric-key ratchet, as exposed by the internal Diffie-Hellman ratchet.

property receiving_chain_length: Optional[int]

Returns: The length of the receiving chain of the internal symmetric-key ratchet, if it exists, as exposed by the internal Diffie-Hellman ratchet.

abstract static _build_associated_data(associated_data, header)[source]
Parameters

  • associated_data (bytes) – The associated data to prepend to the output. If the associated data is not guaranteed to be a parseable byte sequence, a length value should be prepended to ensure that the output is parseable as a unique pair (associated data, header).

  • header (Header) – The message header to encode in a unique, reversible manner.

Return type

bytes

Returns

A byte sequence encoding the associated data and the header in a unique, reversible way.

property model: DoubleRatchetModel

Returns: The internal state of this DoubleRatchet as a pydantic model.

property json: JSONObject

Returns: The internal state of this DoubleRatchet as a JSON-serializable Python object.

classmethod from_model(model, diffie_hellman_ratchet_class, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold, max_num_skipped_message_keys, aead)[source]
Parameters

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

  • diffie_hellman_ratchet_class (Type[DiffieHellmanRatchet]) – A non-abstract subclass of DiffieHellmanRatchet.

  • root_chain_kdf (Type[KDF]) – The KDF to use for the root chain. The KDF must be capable of deriving 64 bytes.

  • message_chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.

  • message_chain_constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

  • dos_protection_threshold (int) – The maximum number of skipped message keys to calculate. If more than that number of message keys are skipped, the keys are not calculated to prevent being DoSed.

  • max_num_skipped_message_keys (int) – The maximum number of skipped message keys to store in case the lost or out-of-order message comes in later. Older keys are discarded to make space for newer keys.

  • aead (Type[AEAD]) – The AEAD implementation to use for message en- and decryption.

Return type

TypeVar(DoubleRatchetTypeT, bound= DoubleRatchet)

Returns

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

Raises

InconsistentSerializationException – if the serialized data is structurally correct, but incomplete. This can only happen when migrating an instance from pre-stable data that was serialized before sending or receiving a single message. In this case, the serialized instance is basically uninitialized and can be discarded/replaced with a new instance using encrypt_initial_message() or decrypt_initial_message() without losing information.

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, diffie_hellman_ratchet_class, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold, max_num_skipped_message_keys, aead)[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 DoubleRatchet, as produced by json.

  • diffie_hellman_ratchet_class (Type[DiffieHellmanRatchet]) – A non-abstract subclass of DiffieHellmanRatchet.

  • root_chain_kdf (Type[KDF]) – The KDF to use for the root chain. The KDF must be capable of deriving 64 bytes.

  • message_chain_kdf (Type[KDF]) – The KDF to use for the sending and receiving chains. The KDF must be capable of deriving 64 bytes.

  • message_chain_constant (bytes) – The constant to feed into the sending and receiving KDF chains on each step.

  • dos_protection_threshold (int) – The maximum number of skipped message keys to calculate. If more than that number of message keys are skipped, the keys are not calculated to prevent being DoSed.

  • max_num_skipped_message_keys (int) – The maximum number of skipped message keys to store in case the lost or out-of-order message comes in later. Older keys are discarded to make space for newer keys.

  • aead (Type[AEAD]) – The AEAD implementation to use for message en- and decryption.

Return type

TypeVar(DoubleRatchetTypeT, bound= DoubleRatchet)

Returns

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

Raises

InconsistentSerializationException – if the serialized data is structurally correct, but incomplete. This can only happen when migrating an instance from pre-stable data that was serialized before sending or receiving a single message. In this case, the serialized instance is basically uninitialized and can be discarded/replaced with a new instance using encrypt_initial_message() or decrypt_initial_message() without losing information.

async encrypt_message(message, associated_data)[source]
Parameters

  • message (bytes) – The message to encrypt.

  • associated_data (bytes) – Additional data to authenticate without including it in the ciphertext.

Return type

EncryptedMessage

Returns

The encrypted message including the header to send to the recipient.

async decrypt_message(message, associated_data)[source]
Parameters

  • message (EncryptedMessage) – The encrypted message.

  • associated_data (bytes) – Additional data to authenticate without including it in the ciphertext.

Return type

bytes

Returns

The message plaintext, after decrypting and authenticating the ciphertext.

Raises