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::errors::InvalidExtensionError,
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,
98    /// List of initial leaf node extensions
99    pub(crate) leaf_node_extensions: Extensions,
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 {
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(
327        mut self,
328        extensions: Extensions,
329    ) -> Result<Self, InvalidExtensionError> {
330        let is_valid_in_group_context = extensions.application_id().is_none()
331            && extensions.ratchet_tree().is_none()
332            && extensions.external_pub().is_none();
333        if !is_valid_in_group_context {
334            return Err(InvalidExtensionError::IllegalInGroupContext);
335        }
336        self.config.group_context_extensions = extensions;
337        Ok(self)
338    }
339
340    /// Sets extensions of the group creator's [`LeafNode`].
341    ///
342    /// Returns an error if the extension types are not valid in a leaf node.
343    pub fn with_leaf_node_extensions(
344        mut self,
345        extensions: Extensions,
346    ) -> Result<Self, LeafNodeValidationError> {
347        // Ensure that these extensions are not invalid for leaf nodes.
348        // https://validation.openmls.tech/#valn1601
349        if extensions.validate_extension_types_for_leaf_node().is_err() {
350            log::error!("Invalid leaf node extension.");
351            return Err(LeafNodeValidationError::UnsupportedExtensions);
352        }
353
354        // Make sure that the extension type is supported in this context.
355        // This means that the leaf node needs to have support listed in the
356        // the capabilities (https://validation.openmls.tech/#valn0107).
357        if !self.config.capabilities.contains_extensions(&extensions) {
358            return Err(LeafNodeValidationError::ExtensionsNotInCapabilities);
359        }
360
361        self.config.leaf_node_extensions = extensions;
362        Ok(self)
363    }
364
365    /// Finalizes the builder and returns an [`MlsGroupCreateConfig`].
366    pub fn build(self) -> MlsGroupCreateConfig {
367        self.config
368    }
369}
370
371/// Defines what wire format is acceptable for incoming handshake messages.
372/// Note that application messages must always be encrypted.
373#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
374pub enum IncomingWireFormatPolicy {
375    /// Handshake messages must always be PrivateMessage
376    AlwaysCiphertext,
377    /// Handshake messages must always be PublicMessage
378    AlwaysPlaintext,
379    /// Handshake messages can either be PrivateMessage or PublicMessage
380    Mixed,
381}
382
383impl IncomingWireFormatPolicy {
384    pub(crate) fn is_compatible_with(&self, wire_format: WireFormat) -> bool {
385        match self {
386            IncomingWireFormatPolicy::AlwaysCiphertext => wire_format == WireFormat::PrivateMessage,
387            IncomingWireFormatPolicy::AlwaysPlaintext => wire_format == WireFormat::PublicMessage,
388            IncomingWireFormatPolicy::Mixed => {
389                wire_format == WireFormat::PrivateMessage
390                    || wire_format == WireFormat::PublicMessage
391            }
392        }
393    }
394}
395
396/// Defines what wire format should be used for outgoing handshake messages.
397/// Note that application messages must always be encrypted.
398#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
399pub enum OutgoingWireFormatPolicy {
400    /// Handshake messages must always be PrivateMessage
401    AlwaysCiphertext,
402    /// Handshake messages must always be PublicMessage
403    AlwaysPlaintext,
404}
405
406/// Defines what wire format is desired for outgoing handshake messages.
407/// Note that application messages must always be encrypted.
408#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
409pub struct WireFormatPolicy {
410    outgoing: OutgoingWireFormatPolicy,
411    incoming: IncomingWireFormatPolicy,
412}
413
414impl WireFormatPolicy {
415    /// Creates a new wire format policy from an [`OutgoingWireFormatPolicy`]
416    /// and an [`IncomingWireFormatPolicy`].
417    #[cfg(any(feature = "test-utils", test))]
418    pub(crate) fn new(
419        outgoing: OutgoingWireFormatPolicy,
420        incoming: IncomingWireFormatPolicy,
421    ) -> Self {
422        Self { outgoing, incoming }
423    }
424
425    /// Returns a reference to the wire format policy's outgoing wire format policy.
426    pub fn outgoing(&self) -> OutgoingWireFormatPolicy {
427        self.outgoing
428    }
429
430    /// Returns a reference to the wire format policy's incoming wire format policy.
431    pub fn incoming(&self) -> IncomingWireFormatPolicy {
432        self.incoming
433    }
434}
435
436impl Default for WireFormatPolicy {
437    fn default() -> Self {
438        PURE_CIPHERTEXT_WIRE_FORMAT_POLICY
439    }
440}
441
442impl From<OutgoingWireFormatPolicy> for WireFormat {
443    fn from(outgoing: OutgoingWireFormatPolicy) -> Self {
444        match outgoing {
445            OutgoingWireFormatPolicy::AlwaysCiphertext => WireFormat::PrivateMessage,
446            OutgoingWireFormatPolicy::AlwaysPlaintext => WireFormat::PublicMessage,
447        }
448    }
449}
450
451/// All valid wire format policy combinations.
452/// - [`PURE_PLAINTEXT_WIRE_FORMAT_POLICY`]
453/// - [`PURE_CIPHERTEXT_WIRE_FORMAT_POLICY`]
454/// - [`MIXED_PLAINTEXT_WIRE_FORMAT_POLICY`]
455/// - [`MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY`]
456pub const WIRE_FORMAT_POLICIES: [WireFormatPolicy; 4] = [
457    PURE_PLAINTEXT_WIRE_FORMAT_POLICY,
458    PURE_CIPHERTEXT_WIRE_FORMAT_POLICY,
459    MIXED_PLAINTEXT_WIRE_FORMAT_POLICY,
460    MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY,
461];
462
463/// Incoming and outgoing wire formats are always plaintext.
464pub const PURE_PLAINTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
465    outgoing: OutgoingWireFormatPolicy::AlwaysPlaintext,
466    incoming: IncomingWireFormatPolicy::AlwaysPlaintext,
467};
468
469/// Incoming and outgoing wire formats are always ciphertext.
470pub const PURE_CIPHERTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
471    outgoing: OutgoingWireFormatPolicy::AlwaysCiphertext,
472    incoming: IncomingWireFormatPolicy::AlwaysCiphertext,
473};
474
475/// Incoming wire formats can be mixed while outgoing wire formats are always
476/// plaintext.
477pub const MIXED_PLAINTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
478    outgoing: OutgoingWireFormatPolicy::AlwaysPlaintext,
479    incoming: IncomingWireFormatPolicy::Mixed,
480};
481
482/// Incoming wire formats can be mixed while outgoing wire formats are always
483/// ciphertext.
484pub const MIXED_CIPHERTEXT_WIRE_FORMAT_POLICY: WireFormatPolicy = WireFormatPolicy {
485    outgoing: OutgoingWireFormatPolicy::AlwaysCiphertext,
486    incoming: IncomingWireFormatPolicy::Mixed,
487};
openmls/group/mls_group/config.rs

openmls/group/mls_group/
config.rs
