Skip to main content

openmls/components/
vc_commit_data.rs

1//! Virtual-clients commit data (mls-virtual-clients draft).
2//!
3//! A virtual client attaches this struct to a commit as a Safe AAD item under
4//! [`VC_COMPONENT_ID`]. It tells the sibling emulators which actions the commit
5//! performs.
6//!
7//! ```tls
8//! enum {
9//!   reserved(0),
10//!   key_package_upload(1),
11//!   new_derivation_epoch(2),
12//!   (255)
13//! } ActionType;
14//!
15//! struct {
16//!   ActionType action_type;
17//!   select (VirtualClientAction.action_type) {
18//!     case key_package_upload:
19//!       KeyPackageUpload key_package_upload;
20//!     case new_derivation_epoch:
21//!       struct{};
22//!   };
23//! } VirtualClientAction;
24//!
25//! struct {
26//!   VirtualClientAction actions<V>;
27//! } VirtualClientCommitData;
28//! ```
29//!
30//! A [`VirtualClientCommitData`] carries at most one `new_derivation_epoch`
31//! action. That rule is enforced on construction and on deserialization.
32//!
33//! [`VC_COMPONENT_ID`]: crate::components::vc_derivation_info::VC_COMPONENT_ID
34//! [`VirtualClientCommitData`]: crate::components::vc_commit_data::VirtualClientCommitData
35
36use tls_codec::{
37    DeserializeBytes as TlsDeserializeBytesTrait, Serialize as TlsSerializeTrait,
38    TlsDeserializeBytes, TlsSerialize, TlsSize,
39};
40
41use crate::{
42    components::vc_derivation_info::{KeyPackageUpload, VC_COMPONENT_ID},
43    framing::{SafeAad, SafeAadItem},
44};
45
46/// Errors that can occur when building or parsing a [`VirtualClientCommitData`].
47#[derive(thiserror::Error, Debug, PartialEq, Eq, Clone)]
48pub enum VcCommitDataError {
49    /// More than one `new_derivation_epoch` action is present.
50    #[error("VirtualClientCommitData carries more than one new_derivation_epoch action")]
51    MultipleNewDerivationEpochs,
52    /// Encoding or decoding failure.
53    #[error("codec error: {0}")]
54    Codec(String),
55}
56
57impl From<tls_codec::Error> for VcCommitDataError {
58    fn from(err: tls_codec::Error) -> Self {
59        Self::Codec(err.to_string())
60    }
61}
62
63/// One action a virtual client's commit performs.
64#[derive(Debug, PartialEq, TlsSerialize, TlsDeserializeBytes, TlsSize)]
65#[repr(u8)]
66pub enum VirtualClientAction {
67    /// The author published a batch of KeyPackages.
68    #[tls_codec(discriminant = 1)]
69    KeyPackageUpload(KeyPackageUpload),
70    /// The author asks the group to start a new derivation epoch.
71    #[tls_codec(discriminant = 2)]
72    NewDerivationEpoch,
73}
74
75/// What a virtual client tells its siblings about a commit it authored.
76#[derive(Debug, PartialEq, TlsSerialize, TlsSize)]
77pub struct VirtualClientCommitData {
78    actions: Vec<VirtualClientAction>,
79}
80
81impl VirtualClientCommitData {
82    /// Assemble the commit data.
83    ///
84    /// Returns an error if `actions` holds more than one
85    /// [`VirtualClientAction::NewDerivationEpoch`].
86    pub fn new(actions: Vec<VirtualClientAction>) -> Result<Self, VcCommitDataError> {
87        Self::validate(&actions)?;
88        Ok(Self { actions })
89    }
90
91    /// All actions the commit performs.
92    pub fn actions(&self) -> &[VirtualClientAction] {
93        &self.actions
94    }
95
96    /// Adds a [`VirtualClientAction::NewDerivationEpoch`] action unless the
97    /// commit data already carries one.
98    pub(crate) fn require_new_derivation_epoch(&mut self) {
99        if !self.creates_derivation_epoch() {
100            self.actions.push(VirtualClientAction::NewDerivationEpoch);
101        }
102    }
103
104    /// Returns true if the commit asks for a new derivation epoch.
105    pub fn creates_derivation_epoch(&self) -> bool {
106        self.actions
107            .iter()
108            .any(|action| matches!(action, VirtualClientAction::NewDerivationEpoch))
109    }
110
111    /// The KeyPackage batches the commit publishes, in wire order.
112    pub fn key_package_uploads(&self) -> impl Iterator<Item = &KeyPackageUpload> {
113        self.actions.iter().filter_map(|action| match action {
114            VirtualClientAction::KeyPackageUpload(upload) => Some(upload),
115            VirtualClientAction::NewDerivationEpoch => None,
116        })
117    }
118
119    /// Wrap this commit data in a Safe AAD item tagged with
120    /// [`VC_COMPONENT_ID`], ready to be attached to an outgoing commit.
121    pub fn to_safe_aad_item(&self) -> Result<SafeAadItem, VcCommitDataError> {
122        let data = self.tls_serialize_detached()?;
123        Ok(SafeAadItem::new(VC_COMPONENT_ID, data))
124    }
125
126    /// Parse commit data from the bytes of a Safe AAD item tagged with
127    /// [`VC_COMPONENT_ID`]. Rejects bytes left over after the struct.
128    pub fn from_safe_aad_item_data(data: &[u8]) -> Result<Self, VcCommitDataError> {
129        Ok(Self::tls_deserialize_exact_bytes(data)?)
130    }
131
132    /// Parse the commit data carried by `safe_aad` under [`VC_COMPONENT_ID`].
133    ///
134    /// Returns `Ok(None)` when `safe_aad` carries no such item.
135    pub fn from_safe_aad(safe_aad: &SafeAad) -> Result<Option<Self>, VcCommitDataError> {
136        safe_aad
137            .get(VC_COMPONENT_ID)
138            .map(Self::from_safe_aad_item_data)
139            .transpose()
140    }
141
142    fn validate(actions: &[VirtualClientAction]) -> Result<(), VcCommitDataError> {
143        let new_epoch_actions = actions
144            .iter()
145            .filter(|action| matches!(action, VirtualClientAction::NewDerivationEpoch))
146            .count();
147        if new_epoch_actions > 1 {
148            return Err(VcCommitDataError::MultipleNewDerivationEpochs);
149        }
150        Ok(())
151    }
152}
153
154impl TlsDeserializeBytesTrait for VirtualClientCommitData {
155    fn tls_deserialize_bytes(bytes: &[u8]) -> Result<(Self, &[u8]), tls_codec::Error> {
156        let (actions, rest) = Vec::<VirtualClientAction>::tls_deserialize_bytes(bytes)?;
157        let commit_data = VirtualClientCommitData::new(actions)
158            .map_err(|err| tls_codec::Error::DecodingError(err.to_string()))?;
159        Ok((commit_data, rest))
160    }
161}
162
163#[cfg(test)]
164mod tests {
165    use openmls_traits::types::Ciphersuite;
166
167    use super::*;
168    use crate::{
169        binary_tree::LeafNodeIndex,
170        ciphersuite::hash_ref::KeyPackageRef,
171        components::vc_derivation_info::{EpochId, KeyPackageInfo},
172        extensions::{Extension, Extensions, LastResortExtension, UnknownExtension},
173    };
174
175    const CIPHERSUITE: Ciphersuite = Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519;
176
177    fn epoch_id(bytes: &[u8]) -> EpochId {
178        EpochId::new(bytes.to_vec())
179    }
180
181    fn key_package_upload() -> KeyPackageUpload {
182        KeyPackageUpload {
183            epoch_id: epoch_id(b"epoch-for-upload"),
184            leaf_index: LeafNodeIndex::new(3),
185            generation: 7,
186            key_package_info: vec![
187                KeyPackageInfo {
188                    key_package_ref: KeyPackageRef::from_slice(b"first key package ref"),
189                    cipher_suite: CIPHERSUITE,
190                    key_package_index: 0,
191                    extensions: Extensions::empty(),
192                },
193                KeyPackageInfo {
194                    key_package_ref: KeyPackageRef::from_slice(b"second key package ref"),
195                    cipher_suite: CIPHERSUITE,
196                    key_package_index: 1,
197                    // Unknown extensions must survive the round trip in
198                    // their original position.
199                    extensions: Extensions::from_vec(vec![
200                        Extension::Unknown(0xff00, UnknownExtension(b"unknown".to_vec())),
201                        Extension::LastResort(LastResortExtension::default()),
202                    ])
203                    .expect("distinct extension types are valid"),
204                },
205            ],
206        }
207    }
208
209    fn full_commit_data() -> VirtualClientCommitData {
210        VirtualClientCommitData::new(vec![
211            VirtualClientAction::KeyPackageUpload(key_package_upload()),
212            VirtualClientAction::NewDerivationEpoch,
213        ])
214        .expect("one new_derivation_epoch action is valid")
215    }
216
217    #[test]
218    fn vc_commit_data_roundtrip() {
219        let commit_data = full_commit_data();
220
221        let bytes = commit_data.tls_serialize_detached().unwrap();
222        let parsed = VirtualClientCommitData::tls_deserialize_exact_bytes(&bytes).unwrap();
223
224        assert_eq!(parsed, commit_data);
225        assert_eq!(parsed.tls_serialize_detached().unwrap(), bytes);
226        assert!(parsed.creates_derivation_epoch());
227        assert_eq!(
228            parsed.key_package_uploads().collect::<Vec<_>>(),
229            vec![&key_package_upload()]
230        );
231    }
232
233    #[test]
234    fn vc_commit_data_new_rejects_two_new_derivation_epochs() {
235        let err = VirtualClientCommitData::new(vec![
236            VirtualClientAction::NewDerivationEpoch,
237            VirtualClientAction::NewDerivationEpoch,
238        ])
239        .unwrap_err();
240
241        assert_eq!(err, VcCommitDataError::MultipleNewDerivationEpochs);
242    }
243
244    #[test]
245    fn vc_commit_data_deserialize_rejects_two_new_derivation_epochs() {
246        // Hand-craft bytes the constructor would refuse to produce: two
247        // `new_derivation_epoch` actions.
248        let raw_bytes = vec![0x02, 0x02, 0x02];
249
250        let err = VirtualClientCommitData::tls_deserialize_exact_bytes(&raw_bytes).unwrap_err();
251        match err {
252            tls_codec::Error::DecodingError(message) => assert!(
253                message.contains("more than one new_derivation_epoch"),
254                "unexpected error message: {message}"
255            ),
256            other => panic!("unexpected error variant: {other:?}"),
257        }
258    }
259
260    #[test]
261    fn vc_action_deserialize_rejects_reserved_and_unknown_types() {
262        for discriminant in [0x00u8, 0x03, 0xff] {
263            let err = VirtualClientAction::tls_deserialize_exact_bytes(&[discriminant])
264                .expect_err("only key_package_upload and new_derivation_epoch are valid");
265            assert!(
266                matches!(err, tls_codec::Error::UnknownValue(value) if value == discriminant as u64),
267                "unexpected error variant for {discriminant}: {err:?}"
268            );
269        }
270    }
271
272    #[test]
273    fn vc_commit_data_safe_aad_item_roundtrip() {
274        let commit_data = full_commit_data();
275
276        let item = commit_data.to_safe_aad_item().unwrap();
277        assert_eq!(item.component_id(), VC_COMPONENT_ID);
278
279        let parsed = VirtualClientCommitData::from_safe_aad_item_data(item.data()).unwrap();
280        assert_eq!(parsed, commit_data);
281    }
282
283    #[test]
284    fn vc_commit_data_from_item_data_rejects_trailing_bytes() {
285        let mut data = full_commit_data()
286            .to_safe_aad_item()
287            .unwrap()
288            .data()
289            .to_vec();
290        data.push(0x00);
291
292        let err = VirtualClientCommitData::from_safe_aad_item_data(&data).unwrap_err();
293        assert_eq!(
294            err,
295            VcCommitDataError::Codec(tls_codec::Error::TrailingData.to_string())
296        );
297    }
298}