Module: diffie_hellman_ratchet¶
- class doubleratchet.diffie_hellman_ratchet.DiffieHellmanRatchet[source]¶
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)[source]¶
Create and configure a Diffie-Hellman ratchet.
- Parameters
own_ratchet_priv (
Optional
[bytes
]) – 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: Optional[int]¶
Returns: The length of the receiving chain of the internal symmetric-key ratchet, if it exists.
- abstract static _generate_priv()[source]¶
- 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).
- abstract static _derive_pub(priv)[source]¶
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.
- abstract static _perform_diffie_hellman(own_priv, other_pub)[source]¶
- 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)[source]¶
- Parameters
model (
DiffieHellmanRatchetModel
) – The pydantic model holding the internal state of aDiffieHellmanRatchet
, as produced bymodel
.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. Usejson
/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)[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 aDiffieHellmanRatchet
, as produced byjson
.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. Usejson
/from_json()
instead. Refer to Serialization and Migration in the documentation for details.
- async next_encryption_key()[source]¶
- 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)[source]¶
- Parameters
header (
Header
) – The Diffie-Hellman ratchet header,- Return type
Tuple
[bytes
,OrderedDict
[Tuple
[bytes
,int
],bytes
]]- 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[source]¶
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[source]¶
Bases:
Exception
Raised by
DiffieHellmanRatchet.next_decryption_key()
in case is seems the message was processed before.