[PM-26459] Implement data envelope (#336)

## 🎟️ Tracking

<!-- Paste the link to the Jira or GitHub issue or otherwise describe /
point to where this change is coming from. -->
https://bitwarden.atlassian.net/browse/PM-26459

https://bitwarden.atlassian.net/wiki/spaces/EN/pages/2052653095/Draft+Tech+Breakdown+-+DataEnvelope

## 📔 Objective

> [!IMPORTANT]  
> The confluence document has a more detailed breakdown. This is a
shortened version.

Consumers want to protect complex structs such as:
- Vault exports
- Ciphers (vault items)
- Organization reports

Currently, they serialize these themselves (organization reports are
serialized as json), and encrypt fields individually. This is slow to
handle during encrypt/decrypt, and complex to maintain. The server now
has to know the same representation as clients. At the same time, this
can be abused by the server omitting certain fields, or swapping
encrypted fields encrypted under the same key.

EncStrings are not the correct abstraction layer. A new abstraction /
API that is safe and easier to use (an impossible to misuse) is needed.

### Security Definition

**Attacker model:** The relevant attacker model here is a fully
compromised server. That’s what E2E encryption / zero knowledge protect
against.

**Security Goals:** 

**SG1:** The structure should not be modifiable (malleable)
- Reason: This can be abused by the attacker by tampering with the
encrypted item in (to the developer) unexpected ways

**SG2:** The attacker should not be able to infer anything about the
contents of the structure aside from length
- Reason: We have a “Zero knowledge” product and customers expect their
data to not be readable by anyone but them.

**SG3:** The structure should only be encryptable in the specific
section of code that the developer intends
- I.e it should not be possible to swap an encrypted vault item into an
encrypted “user settings” “slot”, since the behavior here is undefined.
 - Reason: Same as SG1

This PR implements a "DataEnvelope". The DataEnvelope solves the problem
of encrypting entire structs. The caller just provides a struct that is
Serializable/Deserializable, and gets back an encrypted blob. The caller
does not decide serialization.

Further, we force the creation of a "content encryption key" by the
interface. This ensures that teams do not create a coupling to keys.
When implementing key-rotation we do not want to re-upload data, but
only re-upload re-encrypted keys, and the content-encryption-key
enforces this key being present.

An example is provided to show usage.

## ⏰ Reminders before review

- Contributor guidelines followed
- All formatters and local linters executed and passed
- Written new unit and / or integration tests where applicable
- Protected functional changes with optionality (feature flags)
- Used internationalization (i18n) for all UI strings
- CI builds passed
- Communicated to DevOps any deployment requirements
- Updated any necessary documentation (Confluence, contributing docs) or
informed the documentation
  team

## 🦮 Reviewer guidelines

<!-- Suggested interactions but feel free to use (or not) as you desire!
-->

- 👍 (`:+1:`) or similar for great changes
- 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info
- ❓ (`:question:`) for questions
- 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry
that's not quite a confirmed
  issue and could potentially benefit from discussion
- 🎨 (`:art:`) for suggestions / improvements
- ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or
concerns needing attention
- 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or
indications of technical debt
- ⛏ (`:pick:`) for minor or nitpick changes

---------

Co-authored-by: Daniel García <dani-garcia@users.noreply.github.com>
Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com>

Author: 3 people

crates/bitwarden-crypto/examples/seal_struct.rs

@@ -0,0 +1,115 @@
+//! 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::{
+    generate_versioned_sealable, key_ids,
+    safe::{DataEnvelope, DataEnvelopeNamespace, SealableData, SealableVersionedData},
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, PartialEq, Debug)]
+struct MyItemV1 {
+    a: u32,
+    b: String,
+}
+impl SealableData for MyItemV1 {}
+
+#[derive(Serialize, Deserialize, PartialEq, Debug)]
+struct MyItemV2 {
+    a: u32,
+    b: bool,
+    c: bool,
+}
+impl SealableData for MyItemV2 {}
+
+generate_versioned_sealable!(
+    MyItem,
+    DataEnvelopeNamespace::VaultItem,
+    [
+        MyItemV1 => "1",
+        MyItemV2 => "2",
+    ]
+);
+
+fn main() {
+    let store: bitwarden_crypto::KeyStore<ExampleIds> =
+        bitwarden_crypto::KeyStore::<ExampleIds>::default();
+    let mut ctx: bitwarden_crypto::KeyStoreContext<'_, ExampleIds> = store.context_mut();
+    let mut disk = MockDisk::new();
+
+    let my_item: MyItem = MyItemV1 {
+        a: 42,
+        b: "Hello, World!".to_string(),
+    }
+    .into();
+
+    // Seals the item into an encrypted blob, and stores the content-encryption-key in the context.
+    // Returned is the sealed item, along with the id of the content-encryption-key used to seal it
+    // on the context. The cek has to be protected separately. Alternatively
+    // `seal_with_wrapping_key` can be used to directly obtain back the wrapped cek.
+    let (sealed_item, cek) = DataEnvelope::seal(my_item, &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 = DataEnvelope::from(sealed_item);
+
+    // Unseal the item again, using the content-encryption-key stored in the context.
+    let my_item: MyItem = sealed_item
+        .unseal(cek, &mut ctx)
+        .expect("Unsealing should work");
+    assert!(matches!(my_item, MyItem::MyItemV1(item) if item.a == 42 && 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(LocalId)
+    }
+
+    #[asymmetric]
+    pub enum ExampleAsymmetricKey {
+        Key(u8),
+        #[local]
+        Local(LocalId),
+    }
+
+    #[signing]
+    pub enum ExampleSigningKey {
+        Key(u8),
+        #[local]
+        Local(LocalId),
+    }
+    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

@@ -5,14 +5,14 @@
 
 use coset::{
     CborSerializable, ContentType, Header, Label,
-    iana::{self, CoapContentFormat},
+    iana::{self, CoapContentFormat, KeyOperation},
 };
 use generic_array::GenericArray;
 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,
@@ -33,20 +33,23 @@ pub(crate) const ARGON2_PARALLELISM: i64 = -71004;
 // Note: These are in the "unregistered" tree: https://datatracker.ietf.org/doc/html/rfc6838#section-3.4
 // These are only used within Bitwarden, and not meant for exchange with other systems.
 const CONTENT_TYPE_PADDED_UTF8: &str = "application/x.bitwarden.utf8-padded";
+pub(crate) const CONTENT_TYPE_PADDED_CBOR: &str = "application/x.bitwarden.cbor-padded";
 const CONTENT_TYPE_BITWARDEN_LEGACY_KEY: &str = "application/x.bitwarden.legacy-key";
 const CONTENT_TYPE_SPKI_PUBLIC_KEY: &str = "application/x.bitwarden.spki-public-key";
 
 // Labels
 //
 /// 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 +81,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 {
@@ -141,6 +145,25 @@ impl TryFrom<&coset::CoseKey> for SymmetricCryptoKey {
             })
             .ok_or(CryptoError::InvalidKey)?;
         let alg = cose_key.alg.as_ref().ok_or(CryptoError::InvalidKey)?;
+        let key_opts = cose_key
+            .key_ops
+            .iter()
+            .map(|op| match op {
+                coset::RegisteredLabel::Assigned(iana::KeyOperation::Encrypt) => {
+                    Ok(KeyOperation::Encrypt)
+                }
+                coset::RegisteredLabel::Assigned(iana::KeyOperation::Decrypt) => {
+                    Ok(KeyOperation::Decrypt)
+                }
+                coset::RegisteredLabel::Assigned(iana::KeyOperation::WrapKey) => {
+                    Ok(KeyOperation::WrapKey)
+                }
+                coset::RegisteredLabel::Assigned(iana::KeyOperation::UnwrapKey) => {
+                    Ok(KeyOperation::UnwrapKey)
+                }
+                _ => Err(CryptoError::InvalidKey),
+            })
+            .collect::<Result<Vec<KeyOperation>, CryptoError>>()?;
 
         match alg {
             coset::Algorithm::PrivateUse(XCHACHA20_POLY1305) => {
@@ -156,7 +179,11 @@ impl TryFrom<&coset::CoseKey> for SymmetricCryptoKey {
                     .try_into()
                     .map_err(|_| CryptoError::InvalidKey)?;
                 Ok(SymmetricCryptoKey::XChaCha20Poly1305Key(
-                    XChaCha20Poly1305Key { enc_key, key_id },
+                    XChaCha20Poly1305Key {
+                        enc_key,
+                        key_id,
+                        supported_operations: key_opts,
+                    },
                 ))
             }
             _ => Err(CryptoError::InvalidKey),
@@ -180,12 +207,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 +242,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,
             )),
@@ -362,8 +394,16 @@ mod test {
         let key = XChaCha20Poly1305Key {
             key_id: KEY_ID,
             enc_key: Box::pin(*GenericArray::from_slice(&KEY_DATA)),
+            supported_operations: vec![
+                KeyOperation::Decrypt,
+                KeyOperation::Encrypt,
+                KeyOperation::WrapKey,
+                KeyOperation::UnwrapKey,
+            ],
         };
-        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)
@@ -375,9 +415,15 @@ mod test {
         let key = XChaCha20Poly1305Key {
             key_id: [1; 16], // Different key ID
             enc_key: Box::pin(*GenericArray::from_slice(&KEY_DATA)),
+            supported_operations: vec![
+                KeyOperation::Decrypt,
+                KeyOperation::Encrypt,
+                KeyOperation::WrapKey,
+                KeyOperation::UnwrapKey,
+            ],
         };
         assert!(matches!(
-            decrypt_xchacha20_poly1305(TEST_VECTOR_COSE_ENCRYPT0, &key),
+            decrypt_xchacha20_poly1305(&CoseEncrypt0Bytes::from(TEST_VECTOR_COSE_ENCRYPT0), &key),
             Err(CryptoError::WrongCoseKeyId)
         ));
     }
@@ -394,11 +440,17 @@ 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,
             enc_key: Box::pin(*GenericArray::from_slice(&KEY_DATA)),
+            supported_operations: vec![
+                KeyOperation::Decrypt,
+                KeyOperation::Encrypt,
+                KeyOperation::WrapKey,
+                KeyOperation::UnwrapKey,
+            ],
         };
         assert!(matches!(
             decrypt_xchacha20_poly1305(&serialized_message, &key),