Expand description
Data encryption for groups with post-compromise security and optional forward secrecy.
This “Data Encryption” scheme allows peers to encrypt any data with a secret, symmetric key for a group. This will be useful for building applications where users who enter a group late will still have access to previously-created content, for example private knowledge or wiki applications or a booking tool for rehearsal rooms.
A member will not learn about any newly-created data after they are removed from the group, since the key gets rotated on member removal or manual key update. This should accommodate for many use-cases in p2p applications which rely on basic group encryption with post-compromise security (PCS) and forward secrecy (FS) during key agreement.
§Messages
Every group operation (create or update
group, add or remove member) results in a
ControlMessage which is broadcast to the network for each group member, along with a set of direct messages.
A DirectMessage is sent to a specific group member and contains the group secrets encrypted
towards them for key agreement.
Application messages contain the ciphertexts and parameters required to decrypt it.
§Key agreement and encryption
The “Data Encryption” group API is mostly a wrapper around the 2SM (Two-Party Secure
Messaging) key agreement protocol. On creating or updating a group and
removing a member, a new, random GroupSecret is generated. Every
secret is identified with a unique GroupSecretId and has a UNIX timestamp indicating when
it was created.
Peers maintain a SecretBundle with all group secrets inside. Secrets are added to the
bundle when local group operations took place or when learning about a new secret from another
member after receiving a control message.
When sending new data into the group we look up the latest secret in the bundle (via comparing timestamps) and use XChaCha20Poly1305 as an AEAD to encrypt the payload with a random nonce. Next to each ciphertext the used nonce and group secret id is mentioned so other members of the group can decrypt the data.
Members who have been added to the group will learn about the whole secret bundle included in a direct “welcome” message encrypted towards them using the 2SM protocol. Through this the added member will be able to decrypt all previously-created content as they will learn about all used secrets.
§Optional forward secrecy
Applications can remove group secrets for forward secrecy based on their own logic. For
removing group secrets implementers can use the EncryptionGroup::update_secrets method.
For stronger forward secrecy guarantees have a look at the “Message Encryption” scheme.
§Key bundles
For initial key agreement (X3DH) peers need to publish key bundles into the network to allow others to invite them into groups. For the “Data Encryption” scheme we’re using long-term pre-keys with lifetimes specified by the application.
More on key bundles can be read here.
§Usage
Check out the EncryptionGroup API for establishing and maintaining groups using the “Data
Encryption” scheme.
GroupSecret and SecretBundle are always explicitly passed into every group operation
(“add member”, “remove member”, etc.) to allow full control over the managed keys for
applications.
Developers need to bring their own data types with group message interfaces, decentralised group membership (DGM) and ordering implementations when using this crate directly. For easier use without this overhead it’s recommended to look into higher-level integrations using the p2panda stack.
Re-exports§
pub use dcgka::ControlMessage;pub use dcgka::DirectMessage;pub use dcgka::DirectMessageContent;pub use dcgka::DirectMessageType;pub use group::EncryptionGroup;pub use group::GroupError;pub use group::GroupOutput;pub use group::GroupResult;pub use group::GroupState;pub use group_secret::GROUP_SECRET_SIZE;pub use group_secret::GroupSecret;pub use group_secret::GroupSecretError;pub use group_secret::GroupSecretId;pub use group_secret::SecretBundle;pub use group_secret::SecretBundleState;
Modules§
- dcgka
- A decentralized continuous group key agreement protocol (DCGKA) for p2panda’s “data encryption” scheme with forward secrecy and post-compromise security.
- group
- API to manage groups using the “Data Encryption” scheme and process remote control- and application messages.
- group_
secret - Methods to create and maintain multiple secrets known by a group which are used to encrypt and decrypt data.
- test_
utils