openmls/group/mls_group/
config.rs

1//! Configuration module for [`MlsGroup`] configurations.
2//!
3//! ## Building an MlsGroupCreateConfig
4//! The [`MlsGroupCreateConfigBuilder`] makes it easy to build configurations for the
5//! [`MlsGroup`].
6//!
7//! ```
8//! use openmls::prelude::*;
9//!
10//! let group_config = MlsGroupCreateConfig::builder()
11//!     .use_ratchet_tree_extension(true)
12//!     .build();
13//! ```
14//!
15//! See [`MlsGroupCreateConfigBuilder`](MlsGroupCreateConfigBuilder#implementations) for
16//! all options that can be configured.
17//!
18//! ### Wire format policies
19//! Only some combination of possible wire formats are valid within OpenMLS.
20//! The [`WIRE_FORMAT_POLICIES`] lists all valid options that can be set.
21//!
22//! ```
23//! use openmls::prelude::*;
24//!
25//! let group_config = MlsGroupCreateConfig::builder()
26//!     .wire_format_policy(MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY)
27//!     .build();
28//! ```
29
30use super::*;
31use crate::{
32    extensions::Extensions,
33    key_packages::Lifetime,
34    tree::sender_ratchet::SenderRatchetConfiguration,
35    treesync::{errors::LeafNodeValidationError, node::leaf_node::Capabilities},
36};
37use serde::{Deserialize, Serialize};
38
39/// The [`MlsGroupJoinConfig`] contains all configuration parameters that are
40/// relevant to group operation at runtime. It is used to configure the group's
41/// behaviour when joining an existing group. To configure a newly created
42/// group, use [`MlsGroupCreateConfig`].
43#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
44pub struct MlsGroupJoinConfig {
45    /// Defines the wire format policy for outgoing and incoming handshake messages.
46    /// Application are always encrypted regardless.
47    pub(crate) wire_format_policy: WireFormatPolicy,
48    /// Size of padding in bytes
49    pub(crate) padding_size: usize,
50    /// Maximum number of past epochs for which application messages
51    /// can be decrypted. The default is 0.
52    pub(crate) max_past_epochs: usize,
53    /// Number of resumption secrets to keep
54    pub(crate) number_of_resumption_psks: usize,
55    /// Flag to indicate the Ratchet Tree Extension should be used
56    pub(crate) use_ratchet_tree_extension: bool,
57    /// Sender ratchet configuration
58    pub(crate) sender_ratchet_configuration: SenderRatchetConfiguration,
59}
60
61impl MlsGroupJoinConfig {
62    /// Returns a builder for [`MlsGroupJoinConfig`].
63    pub fn builder() -> MlsGroupJoinConfigBuilder {
64        MlsGroupJoinConfigBuilder::new()
65    }
66
67    /// Returns the wire format policy set in this  [`MlsGroupJoinConfig`].
68    pub fn wire_format_policy(&self) -> WireFormatPolicy {
69        self.wire_format_policy
70    }
71
72    /// Returns the padding size set in this  [`MlsGroupJoinConfig`].
73    pub fn padding_size(&self) -> usize {
74        self.padding_size
75    }
76
77    /// Returns the [`SenderRatchetConfiguration`] set in this  [`MlsGroupJoinConfig`].
78    pub fn sender_ratchet_configuration(&self) -> &SenderRatchetConfiguration {
79        &self.sender_ratchet_configuration
80    }
81}
82
83/// Specifies configuration for the creation of an [`MlsGroup`]. Refer to the
84/// [User Manual](https://book.openmls.tech/user_manual/group_config.html) for
85/// more information about the different configuration values.
86#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
87pub struct MlsGroupCreateConfig {
88    /// Capabilities advertised in the creator's leaf node
89    pub(crate) capabilities: Capabilities,
90    /// Lifetime of the own leaf node
91    pub(crate) lifetime: Lifetime,
92    /// Ciphersuite and protocol version
93    pub(crate) ciphersuite: Ciphersuite,
94    /// Configuration parameters relevant to group operation at runtime
95    pub(crate) join_config: MlsGroupJoinConfig,
96    /// List of initial group context extensions
97    pub(crate) group_context_extensions: Extensions<GroupContext>,
98    /// List of initial leaf node extensions
99    pub(crate) leaf_node_extensions: Extensions<LeafNode>,
100}
101
102impl Default for MlsGroupCreateConfig {
103    fn default() -> Self {
104        Self {
105            capabilities: Capabilities::default(),
106            lifetime: Lifetime::default(),
107            ciphersuite: Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519,
108            join_config: MlsGroupJoinConfig::default(),
109            group_context_extensions: Extensions::default(),
110            leaf_node_extensions: Extensions::default(),
111        }
112    }
113}
114
115/// Builder struct for an [`MlsGroupJoinConfig`].
116#[derive(Default)]
117pub struct MlsGroupJoinConfigBuilder {
118    join_config: MlsGroupJoinConfig,
119}
120
121impl MlsGroupJoinConfigBuilder {
122    /// Creates a new builder with default values.
123    fn new() -> Self {
124        Self {
125            join_config: MlsGroupJoinConfig::default(),
126        }
127    }
128
129    /// Sets the `wire_format` property of the [`MlsGroupJoinConfig`].
130    pub fn wire_format_policy(mut self, wire_format_policy: WireFormatPolicy) -> Self {
131        self.join_config.wire_format_policy = wire_format_policy;
132        self
133    }
134
135    /// Sets the `padding_size` property of the [`MlsGroupJoinConfig`].
136    pub fn padding_size(mut self, padding_size: usize) -> Self {
137        self.join_config.padding_size = padding_size;
138        self
139    }
140
141    /// Sets the `max_past_epochs` property of the [`MlsGroupJoinConfig`].
142    pub fn max_past_epochs(mut self, max_past_epochs: usize) -> Self {
143        self.join_config.max_past_epochs = max_past_epochs;
144        self
145    }
146
147    /// Sets the `number_of_resumption_psks` property of the [`MlsGroupJoinConfig`].
148    pub fn number_of_resumption_psks(mut self, number_of_resumption_psks: usize) -> Self {
149        self.join_config.number_of_resumption_psks = number_of_resumption_psks;
150        self
151    }
152
153    /// Sets the `use_ratchet_tree_extension` property of the [`MlsGroupJoinConfig`].
154    pub fn use_ratchet_tree_extension(mut self, use_ratchet_tree_extension: bool) -> Self {
155        self.join_config.use_ratchet_tree_extension = use_ratchet_tree_extension;
156        self
157    }
158
159    /// Sets the `sender_ratchet_configuration` property of the [`MlsGroupJoinConfig`].
160    pub fn sender_ratchet_configuration(
161        mut self,
162        sender_ratchet_configuration: SenderRatchetConfiguration,
163    ) -> Self {
164        self.join_config.sender_ratchet_configuration = sender_ratchet_configuration;
165        self
166    }
167
168    /// Finalizes the builder and returns an [`MlsGroupJoinConfig`].
169    pub fn build(self) -> MlsGroupJoinConfig {
170        self.join_config
171    }
172}
173
174impl MlsGroupCreateConfig {
175    /// Returns a builder for [`MlsGroupCreateConfig`]
176    pub fn builder() -> MlsGroupCreateConfigBuilder {
177        MlsGroupCreateConfigBuilder::new()
178    }
179
180    /// Returns the [`MlsGroupCreateConfig`] wire format policy.
181    pub fn wire_format_policy(&self) -> WireFormatPolicy {
182        self.join_config.wire_format_policy
183    }
184
185    /// Returns the [`MlsGroupCreateConfig`] padding size.
186    pub fn padding_size(&self) -> usize {
187        self.join_config.padding_size
188    }
189
190    /// Returns the [`MlsGroupCreateConfig`] max past epochs.
191    pub fn max_past_epochs(&self) -> usize {
192        self.join_config.max_past_epochs
193    }
194
195    /// Returns the [`MlsGroupCreateConfig`] number of resumption psks.
196    pub fn number_of_resumption_psks(&self) -> usize {
197        self.join_config.number_of_resumption_psks
198    }
199
200    /// Returns the [`MlsGroupCreateConfig`] boolean flag that indicates whether ratchet_tree_extension should be used.
201    pub fn use_ratchet_tree_extension(&self) -> bool {
202        self.join_config.use_ratchet_tree_extension
203    }
204
205    /// Returns the [`MlsGroupCreateConfig`] sender ratchet configuration.
206    pub fn sender_ratchet_configuration(&self) -> &SenderRatchetConfiguration {
207        &self.join_config.sender_ratchet_configuration
208    }
209
210    /// Returns the [`Extensions`] set as the initial group context.
211    /// This does not contain the initial group context extensions
212    /// added from builder calls to `external_senders` or `required_capabilities`.
213    pub fn group_context_extensions(&self) -> &Extensions<GroupContext> {
214        &self.group_context_extensions
215    }
216
217    /// Returns the [`MlsGroupCreateConfig`] lifetime configuration.
218    pub fn lifetime(&self) -> &Lifetime {
219        &self.lifetime
220    }
221
222    /// Returns the [`Ciphersuite`].
223    pub fn ciphersuite(&self) -> Ciphersuite {
224        self.ciphersuite
225    }
226
227    #[cfg(any(feature = "test-utils", test))]
228    pub fn test_default(ciphersuite: Ciphersuite) -> Self {
229        Self::builder()
230            .wire_format_policy(WireFormatPolicy::new(
231                OutgoingWireFormatPolicy::AlwaysPlaintext,
232                IncomingWireFormatPolicy::Mixed,
233            ))
234            .ciphersuite(ciphersuite)
235            .build()
236    }
237
238    /// Returns the [`MlsGroupJoinConfig`] of groups created with this create config.
239    pub fn join_config(&self) -> &MlsGroupJoinConfig {
240        &self.join_config
241    }
242}
243
244/// Builder for an [`MlsGroupCreateConfig`].
245#[derive(Default, Debug)]
246pub struct MlsGroupCreateConfigBuilder {
247    config: MlsGroupCreateConfig,
248}
249
250impl MlsGroupCreateConfigBuilder {
251    /// Creates a new builder with default values.
252    fn new() -> Self {
253        MlsGroupCreateConfigBuilder {
254            config: MlsGroupCreateConfig::default(),
255        }
256    }
257
258    /// Sets the `wire_format` property of the MlsGroupCreateConfig.
259    pub fn wire_format_policy(mut self, wire_format_policy: WireFormatPolicy) -> Self {
260        self.config.join_config.wire_format_policy = wire_format_policy;
261        self
262    }
263
264    /// Sets the `padding_size` property of the MlsGroupCreateConfig.
265    pub fn padding_size(mut self, padding_size: usize) -> Self {
266        self.config.join_config.padding_size = padding_size;
267        self
268    }
269
270    /// Sets the `max_past_epochs` property of the MlsGroupCreateConfig.
271    /// This allows application messages from previous epochs to be decrypted.
272    ///
273    /// **WARNING**
274    ///
275    /// This feature enables the storage of message secrets from past epochs.
276    /// It is a trade-off between functionality and forward secrecy and should only be enabled
277    /// if the Delivery Service cannot guarantee that application messages will be sent in
278    /// the same epoch in which they were generated. The number for `max_epochs` should be
279    /// as low as possible.
280    pub fn max_past_epochs(mut self, max_past_epochs: usize) -> Self {
281        self.config.join_config.max_past_epochs = max_past_epochs;
282        self
283    }
284
285    /// Sets the `number_of_resumption_psks` property of the MlsGroupCreateConfig.
286    pub fn number_of_resumption_psks(mut self, number_of_resumption_psks: usize) -> Self {
287        self.config.join_config.number_of_resumption_psks = number_of_resumption_psks;
288        self
289    }
290
291    /// Sets the `use_ratchet_tree_extension` property of the MlsGroupCreateConfig.
292    pub fn use_ratchet_tree_extension(mut self, use_ratchet_tree_extension: bool) -> Self {
293        self.config.join_config.use_ratchet_tree_extension = use_ratchet_tree_extension;
294        self
295    }
296
297    /// Sets the `capabilities` of the group creator's leaf node.
298    pub fn capabilities(mut self, capabilities: Capabilities) -> Self {
299        self.config.capabilities = capabilities;
300        self
301    }
302
303    /// Sets the `sender_ratchet_configuration` property of the MlsGroupCreateConfig.
304    /// See [`SenderRatchetConfiguration`] for more information.
305    pub fn sender_ratchet_configuration(
306        mut self,
307        sender_ratchet_configuration: SenderRatchetConfiguration,
308    ) -> Self {
309        self.config.join_config.sender_ratchet_configuration = sender_ratchet_configuration;
310        self
311    }
312
313    /// Sets the `lifetime` property of the MlsGroupCreateConfig.
314    pub fn lifetime(mut self, lifetime: Lifetime) -> Self {
315        self.config.lifetime = lifetime;
316        self
317    }
318
319    /// Sets the `ciphersuite` property of the MlsGroupCreateConfig.
320    pub fn ciphersuite(mut self, ciphersuite: Ciphersuite) -> Self {
321        self.config.ciphersuite = ciphersuite;
322        self
323    }
324
325    /// Sets initial group context extensions.
326    pub fn with_group_context_extensions(mut self, extensions: Extensions<GroupContext>) -> Self {
327        self.config.group_context_extensions = extensions;
328        self
329    }
330
331    /// Sets extensions of the group creator's [`LeafNode`].
332    ///
333    /// Returns an error if the extension types are not valid in a leaf node.
334    pub fn with_leaf_node_extensions(
335        mut self,
336        extensions: Extensions<LeafNode>,
337    ) -> Result<Self, LeafNodeValidationError> {
338        // Make sure that the extension type is supported in this context.
339        // This means that the leaf node needs to have support listed in the
340        // the capabilities (https://validation.openmls.tech/#valn0107).
341        if !self.config.capabilities.contains_extensions(&extensions) {
342            return Err(LeafNodeValidationError::ExtensionsNotInCapabilities);
343        }
344
345        // Note that the extensions have already been checked to be allowed here.
346        self.config.leaf_node_extensions = extensions;
347        Ok(self)
348    }
349
350    /// Finalizes the builder and returns an [`MlsGroupCreateConfig`].
351    pub fn build(self) -> MlsGroupCreateConfig {
352        self.config
353    }
354}
355
356/// Defines what wire format is acceptable for incoming handshake messages.
357/// Note that application messages must always be encrypted.
358#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
359pub enum IncomingWireFormatPolicy {
360    /// Handshake messages must always be PrivateMessage
361    AlwaysCiphertext,
362    /// Handshake messages must always be PublicMessage
363    AlwaysPlaintext,
364    /// Handshake messages can either be PrivateMessage or PublicMessage
365    Mixed,
366}
367
368impl IncomingWireFormatPolicy {
369    pub(crate) fn is_compatible_with(&self, wire_format: WireFormat) -> bool {
370        match self {
371            IncomingWireFormatPolicy::AlwaysCiphertext => wire_format == WireFormat::PrivateMessage,
372            IncomingWireFormatPolicy::AlwaysPlaintext => wire_format == WireFormat::PublicMessage,
373            IncomingWireFormatPolicy::Mixed => {
374                wire_format == WireFormat::PrivateMessage
375                    || wire_format == WireFormat::PublicMessage
376            }
377        }
378    }
379}
380
381/// Defines what wire format should be used for outgoing handshake messages.
382/// Note that application messages must always be encrypted.
383#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
384pub enum OutgoingWireFormatPolicy {
385    /// Handshake messages must always be PrivateMessage
386    AlwaysCiphertext,
387    /// Handshake messages must always be PublicMessage
388    AlwaysPlaintext,
389}
390
391/// Defines what wire format is desired for outgoing handshake messages.
392/// Note that application messages must always be encrypted.
393#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
394pub struct WireFormatPolicy {
395    outgoing: OutgoingWireFormatPolicy,
396    incoming: IncomingWireFormatPolicy,
397}
398
399impl WireFormatPolicy {
400    /// Creates a new wire format policy from an [`OutgoingWireFormatPolicy`]
401    /// and an [`IncomingWireFormatPolicy`].
402    #[cfg(any(feature = "test-utils", test))]
403    pub(crate) fn new(
404        outgoing: OutgoingWireFormatPolicy,
405        incoming: IncomingWireFormatPolicy,
406    ) -> Self {
407        Self { outgoing, incoming }
408    }
409
410    /// Returns a reference to the wire format policy's outgoing wire format policy.
411    pub fn outgoing(&self) -> OutgoingWireFormatPolicy {
412        self.outgoing
413    }
414
415    /// Returns a reference to the wire format policy's incoming wire format policy.
416    pub fn incoming(&self) -> IncomingWireFormatPolicy {
417        self.incoming
418    }
419}
420
421impl Default for WireFormatPolicy {
422    fn default() -> Self {
423        PURE_CIPHERTEXT_WIRE_FORMAT_POLICY
424    }
425}
426
427impl From<OutgoingWireFormatPolicy> for WireFormat {
428    fn from(outgoing: OutgoingWireFormatPolicy) -> Self {
429        match outgoing {
430            OutgoingWireFormatPolicy::AlwaysCiphertext => WireFormat::PrivateMessage,
431            OutgoingWireFormatPolicy::AlwaysPlaintext => WireFormat::PublicMessage,
432        }
433    }
434}
435
436/// All valid wire format policy combinations.
437/// - [`PURE_PLAINTEXT_WIRE_FORMAT_POLICY`]
438/// - [`PURE_CIPHERTEXT_WIRE_FORMAT_POLICY`]
439/// - [`MIXED_PLAINTEXT_WIRE_FORMAT_POLICY`]
440/// - [`MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY`]
441pub const WIRE_FORMAT_POLICIES: [WireFormatPolicy; 4] = [
442    PURE_PLAINTEXT_WIRE_FORMAT_POLICY,
443    PURE_CIPHERTEXT_WIRE_FORMAT_POLICY,
444    MIXED_PLAINTEXT_WIRE_FORMAT_POLICY,
445    MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY,
446];
447
448/// Incoming and outgoing wire formats are always plaintext.
449pub const PURE_PLAINTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
450    outgoing: OutgoingWireFormatPolicy::AlwaysPlaintext,
451    incoming: IncomingWireFormatPolicy::AlwaysPlaintext,
452};
453
454/// Incoming and outgoing wire formats are always ciphertext.
455pub const PURE_CIPHERTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
456    outgoing: OutgoingWireFormatPolicy::AlwaysCiphertext,
457    incoming: IncomingWireFormatPolicy::AlwaysCiphertext,
458};
459
460/// Incoming wire formats can be mixed while outgoing wire formats are always
461/// plaintext.
462pub const MIXED_PLAINTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
463    outgoing: OutgoingWireFormatPolicy::AlwaysPlaintext,
464    incoming: IncomingWireFormatPolicy::Mixed,
465};
466
467/// Incoming wire formats can be mixed while outgoing wire formats are always
468/// ciphertext.
469pub const MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
470    outgoing: OutgoingWireFormatPolicy::AlwaysCiphertext,
471    incoming: IncomingWireFormatPolicy::Mixed,
472};
openmls/group/mls_group/config.rs

openmls/group/mls_group/
config.rs
