1use std::borrow::Borrow;
4
5use openmls_traits::{random::OpenMlsRand, storage::StorageProvider as StorageProviderTrait};
6use serde::{Deserialize, Serialize};
7use tls_codec::{Serialize as TlsSerializeTrait, VLBytes};
8
9use super::*;
10#[cfg(feature = "extensions-draft")]
11use crate::component::ComponentId;
12use crate::{
13 group::{GroupEpoch, GroupId},
14 schedule::psk::store::ResumptionPskStore,
15 storage::{OpenMlsProvider, StorageProvider},
16};
17
18#[derive(
31 Clone,
32 Copy,
33 Debug,
34 PartialEq,
35 Eq,
36 PartialOrd,
37 Ord,
38 Hash,
39 Deserialize,
40 Serialize,
41 TlsDeserialize,
42 TlsDeserializeBytes,
43 TlsSerialize,
44 TlsSize,
45)]
46#[repr(u8)]
47pub enum ResumptionPskUsage {
48 Application = 1,
50 Reinit = 2,
54 Branch = 3,
58}
59
60#[derive(
62 Debug,
63 PartialEq,
64 Eq,
65 PartialOrd,
66 Ord,
67 Clone,
68 Hash,
69 Deserialize,
70 Serialize,
71 TlsDeserialize,
72 TlsDeserializeBytes,
73 TlsSerialize,
74 TlsSize,
75)]
76pub struct ExternalPsk {
77 psk_id: VLBytes,
78}
79
80impl ExternalPsk {
81 pub fn new(psk_id: Vec<u8>) -> Self {
83 Self {
84 psk_id: psk_id.into(),
85 }
86 }
87
88 pub fn psk_id(&self) -> &[u8] {
90 self.psk_id.as_slice()
91 }
92}
93
94#[derive(Serialize, Deserialize, TlsDeserialize, TlsDeserializeBytes, TlsSerialize, TlsSize)]
97pub(crate) struct PskBundle {
98 secret: Secret,
99}
100
101#[derive(
103 Clone,
104 Debug,
105 PartialEq,
106 Eq,
107 PartialOrd,
108 Ord,
109 Deserialize,
110 Serialize,
111 TlsDeserialize,
112 TlsDeserializeBytes,
113 TlsSerialize,
114 TlsSize,
115 Hash,
116)]
117pub struct ResumptionPsk {
118 pub(crate) usage: ResumptionPskUsage,
119 pub(crate) psk_group_id: GroupId,
120 pub(crate) psk_epoch: GroupEpoch,
121}
122
123impl ResumptionPsk {
124 pub fn new(usage: ResumptionPskUsage, psk_group_id: GroupId, psk_epoch: GroupEpoch) -> Self {
126 Self {
127 usage,
128 psk_group_id,
129 psk_epoch,
130 }
131 }
132
133 pub fn usage(&self) -> ResumptionPskUsage {
135 self.usage
136 }
137
138 pub fn psk_group_id(&self) -> &GroupId {
140 &self.psk_group_id
141 }
142
143 pub fn psk_epoch(&self) -> GroupEpoch {
145 self.psk_epoch
146 }
147}
148
149#[cfg(feature = "extensions-draft")]
153#[derive(
154 Clone,
155 Debug,
156 PartialEq,
157 Eq,
158 PartialOrd,
159 Ord,
160 Deserialize,
161 Serialize,
162 TlsDeserialize,
163 TlsDeserializeBytes,
164 TlsSerialize,
165 TlsSize,
166 Hash,
167)]
168pub struct ApplicationPsk {
169 pub(crate) component_id: ComponentId,
170 pub(crate) psk_id: VLBytes,
171}
172
173#[cfg(feature = "extensions-draft")]
174impl ApplicationPsk {
175 pub fn new(component_id: ComponentId, psk_id: VLBytes) -> Self {
177 Self {
178 component_id,
179 psk_id,
180 }
181 }
182
183 pub fn component_id(&self) -> ComponentId {
185 self.component_id
186 }
187
188 pub fn psk_id(&self) -> &[u8] {
190 self.psk_id.as_slice()
191 }
192}
193
194#[derive(
196 Clone,
197 Debug,
198 PartialEq,
199 Eq,
200 PartialOrd,
201 Ord,
202 Deserialize,
203 Serialize,
204 TlsDeserialize,
205 TlsDeserializeBytes,
206 TlsSerialize,
207 TlsSize,
208 Hash,
209)]
210#[repr(u8)]
211pub enum Psk {
212 #[tls_codec(discriminant = 1)]
214 External(ExternalPsk),
215 #[tls_codec(discriminant = 2)]
217 Resumption(ResumptionPsk),
218 #[cfg(feature = "extensions-draft")]
219 #[tls_codec(discriminant = 3)]
221 Application(ApplicationPsk),
222}
223
224#[derive(Clone, Copy, Debug, Eq, PartialEq)]
236#[repr(u8)]
237pub enum PskType {
238 External = 1,
240 Resumption = 2,
242 #[cfg(feature = "extensions-draft")]
243 Application = 3,
245}
246
247#[derive(
267 Clone,
268 Debug,
269 PartialEq,
270 Eq,
271 PartialOrd,
272 Ord,
273 Deserialize,
274 Serialize,
275 TlsDeserialize,
276 TlsDeserializeBytes,
277 TlsSerialize,
278 TlsSize,
279 Hash,
280)]
281pub struct PreSharedKeyId {
282 pub(crate) psk: Psk,
283 pub(crate) psk_nonce: VLBytes,
284}
285
286impl PreSharedKeyId {
287 pub fn new(
289 ciphersuite: Ciphersuite,
290 rand: &impl OpenMlsRand,
291 psk: Psk,
292 ) -> Result<Self, CryptoError> {
293 let psk_nonce = rand
294 .random_vec(ciphersuite.hash_length())
295 .map_err(|_| CryptoError::InsufficientRandomness)?
296 .into();
297
298 Ok(Self { psk, psk_nonce })
299 }
300
301 pub fn external(psk_id: Vec<u8>, psk_nonce: Vec<u8>) -> Self {
303 let psk = Psk::External(ExternalPsk::new(psk_id));
304
305 Self {
306 psk,
307 psk_nonce: psk_nonce.into(),
308 }
309 }
310
311 pub fn resumption(
313 usage: ResumptionPskUsage,
314 psk_group_id: GroupId,
315 psk_epoch: GroupEpoch,
316 psk_nonce: Vec<u8>,
317 ) -> Self {
318 let psk = Psk::Resumption(ResumptionPsk::new(usage, psk_group_id, psk_epoch));
319
320 Self {
321 psk,
322 psk_nonce: psk_nonce.into(),
323 }
324 }
325
326 #[cfg(feature = "extensions-draft")]
328 pub fn application(component_id: ComponentId, psk_id: Vec<u8>, psk_nonce: Vec<u8>) -> Self {
329 let psk = Psk::Application(ApplicationPsk::new(component_id, psk_id.into()));
330
331 Self {
332 psk,
333 psk_nonce: psk_nonce.into(),
334 }
335 }
336
337 pub fn psk(&self) -> &Psk {
339 &self.psk
340 }
341
342 pub fn psk_nonce(&self) -> &[u8] {
344 self.psk_nonce.as_slice()
345 }
346
347 #[openmls_traits::maybe_async]
353 pub async fn store<Provider: OpenMlsProvider>(
354 &self,
355 provider: &Provider,
356 psk: &[u8],
357 ) -> Result<(), PskError> {
358 let psk_bundle = {
359 let secret = Secret::from_slice(psk);
360
361 PskBundle { secret }
362 };
363
364 provider
365 .storage()
366 .write_psk(&self.psk, &psk_bundle)
367 .await
368 .map_err(|_| PskError::Storage)
369 }
370
371 pub(crate) fn validate_nonce(&self, ciphersuite: Ciphersuite) -> Result<(), PskError> {
378 let expected_nonce_length = ciphersuite.hash_length();
379 let got_nonce_length = self.psk_nonce().len();
380
381 if expected_nonce_length != got_nonce_length {
382 return Err(PskError::NonceLengthMismatch {
383 expected: expected_nonce_length,
384 got: got_nonce_length,
385 });
386 }
387 Ok(())
388 }
389
390 pub(crate) fn validate_in_welcome(
395 psk_ids: &[PreSharedKeyId],
396 ciphersuite: Ciphersuite,
397 ) -> Result<(), PskError> {
398 let mut contained_resumption_usage: Option<ResumptionPskUsage> = None;
399 for id in psk_ids {
400 id.validate_nonce(ciphersuite)?;
403
404 match id.psk() {
407 Psk::Resumption(resumption_psk) => match resumption_psk.usage {
408 ResumptionPskUsage::Application => {
409 return Err(PskError::UsageMismatch {
410 allowed: vec![ResumptionPskUsage::Reinit, ResumptionPskUsage::Branch],
411 got: resumption_psk.usage,
412 });
413 }
414 ResumptionPskUsage::Reinit | ResumptionPskUsage::Branch => {
415 if let Some(previous_usage) = contained_resumption_usage {
416 if previous_usage == resumption_psk.usage {
417 return Err(PskError::UsageDuplicate {
418 usage: previous_usage,
419 });
420 } else {
421 return Err(PskError::UsageConflict {
422 first: previous_usage,
423 second: resumption_psk.usage,
424 });
425 }
426 } else {
427 contained_resumption_usage = Some(resumption_psk.usage);
428 };
429 }
430 },
431 Psk::External(_) => {}
432 #[cfg(feature = "extensions-draft")]
433 Psk::Application(_) => {}
434 };
435 }
436 Ok(())
437 }
438}
439
440#[cfg(test)]
441impl PreSharedKeyId {
442 pub(crate) fn new_with_nonce(psk: Psk, psk_nonce: Vec<u8>) -> Self {
443 Self {
444 psk,
445 psk_nonce: psk_nonce.into(),
446 }
447 }
448}
449
450#[derive(TlsSerialize, TlsSize)]
462pub(crate) struct PskLabel<'a> {
463 pub(crate) id: &'a PreSharedKeyId,
464 pub(crate) index: u16,
465 pub(crate) count: u16,
466}
467
468impl<'a> PskLabel<'a> {
469 fn new(id: &'a PreSharedKeyId, index: u16, count: u16) -> Self {
471 Self { id, index, count }
472 }
473}
474
475#[derive(Clone)]
478pub struct PskSecret {
479 secret: Secret,
480}
481
482impl PskSecret {
483 pub(crate) fn new(
494 crypto: &impl OpenMlsCrypto,
495 ciphersuite: Ciphersuite,
496 psks: Vec<(impl Borrow<PreSharedKeyId>, Secret)>,
497 ) -> Result<Self, PskError> {
498 let num_psks = u16::try_from(psks.len()).map_err(|_| PskError::TooManyKeys)?;
500
501 let mut psk_secret = Secret::zero(ciphersuite);
505
506 for (index, (psk_id, psk)) in psks.into_iter().enumerate() {
507 let psk_extracted = {
509 let zero_secret = Secret::zero(ciphersuite);
510 zero_secret
511 .hkdf_extract(crypto, ciphersuite, &psk)
512 .map_err(LibraryError::unexpected_crypto_error)?
513 };
514
515 let psk_input = {
517 let psk_label = PskLabel::new(psk_id.borrow(), index as u16, num_psks)
518 .tls_serialize_detached()
519 .map_err(LibraryError::missing_bound_check)?;
520
521 psk_extracted
522 .kdf_expand_label(
523 crypto,
524 ciphersuite,
525 "derived psk",
526 &psk_label,
527 ciphersuite.hash_length(),
528 )
529 .map_err(LibraryError::unexpected_crypto_error)?
530 };
531
532 psk_secret = psk_input
534 .hkdf_extract(crypto, ciphersuite, &psk_secret)
535 .map_err(LibraryError::unexpected_crypto_error)?;
536 }
537
538 Ok(Self { secret: psk_secret })
539 }
540
541 pub(crate) fn secret(&self) -> &Secret {
543 &self.secret
544 }
545
546 #[cfg(any(feature = "test-utils", feature = "crypto-debug", test))]
547 pub(crate) fn as_slice(&self) -> &[u8] {
548 self.secret.as_slice()
549 }
550}
551
552#[cfg(any(feature = "test-utils", test))]
553impl From<Secret> for PskSecret {
554 fn from(secret: Secret) -> Self {
555 Self { secret }
556 }
557}
558
559#[openmls_traits::maybe_async]
570pub(crate) async fn load_psks<'p, Storage: StorageProvider>(
571 storage: &Storage,
572 resumption_psk_store: &ResumptionPskStore,
573 group_id: Option<&GroupId>,
574 foreign_resumption_psk: Option<(&PreSharedKeyId, ResumptionPskSecret)>,
575 psk_ids: &'p [PreSharedKeyId],
576) -> Result<Vec<(&'p PreSharedKeyId, Secret)>, PskError> {
577 let mut psk_bundles = Vec::new();
578 let mut foreign_resumption_psk = foreign_resumption_psk;
579
580 for psk_id in psk_ids.iter() {
581 log_crypto!(trace, "PSK store {:?}", resumption_psk_store);
582
583 match &psk_id.psk {
584 Psk::Resumption(resumption) => {
585 let psk_secret = match resumption.usage() {
586 ResumptionPskUsage::Application => {
588 let Some(group_id) = group_id else {
589 return Err(PskError::NotAllowed);
592 };
593 if &resumption.psk_group_id != group_id {
594 return Err(PskError::DifferentGroupId {
596 expected: group_id.clone(),
597 got: resumption.psk_group_id.clone(),
598 });
599 }
600 if let Some(psk_bundle) = resumption_psk_store.get(resumption.psk_epoch()) {
601 (psk_id, psk_bundle.secret.clone())
602 } else {
603 return Err(PskError::KeyNotFound);
605 }
606 }
607 ResumptionPskUsage::Branch | ResumptionPskUsage::Reinit => {
610 match foreign_resumption_psk.take() {
611 Some((foreign_psk_id, foreign_psk_secret))
612 if foreign_psk_id == psk_id =>
613 {
614 (psk_id, foreign_psk_secret.secret)
615 }
616 _ => return Err(PskError::KeyNotFound),
617 }
618 }
619 };
620 psk_bundles.push(psk_secret);
621 }
622 Psk::External(_) => {
623 let psk_bundle: Option<PskBundle> = storage
624 .psk(psk_id.psk())
625 .await
626 .map_err(|_| PskError::KeyNotFound)?;
627 if let Some(psk_bundle) = psk_bundle {
628 psk_bundles.push((psk_id, psk_bundle.secret));
629 } else {
630 return Err(PskError::KeyNotFound);
631 }
632 }
633 #[cfg(feature = "extensions-draft")]
634 Psk::Application(_) => {
635 let psk_bundle: Option<PskBundle> = storage
636 .psk(psk_id.psk())
637 .await
638 .map_err(|_| PskError::KeyNotFound)?;
639 if let Some(psk_bundle) = psk_bundle {
640 psk_bundles.push((psk_id, psk_bundle.secret));
641 } else {
642 return Err(PskError::KeyNotFound);
643 }
644 }
645 }
646 }
647
648 Ok(psk_bundles)
649}
650
651pub mod store {
653 use serde::{Deserialize, Serialize};
654
655 use crate::{group::GroupEpoch, schedule::ResumptionPskSecret};
656
657 #[derive(Debug, Serialize, Deserialize)]
661 #[cfg_attr(any(test, feature = "test-utils"), derive(Clone, PartialEq))]
662 pub(crate) struct ResumptionPskStore {
663 max_number_of_secrets: usize,
664 resumption_psk: Vec<(GroupEpoch, ResumptionPskSecret)>,
665 cursor: usize,
666 }
667
668 impl ResumptionPskStore {
669 pub(crate) fn new(max_number_of_secrets: usize) -> Self {
671 Self {
672 max_number_of_secrets,
673 resumption_psk: vec![],
674 cursor: 0,
675 }
676 }
677
678 pub(crate) fn add(&mut self, epoch: GroupEpoch, resumption_psk: ResumptionPskSecret) {
680 if self.max_number_of_secrets == 0 {
681 return;
682 }
683 let item = (epoch, resumption_psk);
684 if self.resumption_psk.len() < self.max_number_of_secrets {
685 self.resumption_psk.push(item);
686 self.cursor += 1;
687 } else {
688 self.cursor += 1;
689 self.cursor %= self.resumption_psk.len();
690 self.resumption_psk[self.cursor] = item;
691 }
692 }
693
694 pub(crate) fn get(&self, epoch: GroupEpoch) -> Option<&ResumptionPskSecret> {
697 self.resumption_psk
698 .iter()
699 .find(|&(e, _s)| e == &epoch)
700 .map(|(_e, s)| s)
701 }
702 }
703
704 #[cfg(test)]
705 impl ResumptionPskStore {
706 pub(crate) fn cursor(&self) -> usize {
707 self.cursor
708 }
709 }
710}