[PM-24263] Pin protected key envelope unlock (#372)

## 🎟️ Tracking

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

## 📔 Objective

Adds enrollment functionality for Password(PIN)Protected user key
envelope. Both crypto initialization via the init request, *and* a
function exposing the raw key material are provided. The latter is
required since unlock is not yet done via the init methods on
WASM/`clients`.

## ⏰ 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 <mgibson@bitwarden.com>
Co-authored-by: Oscar Hinton <Hinton@users.noreply.github.com>
Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com>

Author: 4 people

crates/bitwarden-core/src/client/encryption_settings.rs

@@ -45,6 +45,9 @@ pub enum EncryptionSettingsError {
 
     #[error(transparent)]
     UserIdAlreadySetError(#[from] UserIdAlreadySetError),
+
+    #[error("Wrong Pin")]
+    WrongPin,
 }
 
 #[allow(clippy::large_enum_variant)]

crates/bitwarden-core/src/client/internal.rs

@@ -25,7 +25,10 @@ use crate::{
         login_method::UserLoginMethod,
     },
     error::NotAuthenticatedError,
-    key_management::{crypto::InitUserCryptoRequest, SecurityState, SignedSecurityState},
+    key_management::{
+        crypto::InitUserCryptoRequest, PasswordProtectedKeyEnvelope, SecurityState,
+        SignedSecurityState,
+    },
 };
 
 /// Represents the user's keys, that are encrypted by the user key, and the signed security state.
@@ -309,6 +312,31 @@ impl InternalClient {
         self.initialize_user_crypto_decrypted_key(decrypted_user_key, key_state)
     }
 
+    #[cfg(feature = "internal")]
+    pub(crate) fn initialize_user_crypto_pin_envelope(
+        &self,
+        pin: String,
+        pin_protected_user_key_envelope: PasswordProtectedKeyEnvelope,
+        key_state: UserKeyState,
+    ) -> Result<(), EncryptionSettingsError> {
+        let decrypted_user_key = {
+            // Note: This block ensures ctx is dropped. Otherwise it would cause a deadlock when
+            // initializing the user crypto
+            use crate::key_management::SymmetricKeyId;
+            let ctx = &mut self.key_store.context_mut();
+            let decrypted_user_key_id = pin_protected_user_key_envelope
+                .unseal(SymmetricKeyId::Local("tmp_unlock_pin"), &pin, ctx)
+                .map_err(|_| EncryptionSettingsError::WrongPin)?;
+
+            // Allowing deprecated here, until a refactor to pass the Local key ids to
+            // `initialized_user_crypto_decrypted_key`
+            #[allow(deprecated)]
+            ctx.dangerous_get_symmetric_key(decrypted_user_key_id)?
+                .clone()
+        };
+        self.initialize_user_crypto_decrypted_key(decrypted_user_key, key_state)
+    }
+
     #[cfg(feature = "secrets")]
     pub(crate) fn initialize_crypto_single_org_key(
         &self,

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

@@ -7,10 +7,11 @@
 use std::collections::HashMap;
 
 use bitwarden_crypto::{
-    dangerous_get_v2_rotated_account_keys, AsymmetricCryptoKey, CoseSerializable, CryptoError,
-    EncString, Kdf, KeyDecryptable, KeyEncryptable, MasterKey, Pkcs8PrivateKeyBytes,
-    SignatureAlgorithm, SignedPublicKey, SigningKey, SpkiPublicKeyBytes, SymmetricCryptoKey,
-    UnsignedSharedKey, UserKey,
+    dangerous_get_v2_rotated_account_keys, safe::PasswordProtectedKeyEnvelopeError,
+    AsymmetricCryptoKey, CoseSerializable, CryptoError, EncString, Kdf, KeyDecryptable,
+    KeyEncryptable, MasterKey, Pkcs8PrivateKeyBytes, PrimitiveEncryptable, SignatureAlgorithm,
+    SignedPublicKey, SigningKey, SpkiPublicKeyBytes, SymmetricCryptoKey, UnsignedSharedKey,
+    UserKey,
 };
 use bitwarden_encoding::B64;
 use bitwarden_error::bitwarden_error;
@@ -23,7 +24,8 @@ use crate::{
     client::{encryption_settings::EncryptionSettingsError, LoginMethod, UserLoginMethod},
     error::StatefulCryptoError,
     key_management::{
-        AsymmetricKeyId, SecurityState, SignedSecurityState, SigningKeyId, SymmetricKeyId,
+        non_generic_wrappers::PasswordProtectedKeyEnvelope, AsymmetricKeyId, SecurityState,
+        SignedSecurityState, SigningKeyId, SymmetricKeyId,
     },
     Client, NotAuthenticatedError, OrganizationId, UserId, VaultLockedError, WrongPasswordError,
 };
@@ -39,6 +41,8 @@ pub enum CryptoClientError {
     VaultLocked(#[from] VaultLockedError),
     #[error(transparent)]
     Crypto(#[from] bitwarden_crypto::CryptoError),
+    #[error(transparent)]
+    PasswordProtectedKeyEnvelope(#[from] PasswordProtectedKeyEnvelopeError),
 }
 
 /// State used for initializing the user cryptographic state.
@@ -68,6 +72,7 @@ pub struct InitUserCryptoRequest {
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 #[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
 #[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+#[allow(clippy::large_enum_variant)]
 pub enum InitUserCryptoMethod {
     /// Password
     Password {
@@ -89,6 +94,13 @@ pub enum InitUserCryptoMethod {
         /// this.
         pin_protected_user_key: EncString,
     },
+    /// PIN Envelope
+    PinEnvelope {
+        /// The user's PIN
+        pin: String,
+        /// The user's symmetric crypto key, encrypted with the PIN-protected key envelope.
+        pin_protected_user_key_envelope: PasswordProtectedKeyEnvelope,
+    },
     /// Auth request
     AuthRequest {
         /// Private Key generated by the `crate::auth::new_auth_request`.
@@ -173,6 +185,16 @@ pub(super) async fn initialize_user_crypto(
                 key_state,
             )?;
         }
+        InitUserCryptoMethod::PinEnvelope {
+            pin,
+            pin_protected_user_key_envelope,
+        } => {
+            client.internal.initialize_user_crypto_pin_envelope(
+                pin,
+                pin_protected_user_key_envelope,
+                key_state,
+            )?;
+        }
         InitUserCryptoMethod::AuthRequest {
             request_private_key,
             method,
@@ -313,6 +335,38 @@ pub(super) fn update_password(
     })
 }
 
+/// Request for deriving a pin protected user key
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
+pub struct EnrollPinResponse {
+    /// [UserKey] protected by PIN
+    pub pin_protected_user_key_envelope: PasswordProtectedKeyEnvelope,
+    /// PIN protected by [UserKey]
+    pub user_key_encrypted_pin: EncString,
+}
+
+pub(super) fn enroll_pin(
+    client: &Client,
+    pin: String,
+) -> Result<EnrollPinResponse, CryptoClientError> {
+    let key_store = client.internal.get_key_store();
+    let mut ctx = key_store.context_mut();
+
+    let key_envelope =
+        PasswordProtectedKeyEnvelope(bitwarden_crypto::safe::PasswordProtectedKeyEnvelope::seal(
+            SymmetricKeyId::User,
+            &pin,
+            &ctx,
+        )?);
+    let encrypted_pin = pin.encrypt(&mut ctx, SymmetricKeyId::User)?;
+    Ok(EnrollPinResponse {
+        pin_protected_user_key_envelope: key_envelope,
+        user_key_encrypted_pin: encrypted_pin,
+    })
+}
+
 /// Request for deriving a pin protected user key
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -930,6 +984,62 @@ mod tests {
         assert_eq!(client_key, client3_key);
     }
 
+    #[tokio::test]
+    async fn test_initialize_user_crypto_pin_envelope() {
+        let user_key = "5yKAZ4TSSEGje54MV5lc5ty6crkqUz4xvl+8Dm/piNLKf6OgRi2H0uzttNTXl9z6ILhkmuIXzGpAVc2YdorHgQ==";
+        let test_pin = "1234";
+
+        let client1 = Client::new(None);
+        initialize_user_crypto(
+            &client1,
+            InitUserCryptoRequest {
+                user_id: Some(UserId::new_v4()),
+                kdf_params: Kdf::PBKDF2 {
+                    iterations: 100_000.try_into().unwrap(),
+                },
+                email: "test@bitwarden.com".into(),
+                private_key: make_key_pair(user_key.try_into().unwrap())
+                    .unwrap()
+                    .user_key_encrypted_private_key,
+                signing_key: None,
+                security_state: None,
+                method: InitUserCryptoMethod::DecryptedKey {
+                    decrypted_user_key: user_key.to_string(),
+                },
+            },
+        )
+        .await
+        .unwrap();
+
+        let enroll_response = client1.crypto().enroll_pin(test_pin.to_string()).unwrap();
+
+        let client2 = Client::new(None);
+        initialize_user_crypto(
+            &client2,
+            InitUserCryptoRequest {
+                user_id: Some(UserId::new_v4()),
+                // NOTE: THIS CHANGES KDF SETTINGS. We ensure in this test that even with different
+                // KDF settings the pin can unlock the user key.
+                kdf_params: Kdf::PBKDF2 {
+                    iterations: 600_000.try_into().unwrap(),
+                },
+                email: "test@bitwarden.com".into(),
+                private_key: make_key_pair(user_key.try_into().unwrap())
+                    .unwrap()
+                    .user_key_encrypted_private_key,
+                signing_key: None,
+                security_state: None,
+                method: InitUserCryptoMethod::PinEnvelope {
+                    pin: test_pin.to_string(),
+                    pin_protected_user_key_envelope: enroll_response
+                        .pin_protected_user_key_envelope,
+                },
+            },
+        )
+        .await
+        .unwrap();
+    }
+
     #[test]
     fn test_enroll_admin_password_reset() {
         let client = Client::new(None);

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

@@ -1,4 +1,4 @@
-use bitwarden_crypto::CryptoError;
+use bitwarden_crypto::{CryptoError, Decryptable};
 #[cfg(feature = "internal")]
 use bitwarden_crypto::{EncString, UnsignedSharedKey};
 use bitwarden_encoding::B64;
@@ -10,18 +10,23 @@ use super::crypto::{
     DeriveKeyConnectorRequest, EnrollAdminPasswordResetError, MakeKeyPairResponse,
     VerifyAsymmetricKeysRequest, VerifyAsymmetricKeysResponse,
 };
+#[cfg(any(feature = "wasm", test))]
+use crate::key_management::PasswordProtectedKeyEnvelope;
 #[cfg(feature = "internal")]
-use crate::key_management::crypto::{
-    derive_pin_key, derive_pin_user_key, enroll_admin_password_reset, get_user_encryption_key,
-    initialize_org_crypto, initialize_user_crypto, update_password, DerivePinKeyResponse,
-    InitOrgCryptoRequest, InitUserCryptoRequest, UpdatePasswordResponse,
+use crate::key_management::{
+    crypto::{
+        derive_pin_key, derive_pin_user_key, enroll_admin_password_reset, get_user_encryption_key,
+        initialize_org_crypto, initialize_user_crypto, update_password, DerivePinKeyResponse,
+        InitOrgCryptoRequest, InitUserCryptoRequest, UpdatePasswordResponse,
+    },
+    SymmetricKeyId,
 };
 use crate::{
     client::encryption_settings::EncryptionSettingsError,
     error::StatefulCryptoError,
     key_management::crypto::{
-        get_v2_rotated_account_keys, make_v2_keys_for_v1_user, CryptoClientError,
-        UserCryptoV2KeysResponse,
+        enroll_pin, get_v2_rotated_account_keys, make_v2_keys_for_v1_user, CryptoClientError,
+        EnrollPinResponse, UserCryptoV2KeysResponse,
     },
     Client,
 };
@@ -81,6 +86,45 @@ impl CryptoClient {
     ) -> Result<UserCryptoV2KeysResponse, StatefulCryptoError> {
         get_v2_rotated_account_keys(&self.client)
     }
+
+    /// Protects the current user key with the provided PIN. The result can be stored and later
+    /// used to initialize another client instance by using the PIN and the PIN key with
+    /// `initialize_user_crypto`.
+    pub fn enroll_pin(&self, pin: String) -> Result<EnrollPinResponse, CryptoClientError> {
+        enroll_pin(&self.client, pin)
+    }
+
+    /// Protects the current user key with the provided PIN. The result can be stored and later
+    /// used to initialize another client instance by using the PIN and the PIN key with
+    /// `initialize_user_crypto`. The provided pin is encrypted with the user key.
+    pub fn enroll_pin_with_encrypted_pin(
+        &self,
+        // Note: This will be replaced by `EncString` with https://bitwarden.atlassian.net/browse/PM-24775
+        encrypted_pin: String,
+    ) -> Result<EnrollPinResponse, CryptoClientError> {
+        let encrypted_pin: EncString = encrypted_pin.parse()?;
+        let pin = encrypted_pin.decrypt(
+            &mut self.client.internal.get_key_store().context_mut(),
+            SymmetricKeyId::User,
+        )?;
+        enroll_pin(&self.client, pin)
+    }
+
+    /// Decrypts a `PasswordProtectedKeyEnvelope`, returning the user key, if successful.
+    /// This is a stop-gap solution, until initialization of the SDK is used.
+    #[cfg(any(feature = "wasm", test))]
+    pub fn unseal_password_protected_key_envelope(
+        &self,
+        pin: String,
+        envelope: PasswordProtectedKeyEnvelope,
+    ) -> Result<Vec<u8>, CryptoClientError> {
+        let mut ctx = self.client.internal.get_key_store().context_mut();
+        let key_slot = SymmetricKeyId::Local("unseal_password_protected_key_envelope");
+        envelope.unseal(key_slot, pin.as_str(), &mut ctx)?;
+        #[allow(deprecated)]
+        let key = ctx.dangerous_get_symmetric_key(key_slot)?;
+        Ok(key.to_encoded().to_vec())
+    }
 }
 
 impl CryptoClient {
@@ -141,3 +185,40 @@ impl Client {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use bitwarden_crypto::{BitwardenLegacyKeyBytes, SymmetricCryptoKey};
+
+    use super::*;
+    use crate::client::test_accounts::test_bitwarden_com_account;
+
+    #[tokio::test]
+    async fn test_enroll_pin_envelope() {
+        // Initialize a test client with user crypto
+        let client = Client::init_test_account(test_bitwarden_com_account()).await;
+        let user_key_initial =
+            SymmetricCryptoKey::try_from(client.crypto().get_user_encryption_key().await.unwrap())
+                .unwrap();
+
+        // Enroll with a PIN, then re-enroll
+        let pin = "1234";
+        let enroll_response = client.crypto().enroll_pin(pin.to_string()).unwrap();
+        let re_enroll_response = client
+            .crypto()
+            .enroll_pin_with_encrypted_pin(enroll_response.user_key_encrypted_pin.to_string())
+            .unwrap();
+
+        let secret = BitwardenLegacyKeyBytes::from(
+            client
+                .crypto()
+                .unseal_password_protected_key_envelope(
+                    pin.to_string(),
+                    re_enroll_response.pin_protected_user_key_envelope,
+                )
+                .unwrap(),
+        );
+        let user_key_final = SymmetricCryptoKey::try_from(&secret).unwrap();
+        assert_eq!(user_key_initial, user_key_final);
+    }
+}

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

@@ -21,7 +21,6 @@ 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")]

crates/bitwarden-uniffi/src/crypto.rs

@@ -1,6 +1,6 @@
 use bitwarden_core::key_management::crypto::{
-    DeriveKeyConnectorRequest, DerivePinKeyResponse, InitOrgCryptoRequest, InitUserCryptoRequest,
-    UpdatePasswordResponse,
+    DeriveKeyConnectorRequest, DerivePinKeyResponse, EnrollPinResponse, InitOrgCryptoRequest,
+    InitUserCryptoRequest, UpdatePasswordResponse,
 };
 use bitwarden_crypto::{EncString, UnsignedSharedKey};
 use bitwarden_encoding::B64;
@@ -68,6 +68,26 @@ impl CryptoClient {
             .map_err(Error::MobileCrypto)?)
     }
 
+    /// Protects the current user key with the provided PIN. The result can be stored and later
+    /// used to initialize another client instance by using the PIN and the PIN key with
+    /// `initialize_user_crypto`.
+    pub fn enroll_pin(&self, pin: String) -> Result<EnrollPinResponse> {
+        Ok(self.0.enroll_pin(pin).map_err(Error::MobileCrypto)?)
+    }
+
+    /// Protects the current user key with the provided PIN. The result can be stored and later
+    /// used to initialize another client instance by using the PIN and the PIN key with
+    /// `initialize_user_crypto`. The provided pin is encrypted with the user key.
+    pub fn enroll_pin_with_encrypted_pin(
+        &self,
+        encrypted_pin: EncString,
+    ) -> Result<EnrollPinResponse> {
+        Ok(self
+            .0
+            .enroll_pin_with_encrypted_pin(encrypted_pin.to_string())
+            .map_err(Error::MobileCrypto)?)
+    }
+
     pub fn enroll_admin_password_reset(&self, public_key: B64) -> Result<UnsignedSharedKey> {
         Ok(self
             .0