[PM-24127] Implement password-protected key envelope

.vscode/settings.json

@@ -15,6 +15,7 @@
     "encryptable",
     "Hkdf",
     "Hmac",
+    "keyslot",
     "Maybeable",
     "Oaep",
     "Pbkdf",

crates/bitwarden-crypto/examples/protect_key_with_password.rs

@@ -0,0 +1,118 @@
+//! 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).try_into().expect("Saving envelope should work"),
+    );
+
+    // 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).try_into().expect("Saving envelope should work"),
+    );
+
+    // 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).try_into().expect("Saving envelope should work"),
+    );
+
+    // 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,10 +23,16 @@ 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";
-const CONTENT_TYPE_BITWARDEN_LEGACY_KEY: &str = "application/x.bitwarden.legacy-key";
+pub(crate) 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
@@ -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> {
+    Ok(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,
+        })
+        .ok_or(CoseExtractError::MissingValue(value_name.to_string()))?
+        .into())
+}
+
+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::*;