[PM-26459] Implement data envelope

crates/bitwarden-crypto/examples/seal_struct.rs

@@ -0,0 +1,96 @@
+//! This example demonstrates how to seal a piece of data.
+//!
+//! If there is a struct that should be kept secret, in can be sealed with a `DataEnvelope`. This
+//! will automatically create a content-encryption-key. This is useful because the key is stored
+//! separately. Rotating the encrypting key now only requires re-uploading the
+//! content-encryption-key instead of the entire data. Further, server-side tampering (swapping of
+//! individual fields encrypted by the same key) is prevented.
+//!
+//! In general, if a struct of data should be protected, the `DataEnvelope` should be used.
+
+use bitwarden_crypto::{key_ids, safe::SealableData};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+struct MyItem {
+    a: u64,
+    b: String,
+}
+impl SealableData for MyItem {}
+
+fn main() {
+    let store = bitwarden_crypto::KeyStore::<ExampleIds>::default();
+    let mut ctx: bitwarden_crypto::KeyStoreContext<'_, ExampleIds> = store.context_mut();
+    let mut disk = MockDisk::new();
+
+    let my_item = MyItem {
+        a: 42,
+        b: "Hello, World!".to_string(),
+    };
+    // Seal the item into an encrypted blob, and store the content-encryption-key in the context.
+    let sealed_item = bitwarden_crypto::safe::DataEnvelope::seal(
+        my_item,
+        &bitwarden_crypto::safe::DataEnvelopeNamespace::VaultItem,
+        ExampleSymmetricKey::ItemKey,
+        &mut ctx,
+    )
+    .expect("Sealing should work");
+
+    // Store the sealed item on disk
+    disk.save("sealed_item", (&sealed_item).into());
+    let sealed_item = disk
+        .load("sealed_item")
+        .expect("Failed to load sealed item")
+        .clone();
+    let sealed_item: bitwarden_crypto::safe::DataEnvelope =
+        bitwarden_crypto::safe::DataEnvelope::from(sealed_item);
+
+    let my_item: MyItem = sealed_item
+        .unseal(
+            &bitwarden_crypto::safe::DataEnvelopeNamespace::VaultItem,
+            ExampleSymmetricKey::ItemKey,
+            &mut ctx,
+        )
+        .expect("Unsealing should work");
+    assert!(my_item.a == 42);
+    assert!(my_item.b == "Hello, World!");
+}
+
+pub(crate) struct MockDisk {
+    map: std::collections::HashMap<String, Vec<u8>>,
+}
+
+impl MockDisk {
+    pub(crate) fn new() -> Self {
+        MockDisk {
+            map: std::collections::HashMap::new(),
+        }
+    }
+
+    pub(crate) fn save(&mut self, key: &str, value: Vec<u8>) {
+        self.map.insert(key.to_string(), value);
+    }
+
+    pub(crate) fn load(&self, key: &str) -> Option<&Vec<u8>> {
+        self.map.get(key)
+    }
+}
+
+key_ids! {
+    #[symmetric]
+    pub enum ExampleSymmetricKey {
+        #[local]
+        ItemKey
+    }
+
+    #[asymmetric]
+    pub enum ExampleAsymmetricKey {
+        Key(u8),
+    }
+
+    #[signing]
+    pub enum ExampleSigningKey {
+        Key(u8),
+    }
+    pub ExampleIds => ExampleSymmetricKey, ExampleAsymmetricKey, ExampleSigningKey;
+}

crates/bitwarden-crypto/src/content_format.rs

@@ -24,6 +24,8 @@ pub(crate) enum ContentFormat {
     CoseKey,
     /// CoseSign1 message
     CoseSign1,
+    /// CoseEncrypt0 message
+    CoseEncrypt0,
     /// Bitwarden Legacy Key
     /// There are three permissible byte values here:
     /// - `[u8; 32]` - AES-CBC (no hmac) key. This is to be removed and banned.
@@ -32,6 +34,8 @@ pub(crate) enum ContentFormat {
     BitwardenLegacyKey,
     /// Stream of bytes
     OctetStream,
+    /// Cbor serialized data
+    Cbor,
 }
 
 mod private {
@@ -210,6 +214,34 @@ impl FromB64ContentFormat for CoseSign1ContentFormat {}
 /// serialized COSE Sign1 messages.
 pub type CoseSign1Bytes = Bytes<CoseSign1ContentFormat>;
 
+/// CBOR serialized data
+#[derive(PartialEq, Eq, Clone, Debug)]
+pub struct CborContentFormat;
+impl private::Sealed for CborContentFormat {}
+impl ConstContentFormat for CborContentFormat {
+    #[allow(private_interfaces)]
+    fn content_format() -> ContentFormat {
+        ContentFormat::Cbor
+    }
+}
+/// CborBytes is a type alias for Bytes with `CborContentFormat`. This is used for CBOR serialized
+/// data.
+pub type CborBytes = Bytes<CborContentFormat>;
+
+/// Content format for COSE Encrypt0 messages.
+#[derive(PartialEq, Eq, Clone, Debug)]
+pub struct CoseEncrypt0ContentFormat;
+impl private::Sealed for CoseEncrypt0ContentFormat {}
+impl ConstContentFormat for CoseEncrypt0ContentFormat {
+    #[allow(private_interfaces)]
+    fn content_format() -> ContentFormat {
+        ContentFormat::CoseEncrypt0
+    }
+}
+/// CoseEncrypt0Bytes is a type alias for Bytes with `CoseEncrypt0ContentFormat`. This is used for
+/// serialized COSE Encrypt0 messages.
+pub type CoseEncrypt0Bytes = Bytes<CoseEncrypt0ContentFormat>;
+
 impl<Ids: KeyIds, T: ConstContentFormat> PrimitiveEncryptable<Ids, Ids::Symmetric, EncString>
     for Bytes<T>
 {

crates/bitwarden-crypto/src/cose.rs

@@ -12,7 +12,7 @@ use thiserror::Error;
 use typenum::U32;
 
 use crate::{
-    ContentFormat, CryptoError, SymmetricCryptoKey, XChaCha20Poly1305Key,
+    ContentFormat, CoseEncrypt0Bytes, CryptoError, SymmetricCryptoKey, XChaCha20Poly1305Key,
     content_format::{Bytes, ConstContentFormat, CoseContentFormat},
     error::{EncStringParseError, EncodingError},
     xchacha20,
@@ -40,13 +40,15 @@ const CONTENT_TYPE_SPKI_PUBLIC_KEY: &str = "application/x.bitwarden.spki-public-
 //
 /// The label used for the namespace ensuring strong domain separation when using signatures.
 pub(crate) const SIGNING_NAMESPACE: i64 = -80000;
+/// The label used for the namespace ensuring strong domain separation when using data envelopes.
+pub(crate) const DATA_ENVELOPE_NAMESPACE: i64 = -80001;
 
 /// Encrypts a plaintext message using XChaCha20Poly1305 and returns a COSE Encrypt0 message
 pub(crate) fn encrypt_xchacha20_poly1305(
     plaintext: &[u8],
     key: &crate::XChaCha20Poly1305Key,
     content_format: ContentFormat,
-) -> Result<Vec<u8>, CryptoError> {
+) -> Result<CoseEncrypt0Bytes, CryptoError> {
     let mut plaintext = plaintext.to_vec();
 
     let header_builder: coset::HeaderBuilder = content_format.into();
@@ -78,14 +80,15 @@ pub(crate) fn encrypt_xchacha20_poly1305(
     cose_encrypt0
         .to_vec()
         .map_err(|err| CryptoError::EncString(EncStringParseError::InvalidCoseEncoding(err)))
+        .map(CoseEncrypt0Bytes::from)
 }
 
 /// Decrypts a COSE Encrypt0 message, using a XChaCha20Poly1305 key
 pub(crate) fn decrypt_xchacha20_poly1305(
-    cose_encrypt0_message: &[u8],
+    cose_encrypt0_message: &CoseEncrypt0Bytes,
     key: &crate::XChaCha20Poly1305Key,
 ) -> Result<(Vec<u8>, ContentFormat), CryptoError> {
-    let msg = coset::CoseEncrypt0::from_slice(cose_encrypt0_message)
+    let msg = coset::CoseEncrypt0::from_slice(cose_encrypt0_message.as_ref())
         .map_err(|err| CryptoError::EncString(EncStringParseError::InvalidCoseEncoding(err)))?;
 
     let Some(ref alg) = msg.protected.header.alg else {
@@ -180,12 +183,16 @@ impl From<ContentFormat> for coset::HeaderBuilder {
             }
             ContentFormat::CoseSign1 => header_builder.content_format(CoapContentFormat::CoseSign1),
             ContentFormat::CoseKey => header_builder.content_format(CoapContentFormat::CoseKey),
+            ContentFormat::CoseEncrypt0 => {
+                header_builder.content_format(CoapContentFormat::CoseEncrypt0)
+            }
             ContentFormat::BitwardenLegacyKey => {
                 header_builder.content_type(CONTENT_TYPE_BITWARDEN_LEGACY_KEY.to_string())
             }
             ContentFormat::OctetStream => {
                 header_builder.content_format(CoapContentFormat::OctetStream)
             }
+            ContentFormat::Cbor => header_builder.content_format(CoapContentFormat::Cbor),
         }
     }
 }
@@ -211,6 +218,7 @@ impl TryFrom<&coset::Header> for ContentFormat {
             Some(ContentType::Assigned(CoapContentFormat::OctetStream)) => {
                 Ok(ContentFormat::OctetStream)
             }
+            Some(ContentType::Assigned(CoapContentFormat::Cbor)) => Ok(ContentFormat::Cbor),
             _ => Err(CryptoError::EncString(
                 EncStringParseError::CoseMissingContentType,
             )),
@@ -363,7 +371,9 @@ mod test {
             key_id: KEY_ID,
             enc_key: Box::pin(*GenericArray::from_slice(&KEY_DATA)),
         };
-        let decrypted = decrypt_xchacha20_poly1305(TEST_VECTOR_COSE_ENCRYPT0, &key).unwrap();
+        let decrypted =
+            decrypt_xchacha20_poly1305(&CoseEncrypt0Bytes::from(TEST_VECTOR_COSE_ENCRYPT0), &key)
+                .unwrap();
         assert_eq!(
             decrypted,
             (TEST_VECTOR_PLAINTEXT.to_vec(), ContentFormat::OctetStream)
@@ -377,7 +387,7 @@ mod test {
             enc_key: Box::pin(*GenericArray::from_slice(&KEY_DATA)),
         };
         assert!(matches!(
-            decrypt_xchacha20_poly1305(TEST_VECTOR_COSE_ENCRYPT0, &key),
+            decrypt_xchacha20_poly1305(&CoseEncrypt0Bytes::from(TEST_VECTOR_COSE_ENCRYPT0), &key),
             Err(CryptoError::WrongCoseKeyId)
         ));
     }
@@ -394,7 +404,7 @@ mod test {
             .create_ciphertext(&[], &[], |_, _| Vec::new())
             .unprotected(coset::HeaderBuilder::new().iv(nonce.to_vec()).build())
             .build();
-        let serialized_message = cose_encrypt0.to_vec().unwrap();
+        let serialized_message = CoseEncrypt0Bytes::from(cose_encrypt0.to_vec().unwrap());
 
         let key = XChaCha20Poly1305Key {
             key_id: KEY_ID,

crates/bitwarden-crypto/src/enc_string/symmetric.rs

@@ -6,8 +6,8 @@ use serde::Deserialize;
 
 use super::{check_length, from_b64, from_b64_vec, split_enc_string};
 use crate::{
-    Aes256CbcHmacKey, ContentFormat, KeyDecryptable, KeyEncryptable, KeyEncryptableWithContentType,
-    SymmetricCryptoKey, Utf8Bytes, XChaCha20Poly1305Key,
+    Aes256CbcHmacKey, ContentFormat, CoseEncrypt0Bytes, KeyDecryptable, KeyEncryptable,
+    KeyEncryptableWithContentType, SymmetricCryptoKey, Utf8Bytes, XChaCha20Poly1305Key,
     error::{CryptoError, EncStringParseError, Result, UnsupportedOperationError},
 };
 
@@ -269,7 +269,9 @@ impl EncString {
         content_format: ContentFormat,
     ) -> Result<EncString> {
         let data = crate::cose::encrypt_xchacha20_poly1305(data_dec, key, content_format)?;
-        Ok(EncString::Cose_Encrypt0_B64 { data })
+        Ok(EncString::Cose_Encrypt0_B64 {
+            data: data.to_vec(),
+        })
     }
 
     /// The numerical representation of the encryption type of the [EncString].
@@ -314,8 +316,10 @@ impl KeyDecryptable<SymmetricCryptoKey, Vec<u8>> for EncString {
                 EncString::Cose_Encrypt0_B64 { data },
                 SymmetricCryptoKey::XChaCha20Poly1305Key(key),
             ) => {
-                let (decrypted_message, _) =
-                    crate::cose::decrypt_xchacha20_poly1305(data.as_slice(), key)?;
+                let (decrypted_message, _) = crate::cose::decrypt_xchacha20_poly1305(
+                    &CoseEncrypt0Bytes::from(data.as_slice()),
+                    key,
+                )?;
                 Ok(decrypted_message)
             }
             _ => Err(CryptoError::WrongKeyType),

crates/bitwarden-crypto/src/error.rs

@@ -5,7 +5,7 @@ use bitwarden_error::bitwarden_error;
 use thiserror::Error;
 use uuid::Uuid;
 
-use crate::fingerprint::FingerprintError;
+use crate::{fingerprint::FingerprintError, safe::DataEnvelopeError};
 
 #[allow(missing_docs)]
 #[bitwarden_error(flat)]
@@ -68,6 +68,9 @@ pub enum CryptoError {
     #[error("Signature error, {0}")]
     Signature(#[from] SignatureError),
 
+    #[error("DataEnvelope error, {0}")]
+    DataEnvelopeError(#[from] DataEnvelopeError),
+
     #[error("Encoding error, {0}")]
     Encoding(#[from] EncodingError),
 }

crates/bitwarden-crypto/src/keys/symmetric_crypto_key.rs

@@ -73,6 +73,18 @@ pub struct XChaCha20Poly1305Key {
     pub(crate) enc_key: Pin<Box<GenericArray<u8, U32>>>,
 }
 
+impl XChaCha20Poly1305Key {
+    /// Creates a new XChaCha20Poly1305Key with a securely sampled cryptographic key and key id.
+    pub fn make() -> Self {
+        let mut rng = rand::thread_rng();
+        let mut enc_key = Box::pin(GenericArray::<u8, U32>::default());
+        rng.fill(enc_key.as_mut_slice());
+        let mut key_id = [0u8; KEY_ID_SIZE];
+        rng.fill(&mut key_id);
+        Self { enc_key, key_id }
+    }
+}
+
 impl ConstantTimeEq for XChaCha20Poly1305Key {
     fn ct_eq(&self, other: &Self) -> Choice {
         self.enc_key.ct_eq(&other.enc_key) & self.key_id.ct_eq(&other.key_id)