p2panda_encryption/message_scheme/
mod.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Message Encryption for groups offering a forward secure (FS) messaging ratchet, similar to
4//! Signal's [Double Ratchet algorithm](https://en.wikipedia.org/wiki/Double_Ratchet_Algorithm).
5//!
6//! Since secret keys are always generated for each message, a user can not easily learn about
7//! previously-created messages when getting hold of such a key. We believe that the latter scheme
8//! will be used in more specialised applications, for example p2p group chats, as strong forward
9//! secrecy comes with it's own UX requirements. We are nonetheless excited to offer a solution for
10//! both worlds, depending on the application's needs.
11//!
12//! ## Messages
13//!
14//! Every group operation ([create](MessageGroup::create) or [update](MessageGroup::update)
15//! group, [add](MessageGroup::add) or [remove](MessageGroup::remove) member) results in a
16//! [`ControlMessage`] which is broadcast to the network for each group member and a set of direct
17//! messages.
18//!
19//! A [`DirectMessage`] is sent to a specific group member and contains the group secrets encrypted
20//! towards them for key agreement.
21//!
22//! Application messages contain the ciphertexts and parameters required to decrypt it using a
23//! message ratchet.
24//!
25//! ## Message Ratchets
26//!
27//! The "inner" message ratchet derives a ChaCha20Poly1305 AEAD secret and nonce for message
28//! encryption for each "generation". Each peer maintains their own [`RatchetSecret`] for sending
29//! messages and keeps around one [`DecryptionRatchet`] per other member in the group to decrypt
30//! received messages from them.
31//!
32//! Messages arriving out of order or getting lost are tolerated within the [configured
33//! limits](group::GroupConfig).
34//!
35//! ## Key Agreement
36//!
37//! Extra care is required to keep the chain secrets, updating the "outer" ratchets in a strict, linearized
38//! order. Consult the [DCGKA](dcgka) module for more information.
39//!
40//! ## Key bundles
41//!
42//! For initial key agreement (X3DH) peers need to publish key bundles into the network to allow
43//! others to invite them into groups. For the "Message Encryption" scheme we're using one-time
44//! pre-keys which bring additional requirements due to their "only use once" limitation.
45//!
46//! More on key bundles can be read [here](crate::key_bundle).
47//!
48//! ## Usage
49//!
50//! Check out the [`MessageGroup`] API for establishing and maintaining groups using the "Message
51//! Encryption" scheme.
52//!
53//! Developers need to bring their own data types with [group message
54//! interfaces](crate::traits::ForwardSecureGroupMessage), [decentralised group
55//! membership](crate::traits::AckedGroupMembership) (DGM) and
56//! [ordering](crate::traits::ForwardSecureOrdering) implementations when using this crate
57//! directly, for easier use without this overhead it's recommended to look into higher-level
58//! integrations using the p2panda stack.
59pub mod dcgka;
60pub mod group;
61mod message;
62pub mod ratchet;
63#[cfg(any(test, feature = "test_utils"))]
64pub mod test_utils;
65#[cfg(test)]
66mod tests;
67
68pub use dcgka::{ControlMessage, DirectMessage, DirectMessageContent, DirectMessageType};
69pub use group::{GroupError, GroupEvent, GroupOutput, GroupState, MessageGroup};
70pub use message::{decrypt_message, encrypt_message};
71pub use ratchet::{
72    DecryptionRatchet, DecryptionRatchetState, Generation, MESSAGE_KEY_SIZE, RatchetError,
73    RatchetSecret, RatchetSecretState,
74};
p2panda_encryption/message_scheme/mod.rs

p2panda_encryption/message_scheme/
mod.rs
