Skip to main content

bitwarden_crypto/safe/
symmetric_key_envelope.rs

1//! Wrapped symmetric key envelope for sealing a symmetric key with another symmetric key.
2
3use std::str::FromStr;
4
5use bitwarden_encoding::{B64, FromStrVisitor};
6use coset::{CborSerializable, CoseEncrypt0Builder, HeaderBuilder};
7use serde::{Deserialize, Serialize};
8use thiserror::Error;
9
10use crate::{
11    ContentFormat, EncodedSymmetricKey, KeySlotIds, KeyStoreContext,
12    cose::{
13        ContentNamespace, SafeObjectNamespace,
14        symmetric::{CoseAlgorithmPolicy, decrypt_cose0, encrypt_cose0},
15    },
16    keys::KeyId,
17    safe::{
18        DecodeSealedKeyError, KeyEncryptionKey, KeyEncryptionKeyError, decode_sealed_symmetric_key,
19        extract_key_id,
20        helpers::{debug_fmt, set_safe_namespaces, validate_safe_namespaces},
21        set_contained_key_id,
22    },
23};
24
25/// Errors that can occur when sealing or unsealing a symmetric key with envelope operations.
26#[derive(Debug, Error)]
27pub enum SymmetricKeyEnvelopeError {
28    /// The wrapping key provided is incorrect or the envelope was tampered with
29    #[error("Wrong key")]
30    WrongKey,
31    /// The envelope could not be parsed correctly
32    #[error("Parsing error {0}")]
33    Parsing(String),
34    /// There is no key for the provided key id in the key store
35    #[error("Key missing error")]
36    KeyMissing,
37    /// The key store could not be written to, for example due to being read-only
38    #[error("Could not write to key store")]
39    KeyStore,
40    /// A wrapping or contained key has an unsupported type
41    #[error("Wrong key type")]
42    WrongKeyType,
43    /// The symmetric key envelope namespace is invalid.
44    #[error("Invalid namespace")]
45    InvalidNamespace,
46}
47
48impl From<KeyEncryptionKeyError> for SymmetricKeyEnvelopeError {
49    fn from(error: KeyEncryptionKeyError) -> Self {
50        match error {
51            KeyEncryptionKeyError::Missing => SymmetricKeyEnvelopeError::KeyMissing,
52            KeyEncryptionKeyError::WrongKeyType => SymmetricKeyEnvelopeError::WrongKeyType,
53        }
54    }
55}
56
57/// A symmetric key protected by a [`KeyEncryptionKey`]: an XAES-256-GCM or AES-256-CBC-HMAC
58/// wrapping key.
59///
60/// To migrate a key stored as an [`EncString`](crate::EncString), see
61/// [`LegacyCompatSymmetricKeyEnvelope`](crate::compat::LegacyCompatSymmetricKeyEnvelope) and its
62/// migration example.
63#[derive(Clone)]
64pub struct SymmetricKeyEnvelope {
65    cose_encrypt0: coset::CoseEncrypt0,
66}
67
68impl SymmetricKeyEnvelope {
69    /// Seals a symmetric key with a [`KeyEncryptionKey`] from the key store.
70    pub fn seal<Ids: KeySlotIds>(
71        key_to_seal: Ids::Symmetric,
72        sealing_key: Ids::Symmetric,
73        namespace: SymmetricKeyEnvelopeNamespace,
74        ctx: &KeyStoreContext<Ids>,
75    ) -> Result<Self, SymmetricKeyEnvelopeError> {
76        // Get the keys from the key store.
77        let key_to_seal = ctx
78            .get_symmetric_key(key_to_seal)
79            .map_err(|_| SymmetricKeyEnvelopeError::KeyMissing)?;
80        let wrapping_key = KeyEncryptionKey::get_cose_key_view(ctx, sealing_key)?;
81
82        let (content_format, key_bytes) = match key_to_seal.to_encoded_raw() {
83            EncodedSymmetricKey::BitwardenLegacyKey(key_bytes) => {
84                (ContentFormat::BitwardenLegacyKey, key_bytes.to_vec())
85            }
86            EncodedSymmetricKey::CoseKey(key_bytes) => (ContentFormat::CoseKey, key_bytes.to_vec()),
87        };
88
89        let mut protected_header = HeaderBuilder::from(content_format).build();
90
91        set_contained_key_id(&mut protected_header, key_to_seal.key_id());
92
93        set_safe_namespaces(
94            &mut protected_header,
95            SafeObjectNamespace::SymmetricKeyEnvelope,
96            namespace,
97        );
98        protected_header.key_id = wrapping_key.key_id().as_slice().into();
99
100        let cose_encrypt0 = encrypt_cose0(
101            wrapping_key.algorithm(),
102            CoseEncrypt0Builder::new(),
103            protected_header,
104            &key_bytes,
105            wrapping_key.key_bytes(),
106        )
107        .map_err(|_| SymmetricKeyEnvelopeError::WrongKeyType)?;
108
109        Ok(SymmetricKeyEnvelope { cose_encrypt0 })
110    }
111
112    /// Unseals a symmetric key with a [`KeyEncryptionKey`] and stores it in the key store context.
113    pub fn unseal<Ids: KeySlotIds>(
114        &self,
115        wrapping_key: Ids::Symmetric,
116        namespace: SymmetricKeyEnvelopeNamespace,
117        ctx: &mut KeyStoreContext<Ids>,
118    ) -> Result<Ids::Symmetric, SymmetricKeyEnvelopeError> {
119        let wrapping_key = KeyEncryptionKey::get_cose_key_view(ctx, wrapping_key)?;
120
121        validate_safe_namespaces(
122            &self.cose_encrypt0.protected.header,
123            SafeObjectNamespace::SymmetricKeyEnvelope,
124            namespace,
125        )
126        .map_err(|_| SymmetricKeyEnvelopeError::InvalidNamespace)?;
127
128        // The wrapping key is independently typed, so require the protected content-encryption
129        // algorithm to match its algorithm before attempting decryption. This prevents an envelope
130        // sealed with one algorithm from being opened as another.
131        let key_bytes = decrypt_cose0(
132            &self.cose_encrypt0,
133            CoseAlgorithmPolicy::Exactly(wrapping_key.algorithm()),
134            wrapping_key.key_bytes(),
135        )
136        .map_err(|_| SymmetricKeyEnvelopeError::WrongKey)?;
137
138        let key = decode_sealed_symmetric_key(&self.cose_encrypt0.protected.header, key_bytes)
139            .map_err(|e| match e {
140                DecodeSealedKeyError::InvalidContentFormat => {
141                    SymmetricKeyEnvelopeError::Parsing("Invalid content format".to_string())
142                }
143                DecodeSealedKeyError::UnsupportedContentFormat
144                | DecodeSealedKeyError::InvalidKey => SymmetricKeyEnvelopeError::WrongKeyType,
145            })?;
146
147        Ok(ctx.add_local_symmetric_key(key))
148    }
149
150    /// Get the key ID of the contained key.
151    pub fn contained_key_id(&self) -> Result<Option<KeyId>, SymmetricKeyEnvelopeError> {
152        extract_key_id(&self.cose_encrypt0.protected.header)
153            .map_err(|_| SymmetricKeyEnvelopeError::Parsing("Invalid contained key id".to_string()))
154    }
155
156    /// Get the key ID of the key this envelope was sealed with. Always present in a well-formed
157    /// envelope.
158    pub fn encrypted_by_key_id(&self) -> Result<KeyId, SymmetricKeyEnvelopeError> {
159        KeyId::try_from(self.cose_encrypt0.protected.header.key_id.as_slice())
160            .map_err(|_| SymmetricKeyEnvelopeError::Parsing("Invalid sealing key id".to_string()))
161    }
162}
163
164impl From<&SymmetricKeyEnvelope> for Vec<u8> {
165    fn from(val: &SymmetricKeyEnvelope) -> Self {
166        val.cose_encrypt0
167            .clone()
168            .to_vec()
169            .expect("Serialization to cose should not fail")
170    }
171}
172
173impl TryFrom<&Vec<u8>> for SymmetricKeyEnvelope {
174    type Error = coset::CoseError;
175
176    fn try_from(value: &Vec<u8>) -> Result<Self, Self::Error> {
177        let cose_encrypt0 = coset::CoseEncrypt0::from_slice(value)?;
178        Ok(SymmetricKeyEnvelope { cose_encrypt0 })
179    }
180}
181
182impl std::fmt::Debug for SymmetricKeyEnvelope {
183    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
184        let mut s = f.debug_struct("SymmetricKeyEnvelope");
185
186        if !self.cose_encrypt0.protected.header.key_id.is_empty() {
187            s.field(
188                "sealing_key_id",
189                &self.cose_encrypt0.protected.header.key_id,
190            );
191        }
192
193        debug_fmt::<SymmetricKeyEnvelopeNamespace>(&mut s, &self.cose_encrypt0.protected.header);
194
195        if let Ok(Some(key_id)) = self.contained_key_id() {
196            s.field("contained_key_id", &key_id);
197        }
198
199        s.finish()
200    }
201}
202
203impl FromStr for SymmetricKeyEnvelope {
204    type Err = SymmetricKeyEnvelopeError;
205
206    fn from_str(s: &str) -> Result<Self, Self::Err> {
207        let data = B64::try_from(s).map_err(|_| {
208            SymmetricKeyEnvelopeError::Parsing(
209                "Invalid WrappedSymmetricKey Base64 encoding".to_string(),
210            )
211        })?;
212        Self::try_from(&data.into_bytes()).map_err(|_| {
213            SymmetricKeyEnvelopeError::Parsing("Failed to parse SymmetricKeyEnvelope".to_string())
214        })
215    }
216}
217
218impl From<SymmetricKeyEnvelope> for String {
219    fn from(val: SymmetricKeyEnvelope) -> Self {
220        let serialized: Vec<u8> = (&val).into();
221        B64::from(serialized).to_string()
222    }
223}
224
225impl<'de> Deserialize<'de> for SymmetricKeyEnvelope {
226    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
227    where
228        D: serde::Deserializer<'de>,
229    {
230        deserializer.deserialize_str(FromStrVisitor::new())
231    }
232}
233
234impl Serialize for SymmetricKeyEnvelope {
235    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
236    where
237        S: serde::Serializer,
238    {
239        let serialized: Vec<u8> = self.into();
240        serializer.serialize_str(&B64::from(serialized).to_string())
241    }
242}
243
244#[cfg(feature = "wasm")]
245#[wasm_bindgen::prelude::wasm_bindgen(typescript_custom_section)]
246const TS_CUSTOM_TYPES: &'static str = r#"
247export type SymmetricKeyEnvelope = Tagged<string, "SymmetricKeyEnvelope">;
248"#;
249
250bitwarden_ffi::impl_wire_string!(SymmetricKeyEnvelope, parse = |wire: String| wire.parse());
251
252/// Content namespace for the symmetric key envelope
253#[allow(clippy::enum_variant_names)]
254#[derive(Debug, Copy, Clone, PartialEq)]
255pub enum SymmetricKeyEnvelopeNamespace {
256    /// A key used for re-hydration of the SDK
257    SessionKey = 1,
258    /// Organization member invites. Used to seal the invite-data content-encryption key and the
259    /// organization key with the invite key.
260    OrganizationInvite = 2,
261    #[cfg(test)]
262    /// Example namespace for testing purposes.
263    ExampleNamespace = -3,
264    #[cfg(test)]
265    /// Another example namespace for testing purposes.
266    ExampleNamespace2 = -4,
267}
268
269impl SymmetricKeyEnvelopeNamespace {
270    /// Returns the numeric value of the namespace.
271    pub fn as_i64(&self) -> i64 {
272        *self as i64
273    }
274}
275
276impl TryFrom<i128> for SymmetricKeyEnvelopeNamespace {
277    type Error = SymmetricKeyEnvelopeError;
278
279    fn try_from(value: i128) -> Result<Self, Self::Error> {
280        match value {
281            1 => Ok(SymmetricKeyEnvelopeNamespace::SessionKey),
282            2 => Ok(SymmetricKeyEnvelopeNamespace::OrganizationInvite),
283            #[cfg(test)]
284            -3 => Ok(SymmetricKeyEnvelopeNamespace::ExampleNamespace),
285            #[cfg(test)]
286            -4 => Ok(SymmetricKeyEnvelopeNamespace::ExampleNamespace2),
287            _ => Err(SymmetricKeyEnvelopeError::InvalidNamespace),
288        }
289    }
290}
291
292impl TryFrom<i64> for SymmetricKeyEnvelopeNamespace {
293    type Error = SymmetricKeyEnvelopeError;
294
295    fn try_from(value: i64) -> Result<Self, Self::Error> {
296        Self::try_from(i128::from(value))
297    }
298}
299
300impl From<SymmetricKeyEnvelopeNamespace> for i128 {
301    fn from(value: SymmetricKeyEnvelopeNamespace) -> Self {
302        value.as_i64().into()
303    }
304}
305
306impl ContentNamespace for SymmetricKeyEnvelopeNamespace {}
307
308#[cfg(test)]
309mod tests {
310    use super::*;
311    use crate::{
312        KeyStore, SymmetricCryptoKey, SymmetricKeyAlgorithm,
313        cose::{AES_256_CBC_HMAC_SHA256_AEAD, XAES_256_GCM},
314        traits::tests::{TestIds, TestSymmKey},
315    };
316
317    const TEST_VECTOR_XAES256_GCM_SEALING_KEY: &str = "pQEEAlAJiRm3TVKQVUpm9gqA4tm6AzoAARF5BIQDBAUGIFggQyO5bN7Uto3hpXUyqluuArn+zppBmhdnahDRJ6p4s84B";
318    const TEST_VECTOR_XAES256_GCM_KEY_TO_SEAL: &str = "pQEEAlDpQoswNPD5xaz7sYLHZXXXAzoAARFvBIQDBAUGIFgg2YO7eUZhb9WSxxsGvdURTunDOBV0W4FRk9E4TV7c00QB";
319    const TEST_VECTOR_XAES256_GCM_ENVELOPE: &str = "g1g+pgE6AAEReQMYZQRQCYkZt01SkFVKZvYKgOLZujoAARVcUOlCizA08PnFrPuxgsdlddc6AAE4gQM6AAE4gCKhBVgYLLX2iYq+Ko+2Hp2fByDfGd5AC0Lw4+zxWFS9n8fBbBKHfiarETj6Q3uRwZYpDS5p29MBEJW7WxOaf5Az51+Qtr8ugnoocUJhb8l6vmkDxFy1blU6iHuoBvpd+3MSFOeCdiuMLbKrf469fmUlDn0=";
320
321    const TEST_VECTOR_AES256_CBC_HMAC_SEALING_KEY: &str =
322        "Im4/NyElI5SFvB8AVPN3Gpc18YMzAM1K0sIFigkoSQdpLnOUbm4DRhOK0n8WRdcZAsEpzVHKp5o3no9PQBYRnQ==";
323    const TEST_VECTOR_AES256_CBC_HMAC_KEY_TO_SEAL: &str =
324        "ikiXBX+XX73bEzUvrCMazkXDGokzRKGMVxCQmcss4CvEbt0BH7l17EtGVk076s7KUFpG3ddh4s7ft4Zjdp1IZQ==";
325    const TEST_VECTOR_AES256_CBC_HMAC_ENVELOPE: &str = "g1hgpgE6AAERegN4ImFwcGxpY2F0aW9uL3guYml0d2FyZGVuLmxlZ2FjeS1rZXkEUCXt6Q6vGxzVz4yiWQaeIVU6AAEVXFAHW3SH5xZ6K2Rbzk++yRd8OgABOIEDOgABOIAioQVQFoZH08X+KUh2fG9r/3KTAVhwEpdWDKgAXIDyqxsGOJwBGmM2wFc1qCeZMkSjHhNRyQ4b/JClrplC66Vb9TjNLmXVDyDSlvpGYmRIS2e3Hqfg4/fRjNp/8QEmNEddLIZNatT/tpM8AyYfaGSpaz/y3SmiUryPBy2L3cpeNC05vE14tA==";
326
327    /// An envelope pinned as a test vector, the keys it was sealed from, and how to generate it.
328    struct TestVector {
329        /// Used in the generated constant names and in assertion messages.
330        name: &'static str,
331        sealing_key_algorithm: SymmetricKeyAlgorithm,
332        key_to_seal_algorithm: SymmetricKeyAlgorithm,
333        cose_algorithm: coset::Algorithm,
334        sealing_key: &'static str,
335        key_to_seal: &'static str,
336        envelope: &'static str,
337    }
338
339    /// Together, the vectors cover both wrapping key algorithms and both encodings of the sealed
340    /// key: a COSE-encoded key (XChaCha20-Poly1305) and an AES-256-CBC-HMAC key, which uses the
341    /// legacy (non-COSE) encoding.
342    const TEST_VECTORS: [TestVector; 2] = [
343        TestVector {
344            name: "XAES256_GCM",
345            sealing_key_algorithm: SymmetricKeyAlgorithm::XAes256Gcm,
346            key_to_seal_algorithm: SymmetricKeyAlgorithm::XChaCha20Poly1305,
347            cose_algorithm: coset::Algorithm::PrivateUse(XAES_256_GCM),
348            sealing_key: TEST_VECTOR_XAES256_GCM_SEALING_KEY,
349            key_to_seal: TEST_VECTOR_XAES256_GCM_KEY_TO_SEAL,
350            envelope: TEST_VECTOR_XAES256_GCM_ENVELOPE,
351        },
352        TestVector {
353            name: "AES256_CBC_HMAC",
354            sealing_key_algorithm: SymmetricKeyAlgorithm::Aes256CbcHmac,
355            key_to_seal_algorithm: SymmetricKeyAlgorithm::Aes256CbcHmac,
356            cose_algorithm: coset::Algorithm::PrivateUse(AES_256_CBC_HMAC_SHA256_AEAD),
357            sealing_key: TEST_VECTOR_AES256_CBC_HMAC_SEALING_KEY,
358            key_to_seal: TEST_VECTOR_AES256_CBC_HMAC_KEY_TO_SEAL,
359            envelope: TEST_VECTOR_AES256_CBC_HMAC_ENVELOPE,
360        },
361    ];
362
363    /// The supported wrapping key algorithms, each paired with the COSE algorithm that an envelope
364    /// sealed with such a key declares in its protected header.
365    fn wrapping_key_algorithms() -> [(SymmetricKeyAlgorithm, coset::Algorithm); 2] {
366        [
367            (
368                SymmetricKeyAlgorithm::XAes256Gcm,
369                coset::Algorithm::PrivateUse(XAES_256_GCM),
370            ),
371            (
372                SymmetricKeyAlgorithm::Aes256CbcHmac,
373                coset::Algorithm::PrivateUse(AES_256_CBC_HMAC_SHA256_AEAD),
374            ),
375        ]
376    }
377
378    #[test]
379    #[ignore = "Manual test to verify debug format"]
380    fn test_debug() {
381        let key_store = KeyStore::<TestIds>::default();
382        let mut ctx = key_store.context_mut();
383        let key1 = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
384        let key2 = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
385
386        let envelope = SymmetricKeyEnvelope::seal(
387            key1,
388            key2,
389            SymmetricKeyEnvelopeNamespace::ExampleNamespace,
390            &ctx,
391        );
392        println!("{:?}", envelope);
393    }
394
395    #[test]
396    fn test_seal_unseal_symmetric() {
397        let key_store = KeyStore::<TestIds>::default();
398        let mut ctx = key_store.context_mut();
399
400        for (wrapping_key_algorithm, cose_algorithm) in wrapping_key_algorithms() {
401            // AES-256-CBC-HMAC keys use the legacy (non-COSE) encoding, so they are sealed with a
402            // different content format than the COSE-encoded key types.
403            for key_to_seal_algorithm in [
404                SymmetricKeyAlgorithm::Aes256CbcHmac,
405                SymmetricKeyAlgorithm::XChaCha20Poly1305,
406                SymmetricKeyAlgorithm::Aes256Gcm,
407                SymmetricKeyAlgorithm::XAes256Gcm,
408            ] {
409                let key_to_seal = ctx.make_symmetric_key(key_to_seal_algorithm);
410                let wrapping_key = ctx.make_symmetric_key(wrapping_key_algorithm);
411
412                let envelope = SymmetricKeyEnvelope::seal(
413                    key_to_seal,
414                    wrapping_key,
415                    SymmetricKeyEnvelopeNamespace::ExampleNamespace,
416                    &ctx,
417                )
418                .unwrap();
419
420                assert_eq!(
421                    envelope.cose_encrypt0.protected.header.alg.as_ref(),
422                    Some(&cose_algorithm),
423                    "{wrapping_key_algorithm:?} sealing {key_to_seal_algorithm:?}"
424                );
425
426                let unsealed_key = envelope
427                    .unseal(
428                        wrapping_key,
429                        SymmetricKeyEnvelopeNamespace::ExampleNamespace,
430                        &mut ctx,
431                    )
432                    .unwrap();
433
434                ctx.assert_symmetric_keys_equal(unsealed_key, key_to_seal);
435            }
436        }
437    }
438
439    #[test]
440    fn test_key_ids_symmetric() {
441        let key_store = KeyStore::<TestIds>::default();
442        let mut ctx = key_store.context_mut();
443
444        for (wrapping_key_algorithm, _) in wrapping_key_algorithms() {
445            let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
446            let wrapping_key = ctx.make_symmetric_key(wrapping_key_algorithm);
447
448            let envelope = SymmetricKeyEnvelope::seal(
449                key_to_seal,
450                wrapping_key,
451                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
452                &ctx,
453            )
454            .unwrap();
455
456            let key_to_seal_ref = ctx
457                .get_symmetric_key(key_to_seal)
458                .expect("Key should exist in the key store");
459            assert_eq!(
460                key_to_seal_ref.key_id(),
461                envelope.contained_key_id().unwrap(),
462                "{wrapping_key_algorithm:?}"
463            );
464
465            // An AES-256-CBC-HMAC key doesn't store a key ID, so `seal` has to write the ID derived
466            // from the key material.
467            let wrapping_key_id = ctx
468                .get_symmetric_key(wrapping_key)
469                .expect("Key should exist in the key store")
470                .key_id()
471                .expect("Wrapping keys have a key ID");
472            assert_eq!(
473                envelope.cose_encrypt0.protected.header.key_id,
474                wrapping_key_id.as_slice(),
475                "{wrapping_key_algorithm:?}"
476            );
477            assert_eq!(
478                envelope.encrypted_by_key_id().unwrap(),
479                wrapping_key_id,
480                "{wrapping_key_algorithm:?}"
481            );
482        }
483    }
484
485    #[test]
486    fn test_string_serialization() {
487        let key_store = KeyStore::<TestIds>::default();
488        let mut ctx = key_store.context_mut();
489
490        let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
491        let wrapping_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
492
493        let envelope = SymmetricKeyEnvelope::seal(
494            key_to_seal,
495            wrapping_key,
496            SymmetricKeyEnvelopeNamespace::ExampleNamespace,
497            &ctx,
498        )
499        .unwrap();
500
501        let serialized: String = envelope.into();
502        let deserialized = SymmetricKeyEnvelope::from_str(&serialized).unwrap();
503
504        let unsealed_key = deserialized
505            .unseal(
506                wrapping_key,
507                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
508                &mut ctx,
509            )
510            .unwrap();
511
512        let unsealed_key_ref = ctx
513            .get_symmetric_key(unsealed_key)
514            .expect("Key should exist in the key store");
515
516        let original_key_ref = ctx
517            .get_symmetric_key(key_to_seal)
518            .expect("Key should exist in the key store");
519
520        assert_eq!(unsealed_key_ref, original_key_ref);
521    }
522
523    #[test]
524    fn test_wrong_key() {
525        let key_store = KeyStore::<TestIds>::default();
526        let mut ctx = key_store.context_mut();
527
528        for (wrapping_key_algorithm, _) in wrapping_key_algorithms() {
529            let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
530            let wrapping_key = ctx.make_symmetric_key(wrapping_key_algorithm);
531            let wrong_key = ctx.make_symmetric_key(wrapping_key_algorithm);
532
533            let envelope = SymmetricKeyEnvelope::seal(
534                key_to_seal,
535                wrapping_key,
536                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
537                &ctx,
538            )
539            .unwrap();
540
541            assert!(
542                matches!(
543                    envelope.unseal(
544                        wrong_key,
545                        SymmetricKeyEnvelopeNamespace::ExampleNamespace,
546                        &mut ctx
547                    ),
548                    Err(SymmetricKeyEnvelopeError::WrongKey)
549                ),
550                "{wrapping_key_algorithm:?}"
551            );
552        }
553    }
554
555    #[test]
556    fn test_rejects_unsupported_wrapping_keys() {
557        let key_store = KeyStore::<TestIds>::default();
558        let mut ctx = key_store.context_mut();
559
560        let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
561        let wrapping_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
562        let envelope = SymmetricKeyEnvelope::seal(
563            key_to_seal,
564            wrapping_key,
565            SymmetricKeyEnvelopeNamespace::ExampleNamespace,
566            &ctx,
567        )
568        .unwrap();
569
570        let unsupported_wrapping_keys = [
571            ctx.make_symmetric_key(SymmetricKeyAlgorithm::Aes256Gcm),
572            ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305),
573        ];
574
575        for unsupported_wrapping_key in unsupported_wrapping_keys {
576            assert!(matches!(
577                SymmetricKeyEnvelope::seal(
578                    key_to_seal,
579                    unsupported_wrapping_key,
580                    SymmetricKeyEnvelopeNamespace::ExampleNamespace,
581                    &ctx,
582                ),
583                Err(SymmetricKeyEnvelopeError::WrongKeyType)
584            ));
585            // Without the key type check, `unseal` would attempt decryption and fail with
586            // `WrongKey` instead.
587            assert!(matches!(
588                envelope.unseal(
589                    unsupported_wrapping_key,
590                    SymmetricKeyEnvelopeNamespace::ExampleNamespace,
591                    &mut ctx,
592                ),
593                Err(SymmetricKeyEnvelopeError::WrongKeyType)
594            ));
595        }
596    }
597
598    #[test]
599    fn test_wrong_namespace() {
600        let key_store = KeyStore::<TestIds>::default();
601        let mut ctx = key_store.context_mut();
602
603        let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
604        let wrapping_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
605
606        let envelope = SymmetricKeyEnvelope::seal(
607            key_to_seal,
608            wrapping_key,
609            SymmetricKeyEnvelopeNamespace::ExampleNamespace,
610            &ctx,
611        )
612        .unwrap();
613
614        assert!(matches!(
615            envelope.unseal(
616                wrapping_key,
617                SymmetricKeyEnvelopeNamespace::ExampleNamespace2,
618                &mut ctx
619            ),
620            Err(SymmetricKeyEnvelopeError::InvalidNamespace)
621        ));
622    }
623
624    #[test]
625    fn test_seal_missing_wrapping_key() {
626        let key_store = KeyStore::<TestIds>::default();
627        let mut ctx = key_store.context_mut();
628
629        let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
630        let missing_key = TestSymmKey::A(0);
631
632        assert!(matches!(
633            SymmetricKeyEnvelope::seal(
634                key_to_seal,
635                missing_key,
636                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
637                &ctx,
638            ),
639            Err(SymmetricKeyEnvelopeError::KeyMissing)
640        ));
641    }
642
643    #[test]
644    fn test_unseal_missing_wrapping_key() {
645        let key_store = KeyStore::<TestIds>::default();
646        let mut ctx = key_store.context_mut();
647
648        let key_to_seal = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XChaCha20Poly1305);
649        let wrapping_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
650        let envelope = SymmetricKeyEnvelope::seal(
651            key_to_seal,
652            wrapping_key,
653            SymmetricKeyEnvelopeNamespace::ExampleNamespace,
654            &ctx,
655        )
656        .unwrap();
657
658        let missing_key = TestSymmKey::A(0);
659
660        assert!(matches!(
661            envelope.unseal(
662                missing_key,
663                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
664                &mut ctx,
665            ),
666            Err(SymmetricKeyEnvelopeError::KeyMissing)
667        ));
668    }
669
670    #[test]
671    #[ignore = "Generates test vectors; run manually"]
672    fn generate_test_vectors() {
673        let key_store = KeyStore::<TestIds>::default();
674        let mut ctx = key_store.context_mut();
675
676        for vector in TEST_VECTORS {
677            let key_to_seal = ctx.make_symmetric_key(vector.key_to_seal_algorithm);
678            let wrapping_key = ctx.make_symmetric_key(vector.sealing_key_algorithm);
679
680            let envelope = SymmetricKeyEnvelope::seal(
681                key_to_seal,
682                wrapping_key,
683                SymmetricKeyEnvelopeNamespace::ExampleNamespace,
684                &ctx,
685            )
686            .unwrap();
687
688            for (key_name, key) in [("SEALING_KEY", wrapping_key), ("KEY_TO_SEAL", key_to_seal)] {
689                println!(
690                    "const TEST_VECTOR_{}_{key_name}: &str = \"{}\";",
691                    vector.name,
692                    B64::from(
693                        ctx.get_symmetric_key(key)
694                            .unwrap()
695                            .to_encoded()
696                            .to_vec()
697                            .as_slice()
698                    )
699                );
700            }
701            let serialized: String = envelope.into();
702            println!(
703                "const TEST_VECTOR_{}_ENVELOPE: &str = \"{serialized}\";",
704                vector.name
705            );
706        }
707    }
708
709    #[test]
710    fn decrypt_test_vectors() {
711        let key_store = KeyStore::<TestIds>::default();
712        let mut ctx = key_store.context_mut();
713
714        for vector in TEST_VECTORS {
715            let sealing_key = ctx.add_local_symmetric_key(
716                SymmetricCryptoKey::try_from(vector.sealing_key.to_string())
717                    .expect("Failed to parse sealing key from test vector"),
718            );
719            let key_to_seal_test_vector = ctx.add_local_symmetric_key(
720                SymmetricCryptoKey::try_from(vector.key_to_seal.to_string())
721                    .expect("Failed to parse key to seal from test vector"),
722            );
723            assert_eq!(
724                ctx.get_symmetric_key_algorithm(sealing_key).unwrap(),
725                vector.sealing_key_algorithm,
726                "{}",
727                vector.name
728            );
729            assert_eq!(
730                ctx.get_symmetric_key_algorithm(key_to_seal_test_vector)
731                    .unwrap(),
732                vector.key_to_seal_algorithm,
733                "{}",
734                vector.name
735            );
736
737            let envelope = SymmetricKeyEnvelope::from_str(vector.envelope).unwrap();
738
739            // Pin the header fields that consumers rely on: the algorithm, the ID used to look up
740            // the sealing key, and the ID of the contained key.
741            let header = &envelope.cose_encrypt0.protected.header;
742            assert_eq!(
743                header.alg.as_ref(),
744                Some(&vector.cose_algorithm),
745                "{}",
746                vector.name
747            );
748            assert_eq!(
749                header.key_id,
750                ctx.get_symmetric_key(sealing_key)
751                    .unwrap()
752                    .key_id()
753                    .expect("Sealing keys have a key ID")
754                    .as_slice(),
755                "{}",
756                vector.name
757            );
758            assert_eq!(
759                envelope.contained_key_id().unwrap(),
760                ctx.get_symmetric_key(key_to_seal_test_vector)
761                    .unwrap()
762                    .key_id(),
763                "{}",
764                vector.name
765            );
766
767            let unsealed_key = envelope
768                .unseal(
769                    sealing_key,
770                    SymmetricKeyEnvelopeNamespace::ExampleNamespace,
771                    &mut ctx,
772                )
773                .unwrap();
774            ctx.assert_symmetric_keys_equal(unsealed_key, key_to_seal_test_vector);
775        }
776    }
777}