[PM-24127] Implement password-protected key envelope #335
+901
−4
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ernal into km/cose-content-format
…b.com:bitwarden/sdk-internal into km/beeep/safe-password-protected-key-envelope
Co-authored-by: Oscar Hinton <[email protected]>
|
Noting here: I lifted in a fair bit of non-pin-specific changes from the follow-up PR to this PR since the last set of reviews. |
Hinton
approved these changes
Aug 15, 2025
There was a problem hiding this comment.
My primary concerns are resolved. I'd still like to see some elegant way to force upgrades as adding it later will be significantly more complicated. And a note to the root readme to look in safe before implementing anything.
But I'll leave it up to the team to decide if it happens now or when the need arises.
|
justindbaur
approved these changes
Aug 19, 2025
This was referenced Aug 19, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🎟️ Tracking
https://bitwarden.atlassian.net/browse/PM-24127
📔 Objective
The current masterkey logic is complex to understand for using teams (auth), and also prone to error. When any setting changes / gets out of sync, such as the email, or kdf, then decryption fails. The masterkey is further too widely scoped, used both in an authentication protocol, and in unlock decryption.
This PR introduces a PasswordProtectedKeyEnvelope. The goal is to protect a symmetric key with a password securely. Internally, this uses a KDF, and the KDF settings (argon2 parameters, and random salt) are stored on the serialized object.
That means that the only thing needed to unlock this structure is the correct password, everything else is stored on the object, making this process much less error prone. At the same time the interface is easier to use.
An example is provided to show usage.
A follow-up PR will add an unlock method / enrollment for PIN based on this new cryptographic API.
Note: Only argon2 is supported here. The PasswordProtectedKeyEnvelope's settings are completely decoupled from the account settings, and we don't need to provide backwards compatibility to non-recommended legacy cryptographic algorithms (pbkdf2).
⏰ Reminders before review
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 confirmedissue 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