[PM-24127] Implement password-protected key envelope

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::*;