[PM-24127] Implement password-protected key envelope (#335)

## 🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-24127
## 📔 Objective

The current masterkey logic is complex to understand for using teams
(auth), and also prone to error. When any setting changes / gets out of
sync, such as the email, or kdf, then decryption fails. The masterkey is
further too widely scoped, used both in an authentication protocol, and
in unlock decryption.

This PR introduces a PasswordProtectedKeyEnvelope. The goal is to
protect a symmetric key with a password securely. Internally, this uses
a KDF, and the KDF settings (argon2 parameters, and random salt) are
stored on the serialized object.

That means that the only thing needed to unlock this structure is the
correct password, everything else is stored on the object, making this
process much less error prone. At the same time the interface is easier
to use.

An example is provided to show usage.

A follow-up PR will add an unlock method / enrollment for PIN based on
this new cryptographic API.

Note: Only argon2 is supported here. The PasswordProtectedKeyEnvelope's
settings are completely decoupled from the account settings, and we
don't need to provide backwards compatibility to non-recommended legacy
cryptographic algorithms (pbkdf2).

## ⏰ 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: Oscar Hinton <[email protected]>
Co-authored-by: Thomas Avery <[email protected]>

Author: 4 people

crates/bitwarden-core/src/key_management/mod.rs

@@ -18,6 +18,11 @@ mod crypto_client;
 #[cfg(feature = "internal")]
 pub use crypto_client::CryptoClient;
 
+#[cfg(feature = "internal")]
+mod non_generic_wrappers;
+#[allow(unused_imports)]
+#[cfg(feature = "internal")]
+pub(crate) use non_generic_wrappers::*;
 #[cfg(feature = "internal")]
 mod security_state;
 #[cfg(feature = "internal")]

crates/bitwarden-core/src/key_management/non_generic_wrappers.rs

@@ -0,0 +1,36 @@
+//! Structs with generic parameters cannot be moved across FFI bounds (uniffi/wasm).
+//! This module contains wrapper structs that hide the generic parameter with instantiated versions.
+
+use std::ops::Deref;
+
+use serde::{Deserialize, Serialize};
+#[cfg(feature = "wasm")]
+use tsify::Tsify;
+
+use crate::key_management::KeyIds;
+
+/// A non-generic wrapper around `bitwarden-crypto`'s `PasswordProtectedKeyEnvelope`.
+#[derive(Serialize, Deserialize)]
+#[serde(transparent)]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct PasswordProtectedKeyEnvelope(
+    #[cfg_attr(
+        feature = "wasm",
+        tsify(type = r#"Tagged<string, "PasswordProtectedKeyEnvelope">"#)
+    )]
+    pub(crate) bitwarden_crypto::safe::PasswordProtectedKeyEnvelope<KeyIds>,
+);
+
+impl Deref for PasswordProtectedKeyEnvelope {
+    type Target = bitwarden_crypto::safe::PasswordProtectedKeyEnvelope<KeyIds>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl std::fmt::Debug for PasswordProtectedKeyEnvelope {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}

crates/bitwarden-core/src/uniffi_support.rs

@@ -1,11 +1,11 @@
 //! This module contains custom type converters for Uniffi.
 
-use std::num::NonZeroU32;
+use std::{num::NonZeroU32, str::FromStr};
 
 use bitwarden_crypto::CryptoError;
 use uuid::Uuid;
 
-use crate::key_management::SignedSecurityState;
+use crate::key_management::{PasswordProtectedKeyEnvelope, SignedSecurityState};
 
 uniffi::use_remote_type!(bitwarden_crypto::NonZeroU32);
 
@@ -35,3 +35,11 @@ uniffi::custom_type!(SignedSecurityState, String, {
     },
     lower: |obj| obj.into(),
 });
+
+uniffi::custom_type!(PasswordProtectedKeyEnvelope, String, {
+    remote,
+    try_lift: |val| bitwarden_crypto::safe::PasswordProtectedKeyEnvelope::from_str(val.as_str())
+        .map_err(|e| e.into())
+        .map(PasswordProtectedKeyEnvelope),
+    lower: |obj| obj.0.into(),
+});

crates/bitwarden-crypto/examples/protect_key_with_password.rs

@@ -0,0 +1,109 @@
+//! This example demonstrates how to securely protect keys with a password using the
+//! [PasswordProtectedKeyEnvelope].
+
+use bitwarden_crypto::{
+    key_ids,
+    safe::{PasswordProtectedKeyEnvelope, PasswordProtectedKeyEnvelopeError},
+    KeyStore, KeyStoreContext,
+};
+
+fn main() {
+    let key_store = KeyStore::<ExampleIds>::default();
+    let mut ctx: KeyStoreContext<'_, ExampleIds> = key_store.context_mut();
+    let mut disk = MockDisk::new();
+
+    // Alice wants to protect a key with a password.
+    // For example to:
+    // - Protect her vault with a pin
+    // - Protect her exported vault with a password
+    // - Protect a send with a URL fragment secret
+    // For this, the `PasswordProtectedKeyEnvelope` is used.
+
+    // Alice has a vault protected with a symmetric key. She wants the symmetric key protected with
+    // a PIN.
+    let vault_key = ctx
+        .generate_symmetric_key(ExampleSymmetricKey::VaultKey)
+        .expect("Generating vault key should work");
+
+    // Seal the key with the PIN
+    // The KDF settings are chosen for you, and do not need to be separately tracked or synced
+    // Next, store this protected key envelope on disk.
+    let pin = "1234";
+    let envelope =
+        PasswordProtectedKeyEnvelope::seal(vault_key, pin, &ctx).expect("Sealing should work");
+    disk.save("vault_key_envelope", (&envelope).into());
+
+    // Wipe the context to simulate new session
+    ctx.clear_local();
+
+    // Load the envelope from disk and unseal it with the PIN, and store it in the context.
+    let deserialized: PasswordProtectedKeyEnvelope<ExampleIds> =
+        PasswordProtectedKeyEnvelope::try_from(
+            disk.load("vault_key_envelope")
+                .expect("Loading from disk should work"),
+        )
+        .expect("Deserializing envelope should work");
+    deserialized
+        .unseal(ExampleSymmetricKey::VaultKey, pin, &mut ctx)
+        .expect("Unsealing should work");
+
+    // Alice wants to change her password; also her KDF settings are below the minimums.
+    // Re-sealing will update the password, and KDF settings.
+    let envelope = envelope
+        .reseal(pin, "0000")
+        .expect("The password should be valid");
+    disk.save("vault_key_envelope", (&envelope).into());
+
+    // Alice wants to change the protected key. This requires creating a new envelope
+    ctx.generate_symmetric_key(ExampleSymmetricKey::VaultKey)
+        .expect("Generating vault key should work");
+    let envelope = PasswordProtectedKeyEnvelope::seal(ExampleSymmetricKey::VaultKey, "0000", &ctx)
+        .expect("Sealing should work");
+    disk.save("vault_key_envelope", (&envelope).into());
+
+    // Alice tries the password but it is wrong
+    assert!(matches!(
+        envelope.unseal(ExampleSymmetricKey::VaultKey, "9999", &mut ctx),
+        Err(PasswordProtectedKeyEnvelopeError::WrongPassword)
+    ));
+}
+
+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]
+        VaultKey
+    }
+
+    #[asymmetric]
+    pub enum ExampleAsymmetricKey {
+        Key(u8),
+    }
+
+    #[signing]
+    pub enum ExampleSigningKey {
+        Key(u8),
+    }
+
+   pub ExampleIds => ExampleSymmetricKey, ExampleAsymmetricKey, ExampleSigningKey;
+}

crates/bitwarden-crypto/src/cose.rs

@@ -5,9 +5,10 @@
 
 use coset::{
     iana::{self, CoapContentFormat},
-    CborSerializable, ContentType, Label,
+    CborSerializable, ContentType, Header, Label,
 };
 use generic_array::GenericArray;
+use thiserror::Error;
 use typenum::U32;
 
 use crate::{
@@ -22,6 +23,12 @@ use crate::{
 pub(crate) const XCHACHA20_POLY1305: i64 = -70000;
 const XCHACHA20_TEXT_PAD_BLOCK_SIZE: usize = 32;
 
+pub(crate) const ALG_ARGON2ID13: i64 = -71000;
+pub(crate) const ARGON2_SALT: i64 = -71001;
+pub(crate) const ARGON2_ITERATIONS: i64 = -71002;
+pub(crate) const ARGON2_MEMORY: i64 = -71003;
+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";
@@ -221,6 +228,52 @@ pub trait CoseSerializable<T: CoseContentFormat + ConstContentFormat> {
     where
         Self: Sized;
 }
+
+pub(crate) fn extract_integer(
+    header: &Header,
+    target_label: i64,
+    value_name: &str,
+) -> Result<i128, CoseExtractError> {
+    header
+        .rest
+        .iter()
+        .find_map(|(label, value)| match (label, value) {
+            (Label::Int(label_value), ciborium::Value::Integer(int_value))
+                if *label_value == target_label =>
+            {
+                Some(*int_value)
+            }
+            _ => None,
+        })
+        .map(Into::into)
+        .ok_or_else(|| CoseExtractError::MissingValue(value_name.to_string()))
+}
+
+pub(crate) fn extract_bytes(
+    header: &Header,
+    target_label: i64,
+    value_name: &str,
+) -> Result<Vec<u8>, CoseExtractError> {
+    header
+        .rest
+        .iter()
+        .find_map(|(label, value)| match (label, value) {
+            (Label::Int(label_value), ciborium::Value::Bytes(byte_value))
+                if *label_value == target_label =>
+            {
+                Some(byte_value.clone())
+            }
+            _ => None,
+        })
+        .ok_or(CoseExtractError::MissingValue(value_name.to_string()))
+}
+
+#[derive(Debug, Error)]
+pub(crate) enum CoseExtractError {
+    #[error("Missing value {0}")]
+    MissingValue(String),
+}
+
 #[cfg(test)]
 mod test {
     use super::*;

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

@@ -9,7 +9,7 @@ mod symmetric_crypto_key;
 #[cfg(test)]
 pub use symmetric_crypto_key::derive_symmetric_key;
 pub use symmetric_crypto_key::{
-    Aes256CbcHmacKey, Aes256CbcKey, SymmetricCryptoKey, XChaCha20Poly1305Key,
+    Aes256CbcHmacKey, Aes256CbcKey, EncodedSymmetricKey, SymmetricCryptoKey, XChaCha20Poly1305Key,
 };
 mod asymmetric_crypto_key;
 pub use asymmetric_crypto_key::{

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

@@ -407,6 +407,7 @@ impl From<EncodedSymmetricKey> for Vec<u8> {
     }
 }
 impl EncodedSymmetricKey {
+    /// Returns the content format of the encoded symmetric key.
     #[allow(private_interfaces)]
     pub fn content_format(&self) -> ContentFormat {
         match self {

crates/bitwarden-crypto/src/lib.rs

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

crates/bitwarden-crypto/src/safe/README.md

@@ -0,0 +1,16 @@
+# Bitwarden-crypto safe module
+
+The safe module provides high-level cryptographic tools for building secure protocols and features.
+When developing new features, use this module first before considering lower-level primitives from
+other parts of `bitwarden-crypto`.
+
+## Password-protected key envelope
+
+Use the password protected key envelope to protect a symmetric key with a password. Examples
+include:
+
+- locking a vault with a PIN/Password
+- protecting exports with a password
+
+Internally, the module uses a KDF to protect against brute-forcing, but it does not expose this to
+the consumer. The consumer only provides a password and key.

crates/bitwarden-crypto/src/safe/mod.rs

@@ -0,0 +1,4 @@
+#![doc = include_str!("./README.md")]
+
+mod password_protected_key_envelope;
+pub use password_protected_key_envelope::*;