[PM-26177] Add methods to create rotateable key sets from PRF #494

iinuwa · 2025-10-06T17:22:50Z

🎟️ Tracking

📔 Objective

In order to set up unlock passkeys on mobile clients, this PR adds a method to create a rotateable key set derived from a PRF value.

This is based on existing code in the TypeScript library and web vault:

⏰ 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

👍 (:+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

github-actions · 2025-10-06T17:28:00Z

Checkmarx One – Scan Summary & Details – 29191a67-4f6f-4cd0-bfb4-778dbfa424e1

Great job! No new security vulnerabilities introduced in this pull request

codecov · 2025-10-06T17:36:17Z

Codecov Report

❌ Patch coverage is 91.71271% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.07%. Comparing base (ae9b8b5) to head (b9bb1f0).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/bitwarden-core/src/key_management/crypto.rs	0.00%	9 Missing ⚠️
...bitwarden-core/src/key_management/crypto_client.rs	0.00%	3 Missing ⚠️
crates/bitwarden-uniffi/src/crypto.rs	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #494      +/-   ##
==========================================
- Coverage   78.10%   78.07%   -0.04%     
==========================================
  Files         283      288       +5     
  Lines       27628    27853     +225     
==========================================
+ Hits        21579    21745     +166     
- Misses       6049     6108      +59

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

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

iinuwa · 2025-10-06T18:12:57Z

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

+        })
+    }
+
+    fn unlock<Ids: KeyIds>(


This method is currently unused since we don't yet have plans to use the rotateable key set on mobile, only to create them. However, it implements functionality that is currently done in TypeScript that could be moved to the SDK.

I can remove it until we decide to either migrate the browser apps to this SDK method or start using it in the mobile apps.

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

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

quexten · 2025-10-07T09:37:33Z

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

+    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.


Note: I think this needs a KM-owned tech debt follow-up ticket. I'll make a jira ticket when this merges, but adding the APIs for this feels out of scope for an external PR.

quexten

Changes look mostly good, thank you!
Only some minor questions / nits.

One more (optional) suggestion here would be to take test vectors from the TS clients and feed them into the unit tests so we know the implementation works the same way.

iinuwa · 2025-10-07T18:06:54Z

Thank you for the review!

One more (optional) suggestion here would be to take test vectors from the TS clients and feed them into the unit tests so we know the implementation works the same way.

I looked around the clients codebase, but I don't see a full test vector for an end-to-end (PRF, User Key) -> RotateableKeySet and back. There are mocked values that don't verify the actual cryptography in https://github.com/bitwarden/clients/blob/main/libs/auth/src/common/login-strategies/webauthn-login.strategy.spec.ts and https://github.com/bitwarden/clients/blob/main/libs/common/src/auth/services/webauthn-login/webauthn-login.service.spec.ts. The Rust types guarantee some of the other invariants tested in. Did you have some specific test vectors in mind?

abergs · 2025-10-07T18:41:57Z

@iinuwa just a ping that the lint failed and needs a cargo +"nightly-2025-08-18" fmt

iinuwa · 2025-10-07T19:41:54Z

@iinuwa just a ping that the lint failed and needs a cargo +"nightly-2025-08-18" fmt

Thanks. I'm using jj which doesn't run git hooks, and my IDE formats according to Rust stable formatting rules, but doesn't format comments the same way. I'll work that out in my workflow.

quexten · 2025-10-08T10:49:30Z

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

Note: I'd recommend moving RotateableKeySet into it's own file, since it is a different cryptographic construction. key_rotation.rs is really just meant for "User Key Rotation", which may interact with RotateableKeySets, but is a different use-case.

(As a KM note, key_rotation.rs should probably be renamed to user_key_rotation.rs)

claude · 2025-10-08T14:27:37Z

Claude finished @iinuwa's task —— View job

PR Review: Add methods to create rotateable key sets from PRF

Review Tasks:

Read repository guidelines (CLAUDE.md) - No repo-specific guidelines found
Analyze main implementation files
Review cryptographic correctness and security
Check code quality and best practices
Examine test coverage and testing approach
Provide comprehensive feedback

Summary

This PR successfully implements PRF-based rotateable key set creation for mobile unlock passkeys. The implementation follows established patterns in the codebase and addresses the core requirements. However, there are several areas that need attention.

🎨 Code Quality & Architecture

Positive Aspects

Consistent patterns: The implementation follows existing cryptographic patterns in the codebase (e.g., similar to master_key.rs and pin_key.rs)
Good separation of concerns: PRF logic is cleanly separated in its own module
Proper error handling: Uses appropriate CryptoError types throughout
Clear documentation: Good docstrings explaining the purpose and requirements

Areas for Improvement

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

🎨 Minor Issues:

Line 49-50: The test test_long_prf_truncated_to_proper_length has a logic error:

let key1 = derive_symmetric_key_from_prf(&long_prf).unwrap();
let key2 = derive_symmetric_key_from_prf(&prf).unwrap();
assert_eq!(key1, key2);  // This will likely fail!

The test creates two different pseudorandom byte sequences but expects them to be equal. It should use the same first 32 bytes:

let long_prf = pseudorandom_bytes(64);
let truncated_prf = &long_prf[..32];
let key1 = derive_symmetric_key_from_prf(&long_prf).unwrap();
let key2 = derive_symmetric_key_from_prf(truncated_prf).unwrap();

Line 10: The zero-check validation is good but consider documenting why all-zeros PRF is dangerous
Line 13-15: The Box::pin() conversion seems unnecessary - consider if this can be simplified

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

📝 Observations:

Architecture suggestion: As noted in review comments, consider moving RotateableKeySet to its own file since it's a distinct cryptographic primitive
Line 91: Good use of #[allow(deprecated)] with clear reasoning in comments
Lines 119-137: The unlock method is currently dead code but well-implemented for future migration

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

✅ Implementation looks correct:

Proper error propagation
Correct use of existing key store context
Good integration with existing patterns

🔒 Security Analysis

Cryptographic Correctness

✅ PRF truncation: Correctly truncates PRF to 32 bytes, which is appropriate for the security level
✅ Key derivation: Uses existing stretch_key function via HKDF, maintaining consistency
✅ Zero validation: Prevents use of uninitialized/zero PRF values
✅ Key encapsulation: Follows established patterns for public key encryption of downstream keys

Security Concerns

⚠️ PRF source validation: The implementation trusts that the PRF input is cryptographically secure. Consider adding documentation about PRF requirements
✅ No sensitive data leakage: Proper handling of key material throughout

🧪 Testing

Test Coverage

✅ Basic functionality: Well covered with positive and negative cases
✅ Error cases: Tests for short PRF and zero PRF rejection
❌ Test bug: As noted above, test_long_prf_truncated_to_proper_length has incorrect logic
📝 Missing coverage: No end-to-end integration tests (though this may be intentional for this PR scope)

Test Quality

The tests in prf.rs are well-structured but the truncation test needs fixing. The rotateable key set tests in key_rotation.rs are comprehensive and demonstrate proper usage patterns.

🚀 Performance & Efficiency

✅ Minimal overhead: Adds minimal computational overhead
✅ Memory efficient: No unnecessary allocations or copies
✅ Lazy evaluation: Keys are generated on-demand

📋 API Design

✅ Consistent naming: Follows established conventions (make_prf_user_key_set)
✅ Proper error types: Returns appropriate CryptoClientError/CryptoError
✅ Type safety: Good use of type system to prevent misuse

⚠️ Issues Requiring Attention

Critical: Fix the test logic bug in test_long_prf_truncated_to_proper_length
Minor: Consider documentation improvements for PRF security requirements
Future: Address the architectural suggestion to move RotateableKeySet to its own file

🔧 Recommendations

Fix the test: Update the truncation test to properly validate that long PRFs are correctly truncated
Add PRF documentation: Document expected PRF entropy and security requirements
Consider test vectors: If available from TypeScript implementation, add cross-platform test vectors

✅ Overall Assessment

This is a well-implemented PR that successfully adds the requested functionality while maintaining code quality and security standards. The cryptographic approach is sound and follows established patterns. With the test fix, this would be ready for merge.

The implementation correctly addresses the objective of enabling unlock passkeys on mobile clients through PRF-derived rotateable key sets.

sonarqubecloud · 2025-10-08T14:33:19Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Add methods to create rotateable key sets from PRF

32ca764

iinuwa force-pushed the km/PM-26177/create-prf-user-key-set branch from 2514070 to 32ca764 Compare October 6, 2025 18:30

iinuwa commented Oct 6, 2025

View reviewed changes

This was referenced Oct 6, 2025

[PM-26177] Derive rotateable key set from PRF (3/3) #487

Closed

[PM-26177] Add methods to create rotateable key set (2/3) #486

Closed

[PM-26354] Add methods to un-/wrap asymmetric keys in keystore context (1/3) #485

Closed

Mark unused method

4b8b249

quexten reviewed Oct 7, 2025

View reviewed changes

crates/bitwarden-crypto/src/store/key_rotation.rs Outdated Show resolved Hide resolved

quexten reviewed Oct 7, 2025

View reviewed changes

crates/bitwarden-crypto/src/keys/prf.rs Show resolved Hide resolved

quexten reviewed Oct 7, 2025

View reviewed changes

crates/bitwarden-crypto/src/keys/prf.rs Outdated Show resolved Hide resolved

quexten reviewed Oct 7, 2025

View reviewed changes

iinuwa added 2 commits October 7, 2025 13:02

Clarify implicit PRF truncation

eabb6cf

Use upstream/downstream key terminology for rotateable key set

748f6d6

iinuwa added 2 commits October 7, 2025 14:40

Fix lints

f986b43

Feature-gate wasm-only imports

0dce15e

quexten reviewed Oct 8, 2025

View reviewed changes

Lint with correct version of cargo-sort

b9bb1f0

[PM-26177] Add methods to create rotateable key sets from PRF #494

Are you sure you want to change the base?

[PM-26177] Add methods to create rotateable key sets from PRF #494

Uh oh!

Conversation

iinuwa commented Oct 6, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎟️ Tracking

📔 Objective

⏰ Reminders before review

🦮 Reviewer guidelines

Uh oh!

github-actions bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Great job! No new security vulnerabilities introduced in this pull request

Uh oh!

codecov bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iinuwa Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

quexten Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

quexten left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iinuwa commented Oct 7, 2025

Uh oh!

abergs commented Oct 7, 2025

Uh oh!

iinuwa commented Oct 7, 2025

Uh oh!

quexten Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claude bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Add methods to create rotateable key sets from PRF

Review Tasks:

Summary

🎨 Code Quality & Architecture

Positive Aspects

Areas for Improvement

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

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

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

🔒 Security Analysis

Cryptographic Correctness

Security Concerns

🧪 Testing

Test Coverage

Test Quality

🚀 Performance & Efficiency

📋 API Design

⚠️ Issues Requiring Attention

🔧 Recommendations

✅ Overall Assessment

Uh oh!

sonarqubecloud bot commented Oct 8, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

iinuwa commented Oct 6, 2025 •

edited by atlassian bot

Loading

github-actions bot commented Oct 6, 2025 •

edited

Loading

codecov bot commented Oct 6, 2025 •

edited

Loading

quexten left a comment •

edited

Loading

quexten Oct 8, 2025 •

edited

Loading

claude bot commented Oct 8, 2025 •

edited

Loading