openmls/components/
vc_commit_data.rs1use 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#[derive(thiserror::Error, Debug, PartialEq, Eq, Clone)]
48pub enum VcCommitDataError {
49 #[error("VirtualClientCommitData carries more than one new_derivation_epoch action")]
51 MultipleNewDerivationEpochs,
52 #[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#[derive(Debug, PartialEq, TlsSerialize, TlsDeserializeBytes, TlsSize)]
65#[repr(u8)]
66pub enum VirtualClientAction {
67 #[tls_codec(discriminant = 1)]
69 KeyPackageUpload(KeyPackageUpload),
70 #[tls_codec(discriminant = 2)]
72 NewDerivationEpoch,
73}
74
75#[derive(Debug, PartialEq, TlsSerialize, TlsSize)]
77pub struct VirtualClientCommitData {
78 actions: Vec<VirtualClientAction>,
79}
80
81impl VirtualClientCommitData {
82 pub fn new(actions: Vec<VirtualClientAction>) -> Result<Self, VcCommitDataError> {
87 Self::validate(&actions)?;
88 Ok(Self { actions })
89 }
90
91 pub fn actions(&self) -> &[VirtualClientAction] {
93 &self.actions
94 }
95
96 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 pub fn creates_derivation_epoch(&self) -> bool {
106 self.actions
107 .iter()
108 .any(|action| matches!(action, VirtualClientAction::NewDerivationEpoch))
109 }
110
111 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 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 pub fn from_safe_aad_item_data(data: &[u8]) -> Result<Self, VcCommitDataError> {
129 Ok(Self::tls_deserialize_exact_bytes(data)?)
130 }
131
132 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 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 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}