[RFC] Implement password-protected key envelope

crates/bitwarden-crypto/examples/protect_key_with_password.rs

@@ -0,0 +1,103 @@
+//! This example demonstrates how to securely protect keys with a password using the
+//! [PasswordProtectedKeyEnvelope].
+
+use bitwarden_crypto::{
+    key_ids, KeyStore, KeyStoreContext, PasswordProtectedKeyEnvelope,
+    PasswordProtectedKeyEnvelopeError,
+};
+
+fn main() {
+    let key_story = KeyStore::<ExampleIds>::default();
+    let mut ctx: KeyStoreContext<'_, ExampleIds> = key_story.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 this protected with a PIN.
+    let vault_key = ctx
+        .generate_symmetric_key(ExampleSymmetricKey::VaultKey)
+        .unwrap();
+
+    // Seal the key with the PIN
+    // The KDF settings are chosen for you, and do not need to be separately tracked or synced
+    // Next, story 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().unwrap());
+
+    // 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").unwrap()).unwrap();
+    deserialized
+        .unseal(ExampleSymmetricKey::VaultKey, pin, &mut ctx)
+        .unwrap();
+
+    // 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().unwrap());
+
+    // Alice wants to change the protected key. This requires creating a new envelope
+    ctx.generate_symmetric_key(ExampleSymmetricKey::VaultKey)
+        .unwrap();
+    let envelope = PasswordProtectedKeyEnvelope::seal(ExampleSymmetricKey::VaultKey, "0000", &ctx)
+        .expect("Sealing should work");
+    disk.save("vault_key_envelope", (&envelope).try_into().unwrap());
+
+    // 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

@@ -22,10 +22,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

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,8 @@ pub use store::{
 };
 mod cose;
 pub use cose::CoseSerializable;
+mod safe;
+pub use safe::*;
 mod signing;
 pub use signing::*;
 mod traits;

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

@@ -0,0 +1,2 @@
+mod password_protected_key_envelope;
+pub use password_protected_key_envelope::*;