[PM-15097] Implement COSE/XChaCha20 key format and encstring (#181)

## 🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-15097

## 📔 Objective

Adds the initial version of the new key format - using COSE, and adds
XChaCha20-Poly1305 encryption using it.

Specifically, to separate COSE keys from other types of keys, they are
padded using a PKCS7-like padding to be larger than the existing
AES256_CBC_HMAC keys. When wrapped using asymmetric encryption, or using
old symmetric encryption key types, COSE messages are serialized to the
byte array and padded.

When encrypted by other COSE keys, there is no padding needed, instead
the content_format will indicate what format the content message (key)
is using, one of which is `cosekey`. Content formats will be added in a
follow-up PR. The new encstring type shall not be used until then, since
this is another format change.

COSE keys are assigned a `key-id`, 24 random bytes, which is considered
enough for random collision resistance. Citing the XChaCha doc on why a
24-byte nonce is enough:
> Assuming a secure random number generator, random 192-bit nonces
   should experience a single collision (with probability 50%) after
   roughly 2^96 messages (approximately 7.2998163e+28).  A more
   conservative threshold (2^-32 chance of collision) still allows for
   2^80 messages to be sent under a single key.
(https://datatracker.ietf.org/doc/html/draft-arciszewski-xchacha).

## ⏰ 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: Matt Gibson <[email protected]>
Co-authored-by: Daniel García <[email protected]>
Co-authored-by: Oscar Hinton <[email protected]>

Author: 4 people

.vscode/settings.json

@@ -4,7 +4,9 @@
     "Bitwarden",
     "Cdecl",
     "chrono",
+    "ciphertext",
     "cloc",
+    "COSE",
     "dealloc",
     "decryptable",
     "dylib",
@@ -22,6 +24,7 @@
     "totp",
     "uniffi",
     "wordlist",
+    "XCHACHA",
     "Zeroize",
     "Zeroizing",
     "zxcvbn"

Cargo.lock

@@ -130,7 +130,7 @@ fn test_auth_request() {
 
     let decrypted = auth_request_decrypt_user_key(request.private_key, encrypted).unwrap();
 
-    assert_eq!(decrypted.to_vec(), secret);
+    assert_eq!(decrypted.to_encoded(), secret);
 }
 
 #[cfg(test)]
@@ -183,7 +183,7 @@ mod tests {
         let dec = auth_request_decrypt_user_key(private_key.to_owned(), enc_user_key).unwrap();
 
         assert_eq!(
-            &dec.to_vec(),
+            &dec.to_encoded(),
             &[
                 201, 37, 234, 213, 21, 75, 40, 70, 149, 213, 234, 16, 19, 251, 162, 245, 161, 74,
                 34, 245, 211, 151, 211, 192, 95, 10, 117, 50, 88, 223, 23, 157
@@ -202,7 +202,7 @@ mod tests {
                 .unwrap();
 
         assert_eq!(
-            &dec.to_vec(),
+            &dec.to_encoded(),
             &[
                 109, 128, 172, 147, 206, 123, 134, 95, 16, 36, 155, 113, 201, 18, 186, 230, 216,
                 212, 173, 188, 74, 11, 134, 131, 137, 242, 105, 178, 105, 126, 52, 139, 248, 91,

crates/bitwarden-core/src/auth/auth_request.rs

@@ -65,7 +65,7 @@ pub(crate) fn validate_password_user_key(
                 #[allow(deprecated)]
                 let existing_key = ctx.dangerous_get_symmetric_key(SymmetricKeyId::User)?;
 
-                if user_key.to_vec() != existing_key.to_vec() {
+                if user_key != *existing_key {
                     return Err(AuthValidateError::WrongUserKey);
                 }
 

crates/bitwarden-core/src/auth/password/validate.rs

@@ -37,7 +37,7 @@ pub(crate) fn validate_pin(
                 return Ok(false);
             };
 
-            Ok(user_key.to_vec() == decrypted_key.to_vec())
+            Ok(*user_key == decrypted_key)
         }
     }
 }

crates/bitwarden-core/src/auth/pin.rs

@@ -17,9 +17,7 @@ pub(super) fn make_register_tde_keys(
 ) -> Result<RegisterTdeKeyResponse, EncryptionSettingsError> {
     let public_key = AsymmetricPublicCryptoKey::from_der(&STANDARD.decode(org_public_key)?)?;
 
-    let mut rng = rand::thread_rng();
-
-    let user_key = UserKey::new(SymmetricCryptoKey::generate(&mut rng));
+    let user_key = UserKey::new(SymmetricCryptoKey::make_aes256_cbc_hmac_key());
     let key_pair = user_key.make_key_pair()?;
 
     let admin_reset = UnsignedSharedKey::encapsulate_key_unsigned(&user_key.0, &public_key)?;

crates/bitwarden-core/src/auth/tde.rs

@@ -776,7 +776,7 @@ mod tests {
             .dangerous_get_symmetric_key(SymmetricKeyId::User)
             .unwrap();
 
-        assert_eq!(&decrypted.to_vec(), &expected.to_vec());
+        assert_eq!(decrypted, *expected);
     }
 
     #[test]

crates/bitwarden-core/src/mobile/crypto.rs

@@ -31,6 +31,8 @@ base64 = ">=0.22.1, <0.23"
 bitwarden-error = { workspace = true }
 cbc = { version = ">=0.1.2, <0.2", features = ["alloc", "zeroize"] }
 chacha20poly1305 = { version = "0.10.1" }
+ciborium = { version = ">=0.2.2, <0.3" }
+coset = { version = ">=0.3.8, <0.4" }
 generic-array = { version = ">=0.14.7, <1.0", features = ["zeroize"] }
 hkdf = ">=0.12.3, <0.13"
 hmac = ">=0.12.1, <0.13"
@@ -48,6 +50,7 @@ sha2 = ">=0.10.6, <0.11"
 subtle = ">=2.5.0, <3.0"
 thiserror = { workspace = true }
 tsify-next = { workspace = true, optional = true }
+typenum = ">=1.18.0, <1.19.0"
 uniffi = { workspace = true, optional = true }
 uuid = { workspace = true }
 wasm-bindgen = { workspace = true, optional = true }

crates/bitwarden-crypto/Cargo.toml

@@ -16,7 +16,7 @@ secure.
 use bitwarden_crypto::{SymmetricCryptoKey, KeyEncryptable, KeyDecryptable, CryptoError};
 
 async fn example() -> Result<(), CryptoError> {
-  let key = SymmetricCryptoKey::generate(rand::thread_rng());
+  let key = SymmetricCryptoKey::make_aes256_cbc_hmac_key();
 
   let data = "Hello, World!".to_owned();
   let encrypted = data.clone().encrypt_with_key(&key)?;

crates/bitwarden-crypto/README.md

@@ -5,12 +5,11 @@
 //! In most cases you should use the [EncString][crate::EncString] with
 //! [KeyEncryptable][crate::KeyEncryptable] & [KeyDecryptable][crate::KeyDecryptable] instead.
 
-use aes::cipher::{
-    block_padding::Pkcs7, typenum::U32, BlockDecryptMut, BlockEncryptMut, KeyIvInit,
-};
+use aes::cipher::{block_padding::Pkcs7, BlockDecryptMut, BlockEncryptMut, KeyIvInit};
 use generic_array::GenericArray;
 use hmac::Mac;
 use subtle::ConstantTimeEq;
+use typenum::U32;
 
 use crate::{
     error::{CryptoError, Result},

crates/bitwarden-crypto/src/aes.rs

@@ -0,0 +1,132 @@
+//! This file contains private-use constants for COSE encoded key types and algorithms.
+//! Standardized values from <https://www.iana.org/assignments/cose/cose.xhtml> should always be preferred
+//! unless there is a a clear benefit, such as a clear cryptographic benefit, which MUST
+//! be documented publicly.
+
+use coset::{iana, CborSerializable, Label};
+use generic_array::GenericArray;
+use typenum::U32;
+
+use crate::{
+    error::EncStringParseError, xchacha20, CryptoError, SymmetricCryptoKey, XChaCha20Poly1305Key,
+};
+
+/// XChaCha20 <https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03> is used over ChaCha20
+/// to be able to randomly generate nonces, and to not have to worry about key wearout. Since
+/// the draft was never published as an RFC, we use a private-use value for the algorithm.
+pub(crate) const XCHACHA20_POLY1305: i64 = -70000;
+
+/// Encrypts a plaintext message using XChaCha20Poly1305 and returns a COSE Encrypt0 message
+pub(crate) fn encrypt_xchacha20_poly1305(
+    plaintext: &[u8],
+    key: &crate::XChaCha20Poly1305Key,
+) -> Result<Vec<u8>, CryptoError> {
+    let mut protected_header = coset::HeaderBuilder::new().build();
+    // This should be adjusted to use the builder pattern once implemented in coset.
+    // The related coset upstream issue is:
+    // https://github.com/google/coset/issues/105
+    protected_header.alg = Some(coset::Algorithm::PrivateUse(XCHACHA20_POLY1305));
+
+    let mut nonce = [0u8; xchacha20::NONCE_SIZE];
+    let cose_encrypt0 = coset::CoseEncrypt0Builder::new()
+        .protected(protected_header)
+        .create_ciphertext(plaintext, &[], |data, aad| {
+            let ciphertext =
+                crate::xchacha20::encrypt_xchacha20_poly1305(&(*key.enc_key).into(), data, aad);
+            nonce = ciphertext.nonce();
+            ciphertext.encrypted_bytes().to_vec()
+        })
+        .unprotected(coset::HeaderBuilder::new().iv(nonce.to_vec()).build())
+        .build();
+
+    cose_encrypt0
+        .to_vec()
+        .map_err(|err| CryptoError::EncString(EncStringParseError::InvalidCoseEncoding(err)))
+}
+
+/// Decrypts a COSE Encrypt0 message, using a XChaCha20Poly1305 key
+pub(crate) fn decrypt_xchacha20_poly1305(
+    cose_encrypt0_message: &[u8],
+    key: &crate::XChaCha20Poly1305Key,
+) -> Result<Vec<u8>, CryptoError> {
+    let msg = coset::CoseEncrypt0::from_slice(cose_encrypt0_message)
+        .map_err(|err| CryptoError::EncString(EncStringParseError::InvalidCoseEncoding(err)))?;
+    let Some(ref alg) = msg.protected.header.alg else {
+        return Err(CryptoError::EncString(
+            EncStringParseError::CoseMissingAlgorithm,
+        ));
+    };
+    if *alg != coset::Algorithm::PrivateUse(XCHACHA20_POLY1305) {
+        return Err(CryptoError::WrongKeyType);
+    }
+
+    let decrypted_message = msg.decrypt(&[], |data, aad| {
+        let nonce = msg.unprotected.iv.as_slice();
+        crate::xchacha20::decrypt_xchacha20_poly1305(
+            nonce
+                .try_into()
+                .map_err(|_| CryptoError::InvalidNonceLength)?,
+            &(*key.enc_key).into(),
+            data,
+            aad,
+        )
+    })?;
+    Ok(decrypted_message)
+}
+
+const SYMMETRIC_KEY: Label = Label::Int(iana::SymmetricKeyParameter::K as i64);
+
+impl TryFrom<&coset::CoseKey> for SymmetricCryptoKey {
+    type Error = CryptoError;
+
+    fn try_from(cose_key: &coset::CoseKey) -> Result<Self, Self::Error> {
+        let key_bytes = cose_key
+            .params
+            .iter()
+            .find_map(|(label, value)| match (label, value) {
+                (&SYMMETRIC_KEY, ciborium::Value::Bytes(bytes)) => Some(bytes),
+                _ => None,
+            })
+            .ok_or(CryptoError::InvalidKey)?;
+        let alg = cose_key.alg.as_ref().ok_or(CryptoError::InvalidKey)?;
+
+        match alg {
+            coset::Algorithm::PrivateUse(XCHACHA20_POLY1305) => {
+                // Ensure the length is correct since `GenericArray::clone_from_slice` panics if it
+                // receives the wrong length.
+                if key_bytes.len() != xchacha20::KEY_SIZE {
+                    return Err(CryptoError::InvalidKey);
+                }
+                let enc_key = Box::pin(GenericArray::<u8, U32>::clone_from_slice(key_bytes));
+                let key_id = cose_key
+                    .key_id
+                    .as_slice()
+                    .try_into()
+                    .map_err(|_| CryptoError::InvalidKey)?;
+                Ok(SymmetricCryptoKey::XChaCha20Poly1305Key(
+                    XChaCha20Poly1305Key { enc_key, key_id },
+                ))
+            }
+            _ => Err(CryptoError::InvalidKey),
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_encrypt_decrypt_roundtrip() {
+        let SymmetricCryptoKey::XChaCha20Poly1305Key(ref key) =
+            SymmetricCryptoKey::make_xchacha20_poly1305_key()
+        else {
+            panic!("Failed to create XChaCha20Poly1305Key");
+        };
+
+        let plaintext = b"Hello, world!";
+        let encrypted = encrypt_xchacha20_poly1305(plaintext, key).unwrap();
+        let decrypted = decrypt_xchacha20_poly1305(&encrypted, key).unwrap();
+        assert_eq!(decrypted, plaintext);
+    }
+}

crates/bitwarden-crypto/src/cose.rs

@@ -163,7 +163,7 @@ impl UnsignedSharedKey {
     ) -> Result<UnsignedSharedKey> {
         let enc = encrypt_rsa2048_oaep_sha1(
             encapsulation_key.to_public_key(),
-            &encapsulated_key.to_vec(),
+            &encapsulated_key.to_encoded(),
         )?;
         Ok(UnsignedSharedKey::Rsa2048_OaepSha1_B64 { data: enc })
     }