Module: diffie_hellman_ratchet

class doubleratchet.diffie_hellman_ratchet.DiffieHellmanRatchet

Bases: ABC

As communication partners exchange messages they also exchange new Diffie-Hellman public keys, and the Diffie-Hellman output secrets become the inputs to the root chain. The output keys from the root chain become new KDF keys for the sending and receiving chains. This is called the Diffie-Hellman ratchet.

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

Note

The specification introduces the symmetric-key ratchet and the Diffie-Hellman ratchet as independent units and links them together in the Double Ratchet. This implementation does not follow that separation, instead the Diffie-Hellman ratchet manages the symmetric-key ratchet internally, which makes the code a little less complicated, as the Double Ratchet doesn’t have to forward keys generated by the Diffie-Hellman ratchet to the symmetric-key ratchet.

async classmethod create(own_ratchet_priv, other_ratchet_pub, root_chain_kdf, root_chain_key, message_chain_kdf, message_chain_constant, dos_protection_threshold)

Create and configure a Diffie-Hellman ratchet.

Parameters:

• own_ratchet_priv (bytes | None) – The ratchet private key to use initially with this instance.

• other_ratchet_pub (bytes) – The ratchet public key of the other party.

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

• root_chain_key (bytes) – The key to initialize the root chain with, consisting of 32 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.

Return type:

TypeVar(DiffieHellmanRatchetTypeT, bound= DiffieHellmanRatchet)

Returns:

A configured instance of DiffieHellmanRatchet, capable of sending and receiving messages.

property sending_chain_length: int

Returns: The length of the sending chain of the internal symmetric-key ratchet.

property receiving_chain_length: int | None

Returns: The length of the receiving chain of the internal symmetric-key ratchet, if it exists.

abstractmethod static _generate_priv()

Return type:

bytes

Returns:

A freshly generated private key, capable of performing Diffie-Hellman key exchanges with the public key of another party.

Note

This function is recommended to generate a key pair based on the Curve25519 or Curve448 elliptic curves (https://signal.org/docs/specifications/doubleratchet/#recommended-cryptographic-algorithms).

abstractmethod static _derive_pub(priv)

Derive the public key from a private key as generated by _generate_priv().

Parameters:

priv (bytes) – The private key as returned by _generate_priv().

Return type:

bytes

Returns:

The public key corresponding to the private key.

abstractmethod static _perform_diffie_hellman(own_priv, other_pub)

Parameters:

• own_priv (bytes) – The own ratchet private key.

• other_pub (bytes) – The ratchet public key of the other party.

Return type:

bytes

Returns:

A shared secret agreed on via Diffie-Hellman. This method is recommended to perform X25519 or X448. There is no need to check for invalid public keys (https://signal.org/docs/specifications/doubleratchet/#recommended-cryptographic-algorithms).

property model: DiffieHellmanRatchetModel

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

property json: JSONObject

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

classmethod from_model(model, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold)

Parameters:

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

• 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.

Return type:

TypeVar(DiffieHellmanRatchetTypeT, bound= DiffieHellmanRatchet)

Returns:

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

Raises:

InconsistentSerializationException – if the serialized data is structurally correct, but incomplete. This can only happen when migrating a DoubleRatchet 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 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, root_chain_kdf, message_chain_kdf, message_chain_constant, dos_protection_threshold)

Parameters:

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

• 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.

Return type:

TypeVar(DiffieHellmanRatchetTypeT, bound= DiffieHellmanRatchet)

Returns:

A configured instance of DiffieHellmanRatchet, 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 a DoubleRatchet 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 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.

async next_encryption_key()

Return type:

Tuple[bytes, Header]

Returns:

The next (32 bytes) encryption key derived from the sending chain and the corresponding Diffie-Hellman ratchet header.

async next_decryption_key(header)

Parameters:

header (Header) – The Diffie-Hellman ratchet header,

Return type:

Tuple[bytes, SkippedMessageKeys]

Returns:

The next (32 bytes) decryption key derived from the receiving chain and message keys that were skipped while deriving the new decryption key.

Raises:

• DoSProtectionException – if a huge number of message keys were skipped that have to be calculated first before decrypting the next message.

• DuplicateMessageException – if this message appears to be a duplicate.

exception doubleratchet.diffie_hellman_ratchet.DoSProtectionException

Bases: Exception

Raised by DiffieHellmanRatchet.next_decryption_key() in case the number of skipped message keys to calculate crosses the DoS protection threshold.

exception doubleratchet.diffie_hellman_ratchet.DuplicateMessageException

Bases: Exception

Raised by DiffieHellmanRatchet.next_decryption_key() in case is seems the message was processed before.