Module key_bundle 

Key bundles to asynchronously receive encrypted data from others.

This is for asynchronous settings where one user (“Bob”) is offline but has published a key bundle (containing their identity key, pre-keys, etc.) beforehands. Another user (“Alice”) wants to use that information to send encrypted data to Bob.

Depending on the security of the chat group this key bundle should be used only once with OneTimeKeyBundle or only within a given “lifetime” (one day, two weeks, etc.) with LongTermKeyBundle. Members need to make sure that there are always fresh key bundles from them available in the network for others.

Forward secrecy

Some applications might have very strong forward secrecy requirements and only allow “one-time” pre-keys per group. This means that we can only establish a Forward Secure (FS) communication channel with a peer if we reliably made sure to only use the pre-key exactly once. This is hard to guarantee in a decentralised setting. If we don’t care about very strong FS we can ease up on that requirement a little bit and tolerate re-use with longer-living pre-keys which get rotated frequently (every week for example).

Public-key infrastructure (PKI)

We assume that encrypted groups with strong FS guarantees using one-time key bundles only get established when peers have explicitly exchanged their one-time pre-keys with each other, for example in form of scanning QR codes.

Another solution for very strong forward secrecy, where we can make sure the pre-key is only used once, is a “bilateral session state establishment” process where peers can only establish a group chat with each other after both parties have been online. They don’t need to be online at the same time, just to be online at least once and receive the messages of the other party. This puts a slight restriction on the “offline-first” nature for peer-to-peer applications.

Another solution is to rely on always-online and trusted key servers which maintain the pre-keys for the network, but this puts an unnecessary centralisation point into the system and seems even worse.

For longer-living (“long-term”) pre-key bundles we can lift the strict “use once” requirement and peers can regularly publish fresh key bundles on the network, other peers need to make sure they keep collecting the latest bundles regularly.

Authenticated Messaging

Note that while pre-keys are signed, bundles should be part of an authenticated messaging scheme where the whole payload (and thus it’s lifetime and maybe one-time pre-key) is signed by the same identity to prevent replay- and impersonation attacks.

Otherwise attackers might be able to re-play the same pre-key with different lifetimes.

Structs

Lifetime

Determines the lifetime of a pre-key by defining a time range.

LongTermKeyBundle

Key-bundle with public keys to be used until the pre-key expired.

OneTimeKeyBundle

Key-bundle with public keys to be used exactly once.

OneTimePreKey

Pre-key with key material for X3DH key agreement to be used exactly once.

PreKey

Pre-key with key material for X3DH key agreement to be used until it’s lifetime has expired.

Enums

KeyBundleError

LifetimeError

Functions

latest_key_bundle

Helper method to identify the “latest” (valid and with furthest expiry date) key bundle from a set. Returns None if no valid bundle was given.

latest_prekey

Helper method to identify the “latest” (valid and with furthest expiry date) pre-key from a set. Returns None if no valid key was given.

Type Aliases

OneTimePreKeyId

Unique identifier of a member’s one-time pre-key.

PreKeyId

Unique identifier of a member’s pre-key which can be used to address long-term key bundles.