[RFC] Implement data envelope

crates/bitwarden-crypto/examples/seal_struct.rs

@@ -0,0 +1,91 @@
+//! 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, 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::DataEnvelope::<ExampleIds>::seal(
+        my_item,
+        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::DataEnvelope<ExampleIds> =
+        bitwarden_crypto::DataEnvelope::from(sealed_item);
+
+    let my_item: MyItem = sealed_item
+        .unseal(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 @@
     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 @@
     BitwardenLegacyKey,
     /// Stream of bytes
     OctetStream,
+    /// Cbor serialized data
+    Cbor,
 }
 
 mod private {
@@ -191,6 +195,34 @@
 /// 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

@@ -13,7 +13,8 @@
 use crate::{
     content_format::{Bytes, ConstContentFormat, CoseContentFormat},
     error::{EncStringParseError, EncodingError},
-    xchacha20, ContentFormat, CryptoError, SymmetricCryptoKey, XChaCha20Poly1305Key,
+    xchacha20, ContentFormat, CoseEncrypt0Bytes, CryptoError, SymmetricCryptoKey,
+    XChaCha20Poly1305Key,
 };
 
 /// XChaCha20 <https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03> is used over ChaCha20
@@ -38,7 +39,7 @@
     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();
@@ -68,14 +69,15 @@
     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 {
@@ -170,12 +172,16 @@
             }
             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),
         }
     }
 }
@@ -201,6 +207,7 @@
             Some(ContentType::Assigned(CoapContentFormat::OctetStream)) => {
                 Ok(ContentFormat::OctetStream)
             }
+            Some(ContentType::Assigned(CoapContentFormat::Cbor)) => Ok(ContentFormat::Cbor),
             _ => Err(CryptoError::EncString(
                 EncStringParseError::CoseMissingContentType,
             )),
@@ -307,7 +314,9 @@
             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)
@@ -321,7 +330,7 @@
             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)
         ));
     }
@@ -338,7 +347,7 @@
             .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

@@ -8,8 +8,8 @@ use super::{check_length, from_b64, from_b64_vec, split_enc_string};
 use crate::{
     error::{CryptoError, EncStringParseError, Result, UnsupportedOperation},
     util::FromStrVisitor,
-    Aes256CbcHmacKey, ContentFormat, KeyDecryptable, KeyEncryptable, KeyEncryptableWithContentType,
-    SymmetricCryptoKey, Utf8Bytes, XChaCha20Poly1305Key,
+    Aes256CbcHmacKey, ContentFormat, CoseEncrypt0Bytes, KeyDecryptable, KeyEncryptable,
+    KeyEncryptableWithContentType, SymmetricCryptoKey, Utf8Bytes, XChaCha20Poly1305Key,
 };
 
 #[cfg(feature = "wasm")]
@@ -266,7 +266,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].
@@ -311,8 +313,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/lib.rs

@@ -36,6 +36,8 @@ pub use store::{
 };
 mod cose;
 pub use cose::CoseSerializable;
+mod safe;
+pub use safe::*;
 mod signing;
 pub use signing::*;
 mod traits;