Add methods to create rotateable key sets from PRF

Author: iinuwa

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

@@ -8,9 +8,10 @@ use std::collections::HashMap;
 
 use bitwarden_crypto::{
     AsymmetricCryptoKey, CoseSerializable, CryptoError, EncString, Kdf, KeyDecryptable,
-    KeyEncryptable, MasterKey, Pkcs8PrivateKeyBytes, PrimitiveEncryptable, SignatureAlgorithm,
-    SignedPublicKey, SigningKey, SpkiPublicKeyBytes, SymmetricCryptoKey, UnsignedSharedKey,
-    UserKey, dangerous_get_v2_rotated_account_keys, safe::PasswordProtectedKeyEnvelopeError,
+    KeyEncryptable, MasterKey, Pkcs8PrivateKeyBytes, PrimitiveEncryptable, RotateableKeySet,
+    SignatureAlgorithm, SignedPublicKey, SigningKey, SpkiPublicKeyBytes, SymmetricCryptoKey,
+    UnsignedSharedKey, UserKey, dangerous_get_v2_rotated_account_keys,
+    derive_symmetric_key_from_prf, safe::PasswordProtectedKeyEnvelopeError,
 };
 use bitwarden_encoding::B64;
 use bitwarden_error::bitwarden_error;
@@ -498,6 +499,16 @@ fn derive_pin_protected_user_key(
     Ok(derived_key.encrypt_user_key(user_key)?)
 }
 
+pub(super) fn make_prf_user_key_set(
+    client: &Client,
+    prf: B64,
+) -> Result<RotateableKeySet, CryptoClientError> {
+    let prf_key = derive_symmetric_key_from_prf(prf.as_bytes())?;
+    let ctx = client.internal.get_key_store().context();
+    let key_set = RotateableKeySet::new(&ctx, &prf_key, SymmetricKeyId::User)?;
+    Ok(key_set)
+}
+
 #[allow(missing_docs)]
 #[bitwarden_error(flat)]
 #[derive(Debug, thiserror::Error)]

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

@@ -1,4 +1,4 @@
-use bitwarden_crypto::{CryptoError, Decryptable, Kdf};
+use bitwarden_crypto::{CryptoError, Decryptable, Kdf, RotateableKeySet};
 #[cfg(feature = "internal")]
 use bitwarden_crypto::{EncString, UnsignedSharedKey};
 use bitwarden_encoding::B64;
@@ -18,7 +18,7 @@ use crate::key_management::{
     crypto::{
         DerivePinKeyResponse, InitOrgCryptoRequest, InitUserCryptoRequest, UpdatePasswordResponse,
         derive_pin_key, derive_pin_user_key, enroll_admin_password_reset, get_user_encryption_key,
-        initialize_org_crypto, initialize_user_crypto,
+        initialize_org_crypto, initialize_user_crypto, make_prf_user_key_set,
     },
 };
 use crate::{
@@ -172,6 +172,12 @@ impl CryptoClient {
         derive_pin_user_key(&self.client, encrypted_pin)
     }
 
+    /// Creates a new rotateable key set for the current user key protected
+    /// by a key derived from the given PRF.
+    pub fn make_prf_user_key_set(&self, prf: B64) -> Result<RotateableKeySet, CryptoClientError> {
+        make_prf_user_key_set(&self.client, prf)
+    }
+
     /// Prepares the account for being enrolled in the admin password reset feature. This encrypts
     /// the users [UserKey][bitwarden_crypto::UserKey] with the organization's public key.
     pub fn enroll_admin_password_reset(

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

@@ -33,4 +33,6 @@ pub use kdf::{
     default_pbkdf2_iterations,
 };
 pub(crate) use key_id::{KEY_ID_SIZE, KeyId};
+mod prf;
 pub(crate) mod utils;
+pub use prf::derive_symmetric_key_from_prf;

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

@@ -0,0 +1,44 @@
+use crate::{CryptoError, SymmetricCryptoKey, utils::stretch_key};
+
+/// Takes the output of a PRF and derives a symmetric key
+pub fn derive_symmetric_key_from_prf(prf: &[u8]) -> Result<SymmetricCryptoKey, CryptoError> {
+    let (secret, _) = prf
+        .split_at_checked(32)
+        .ok_or_else(|| CryptoError::InvalidKeyLen)?;
+    let secret: [u8; 32] = secret.try_into().unwrap();
+    if secret.iter().all(|b| *b == b'\0') {
+        return Err(CryptoError::ZeroNumber);
+    }
+    Ok(SymmetricCryptoKey::Aes256CbcHmacKey(stretch_key(
+        &Box::pin(secret.into()),
+    )?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn test_prf_succeeds() {
+        let prf = [
+            0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
+            24, 25, 26, 27, 28, 29, 30, 31,
+        ];
+        derive_symmetric_key_from_prf(&prf).unwrap();
+    }
+
+    #[test]
+    fn test_zero_key_fails() {
+        let prf = [
+            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+            0, 0, 0,
+        ];
+        let err = derive_symmetric_key_from_prf(&prf).unwrap_err();
+        assert!(matches!(err, CryptoError::ZeroNumber));
+    }
+    #[test]
+    fn test_short_prf_fails() {
+        let prf = [0, 1, 2, 3, 4, 5, 6, 7, 8];
+        let err = derive_symmetric_key_from_prf(&prf).unwrap_err();
+        assert!(matches!(err, CryptoError::InvalidKeyLen));
+    }
+}

crates/bitwarden-crypto/src/lib.rs

@@ -32,7 +32,8 @@ mod wordlist;
 pub use wordlist::EFF_LONG_WORD_LIST;
 mod store;
 pub use store::{
-    KeyStore, KeyStoreContext, RotatedUserKeys, dangerous_get_v2_rotated_account_keys,
+    KeyStore, KeyStoreContext, RotateableKeySet, RotatedUserKeys,
+    dangerous_get_v2_rotated_account_keys,
 };
 mod cose;
 pub use cose::CoseSerializable;

crates/bitwarden-crypto/src/store/key_rotation.rs

@@ -1,7 +1,11 @@
+use serde::{Deserialize, Serialize};
+use tsify::Tsify;
+
 use crate::{
-    CoseKeyBytes, CoseSerializable, CryptoError, EncString, KeyEncryptable, KeyIds,
-    KeyStoreContext, SignedPublicKey, SignedPublicKeyMessage, SpkiPublicKeyBytes,
-    SymmetricCryptoKey,
+    AsymmetricCryptoKey, AsymmetricPublicCryptoKey, CoseKeyBytes, CoseSerializable, CryptoError,
+    EncString, KeyDecryptable, KeyEncryptable, KeyIds, KeyStoreContext, Pkcs8PrivateKeyBytes,
+    SignedPublicKey, SignedPublicKeyMessage, SpkiPublicKeyBytes, SymmetricCryptoKey,
+    UnsignedSharedKey,
 };
 
 /// Rotated set of account keys
@@ -45,6 +49,113 @@ pub fn dangerous_get_v2_rotated_account_keys<Ids: KeyIds>(
     })
 }
 
+/// A set of keys where a given `EncryptionKey` is protected by an encrypted public/private
+/// key-pair. The `EncryptionKey` is used to encrypt/decrypt data, while the public/private key-pair
+/// is used to rotate the `EncryptionKey`.
+///
+/// The `PrivateKey` is protected by an `ExternalKey`, such as a `DeviceKey`, or `PrfKey`,
+/// and the `PublicKey` is protected by the `EncryptionKey`. This setup allows:
+///
+///   - Access to `EncryptionKey` by knowing the `ExternalKey`
+///   - Rotation to a `NewEncryptionKey` by knowing the current `UserKey`, without needing access to
+///     the `ExternalKey`
+#[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 RotateableKeySet {
+    /// `EncryptionKey` protected by encapsulation key
+    encapsulated_encryption_key: UnsignedSharedKey,
+    /// Encapsulation key protected by `EncryptionKey`
+    encrypted_encapsulation_key: EncString,
+    /// Decapsulation key protected by `ExternalKey`
+    wrapped_decapsulation_key: EncString,
+}
+
+impl RotateableKeySet {
+    /// Create a set of keys to allow access to the user key via the provided
+    /// symmetric wrapping key while allowing the user key to be rotated.
+    pub fn new<Ids: KeyIds>(
+        ctx: &KeyStoreContext<Ids>,
+        wrapping_key: &SymmetricCryptoKey,
+        key_to_wrap: Ids::Symmetric,
+    ) -> Result<Self, CryptoError> {
+        let key_pair = AsymmetricCryptoKey::make(crate::PublicKeyEncryptionAlgorithm::RsaOaepSha1);
+
+        #[allow(deprecated)]
+        let key_to_wrap_instance = ctx.dangerous_get_symmetric_key(key_to_wrap)?;
+        // encapsulate encryption key
+        let encapsulated_encryption_key = UnsignedSharedKey::encapsulate_key_unsigned(
+            key_to_wrap_instance,
+            &key_pair.to_public_key(),
+        )?;
+
+        // wrap decapsulation key
+        let wrapped_decapsulation_key = key_pair.to_der()?.encrypt_with_key(wrapping_key)?;
+
+        // wrap encapsulation key with encryption key
+        // Note: Usually, a public key is - by definition - public, so this should not be necessary.
+        // The specific use-case for this function is to enable rotateable key sets, where
+        // the "public key" is not public, with the intent of preventing the server from being able
+        // to overwrite the user key unlocked by the rotateable keyset.
+        let encrypted_encapsulation_key = key_pair
+            .to_public_key()
+            .to_der()?
+            .encrypt_with_key(&key_to_wrap_instance)?;
+
+        Ok(RotateableKeySet {
+            encapsulated_encryption_key,
+            encrypted_encapsulation_key,
+            wrapped_decapsulation_key,
+        })
+    }
+
+    fn unlock<Ids: KeyIds>(
+        &self,
+        ctx: &mut KeyStoreContext<Ids>,
+        unwrapping_key: &SymmetricCryptoKey,
+        key_to_unwrap: Ids::Symmetric,
+    ) -> Result<(), CryptoError> {
+        let priv_key_bytes: Vec<u8> = self
+            .wrapped_decapsulation_key
+            .decrypt_with_key(unwrapping_key)?;
+        let decapsulation_key =
+            AsymmetricCryptoKey::from_der(&Pkcs8PrivateKeyBytes::from(priv_key_bytes))?;
+        let encryption_key = self
+            .encapsulated_encryption_key
+            .decapsulate_key_unsigned(&decapsulation_key)?;
+        #[allow(deprecated)]
+        ctx.set_symmetric_key(key_to_unwrap, encryption_key)?;
+        Ok(())
+    }
+}
+
+fn rotate_key_set<Ids: KeyIds>(
+    ctx: &KeyStoreContext<Ids>,
+    key_set: RotateableKeySet,
+    old_encryption_key_id: Ids::Symmetric,
+    new_encryption_key_id: Ids::Symmetric,
+) -> Result<RotateableKeySet, CryptoError> {
+    let pub_key_bytes = ctx.decrypt_data_with_symmetric_key(
+        old_encryption_key_id,
+        &key_set.encrypted_encapsulation_key,
+    )?;
+    let pub_key = SpkiPublicKeyBytes::from(pub_key_bytes);
+    let encapsulation_key = AsymmetricPublicCryptoKey::from_der(&pub_key)?;
+    // TODO: There is no method to store only the public key in the store, so we
+    // have pull out the encryption key to encapsulate it manually.
+    #[allow(deprecated)]
+    let new_encryption_key = ctx.dangerous_get_symmetric_key(new_encryption_key_id)?;
+    let new_encapsulated_key =
+        UnsignedSharedKey::encapsulate_key_unsigned(new_encryption_key, &encapsulation_key)?;
+    let new_encrypted_encapsulation_key = pub_key.encrypt_with_key(new_encryption_key)?;
+    Ok(RotateableKeySet {
+        encapsulated_encryption_key: new_encapsulated_key,
+        encrypted_encapsulation_key: new_encrypted_encapsulation_key,
+        wrapped_decapsulation_key: key_set.wrapped_decapsulation_key,
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -137,4 +248,79 @@ mod tests {
                 .unwrap()
         );
     }
+
+    #[test]
+    fn test_rotateable_key_set_can_unlock() {
+        // generate initial keys
+        let external_key = SymmetricCryptoKey::make_aes256_cbc_hmac_key();
+        // set up store
+        let store: KeyStore<TestIds> = KeyStore::default();
+        let mut ctx = store.context_mut();
+        let original_encryption_key_id = TestSymmKey::A(0);
+        ctx.generate_symmetric_key(original_encryption_key_id)
+            .unwrap();
+
+        // create key set
+        let key_set =
+            RotateableKeySet::new(&ctx, &external_key, original_encryption_key_id).unwrap();
+
+        // unlock key set
+        let unwrapped_encryption_key_id = TestSymmKey::A(1);
+        key_set
+            .unlock(&mut ctx, &external_key, unwrapped_encryption_key_id)
+            .unwrap();
+
+        #[allow(deprecated)]
+        let original_key = ctx
+            .dangerous_get_symmetric_key(original_encryption_key_id)
+            .unwrap();
+        #[allow(deprecated)]
+        let unwrapped_key = ctx
+            .dangerous_get_symmetric_key(unwrapped_encryption_key_id)
+            .unwrap();
+        assert_eq!(original_key, unwrapped_key);
+    }
+
+    #[test]
+    fn test_rotateable_key_set_rotation() {
+        // generate initial keys
+        let external_key = SymmetricCryptoKey::make_aes256_cbc_hmac_key();
+        // set up store
+        let store: KeyStore<TestIds> = KeyStore::default();
+        let mut ctx = store.context_mut();
+        let original_encryption_key_id = TestSymmKey::A(1);
+        ctx.generate_symmetric_key(original_encryption_key_id)
+            .unwrap();
+
+        // create key set
+        let key_set =
+            RotateableKeySet::new(&ctx, &external_key, original_encryption_key_id).unwrap();
+
+        // rotate
+        let new_encryption_key_id = TestSymmKey::A(2_1);
+        ctx.generate_symmetric_key(new_encryption_key_id).unwrap();
+        let new_key_set = rotate_key_set(
+            &ctx,
+            key_set,
+            original_encryption_key_id,
+            new_encryption_key_id,
+        )
+        .unwrap();
+
+        // After rotation, the new key set should be unlocked by the same
+        // external key and return the new encryption key.
+        let unwrapped_encryption_key_id = TestSymmKey::A(2_2);
+        new_key_set
+            .unlock(&mut ctx, &external_key, unwrapped_encryption_key_id)
+            .unwrap();
+        #[allow(deprecated)]
+        let new_encryption_key = ctx
+            .dangerous_get_symmetric_key(new_encryption_key_id)
+            .unwrap();
+        #[allow(deprecated)]
+        let unwrapped_encryption_key = ctx
+            .dangerous_get_symmetric_key(unwrapped_encryption_key_id)
+            .unwrap();
+        assert_eq!(new_encryption_key, unwrapped_encryption_key);
+    }
 }

crates/bitwarden-uniffi/src/crypto.rs

@@ -2,7 +2,7 @@ use bitwarden_core::key_management::crypto::{
     DeriveKeyConnectorRequest, DerivePinKeyResponse, EnrollPinResponse, InitOrgCryptoRequest,
     InitUserCryptoRequest, UpdateKdfResponse, UpdatePasswordResponse,
 };
-use bitwarden_crypto::{EncString, Kdf, UnsignedSharedKey};
+use bitwarden_crypto::{EncString, Kdf, RotateableKeySet, UnsignedSharedKey};
 use bitwarden_encoding::B64;
 
 use crate::error::Result;
@@ -88,6 +88,12 @@ impl CryptoClient {
         Ok(self.0.derive_key_connector(request)?)
     }
 
+    /// Creates the a new rotateable key set for the current user key protected
+    /// by a key derived from the given PRF.
+    pub fn make_prf_user_key_set(&self, prf: B64) -> Result<RotateableKeySet> {
+        Ok(self.0.make_prf_user_key_set(prf)?)
+    }
+
     /// Create the data necessary to update the user's kdf settings. The user's encryption key is
     /// re-encrypted for the password under the new kdf settings. This returns the new encrypted
     /// user key and the new password hash but does not update sdk state.