Skip to content

fix(key-wallet): derive the BIP39 seed in wiped buffers - #1393

Merged
ZocoLini merged 2 commits into
devfrom
pasta/key-wallet-bip39-seed-wiped-buffers
Nov 12, 2026
Merged

ZocoLini merged 2 commits into
devfrom
pasta/key-wallet-bip39-seed-wiped-buffers

Conversation

@PastaPastaPasta

@PastaPastaPasta PastaPastaPasta commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

The seed derivation passes all 24 English (TREZOR) and all 24 Japanese BIP-39 vectors, as the bip39 3.0.0 crate carries them, plus fixed vectors for an empty passphrase, a non-normalized passphrase, and phrases of 127, 128 and 129 bytes on either side of the HMAC key block. The seed also matches the bip39 crate's for every supported wordlist, over short and long phrases and passphrases with compatibility characters, an emoji and 300 bytes.

Mnemonic::to_seed used to call the bip39 crate's derivation and wrap only the returned seed in Zeroizing. It now runs PBKDF2-HMAC-SHA512 in key-wallet (2048 rounds, salt "mnemonic" + NFKD(passphrase), one 64-byte block), keyed with bitcoin_hashes' HmacEngine::new. The salt, the round value, the output and the keyed HMAC engine are wiped when dropped, and HmacEngine::new wipes its own pads. Each round's clone of the keyed engine, which finalize consumes, and the value finalize returns are not wiped; the commit message lists these and the other copies that are not wiped. The seed is byte-for-byte the same as before for every mnemonic and passphrase, and no public signature, feature or dependency changes.

🤖 Generated with Claude Code

PR Hygiene · 966df23

  • Bots — coderabbitai ✓
  • Self-review — posted; again after any push
  • Build running
  • Approvals
    • key-wallet (key-wallet/src/mnemonic.rs, key-wallet/src/mnemonic_tests.rs) — QuantumExplorer or ZocoLini or xdustinface

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

Summary by CodeRabbit

  • Bug Fixes

    • Improved BIP-39 seed derivation to produce expected results across supported languages, including with empty, Unicode, and other passphrases.
  • Tests

    • Expanded coverage for mnemonic-to-seed results across additional languages, phrases, and passphrases.

The complete English (TREZOR) and Japanese BIP-39 vector sets pass through the public API, as do fixed seeds for empty and non-NFKD passphrases and for phrases of 127, 128 and 129 bytes, on either side of the HMAC key block. The seeds also match the bip39 crate for every wordlist.

Mnemonic::to_seed delegated derivation to the bip39 crate and only wrapped the returned seed in Zeroizing. It now derives PBKDF2-HMAC-SHA512 itself (2048 rounds, salt "mnemonic" + NFKD(passphrase), one 64-byte block), keyed with bitcoin_hashes' HmacEngine::new, so the intermediate state can be wiped.

HmacEngine::new hashes a key longer than the block first and erases its pads with volatile writes. The keyed engine is erased through non_secure_erase when the seed is returned. The salt, UTF-8 scratch, round value U and output T are Zeroizing buffers.

Not wiped: the digest values each round returns, the engine clones consumed by finalize, and moved copies of the keyed engine, which hold the keyed HMAC state. Also not wiped: SHA-512 internals, including the hash of a phrase longer than 128 bytes and the engine that computed it inside HmacEngine::new; unicode-normalization's decomposition buffers; and compiler or register copies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Mnemonic::to_seed now derives BIP39 seeds with a local PBKDF2-HMAC-SHA512 implementation. The implementation uses zeroizable HMAC state and intermediate buffers. Tests cover English and Japanese vectors and compare results with the bip39 crate across languages, entropy lengths, and passphrases.

Changes: BIP39 seed derivation

Layer / File(s) Summary
Seed derivation implementation
key-wallet/src/mnemonic.rs
Adds a zeroizable HMAC-SHA512 engine and a 2048-round PBKDF2 implementation. Mnemonic::to_seed uses the local implementation with the mnemonic phrase and passphrase.
Seed derivation vectors and checks
key-wallet/src/mnemonic.rs, key-wallet/src/mnemonic_tests.rs
Replaces limited English seed tests with the complete English “TREZOR” vector set. Adds Japanese and additional vectors, plus checks against the bip39 crate across supported languages, entropy lengths, and passphrases.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Possibly related PRs

Suggested reviewers: quantumexplorer, xdustinface

Merge Risk: Minimal · up to 966df

The change moves BIP39 seed derivation into wiped buffers while keeping seeds identical, and it adds extensive vector tests. No actionable merge-blocking risk was identified.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: deriving the BIP39 seed in wiped buffers within key-wallet.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Finishing Touches

Generate docstrings

  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 470e4e7 and 966df23.

Files selected for processing: 2

  • key-wallet/src/mnemonic.rs
  • key-wallet/src/mnemonic_tests.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Waiting for bot review — coderabbitai not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 11, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Bots are done — your move: post /self-reviewed.
Full checklist in the description.

@github-actions github-actions Bot added waiting-self-review Waiting for the author to post /self-reviewed bot-review-skipped A required review bot did not report; it was skipped by the window or by a person. and removed waiting-bots Waiting for the review bots to report on this head labels Nov 11, 2026
@manki-review

manki-review Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

✅ Review complete in 3m 31s

Planner (6s)
    fix · 400 lines · 2 agents
    judge effort: high

Review (security · pair): 4 findings
    ✅ Claude Sonnet 5.5 · high: 1 finding (42s)
    ✅ Claude Opus 5.5 · high: 3 findings (1m 26s)

Judge: 3 kept · 0 dropped (1m 29s)
    kept: 1 warning · 2 suggestion

Review metadata

Config:

  • Models: reviewer=claude-sonnet-5-5, judge=claude-opus-5-5
  • Triage: trivial=false, subtle=true, paired=true (planner, security-sensitive paths)
  • Team: Claude Sonnet 5.5 · high, Claude Opus 5.5 · high
  • Memory: enabled (central)

Account limits:

  • Claude subscription: weekly 11% (resets 2026-11-17 05:00 UTC)

Judge decisions:

  • Kept: "Per-round HMAC engine clones and finalize outputs are not wiped" (warning, high confidence): "warning. Only the template engine is wrapped in Zeroizing<SeedHmacEngine> (key-wallet/src/mnemonic.rs:185-187). The clone at key-wallet/src/mnemonic.rs:190 and the clone in each loop round at key-wallet/src/mnemonic.rs:198 are plain HmacEngine locals. finalize() consumes them at :194 and :200 with no non_secure_erase. Their keyed midstates are equivalent to the phrase for HMAC purposes and stay in stack memory. This leaves the PR's main goal partly unmet. The seed is still correct, and an attacker needs local memory access to read the leftover data, which no outside input provides. That makes it degraded hardening, not a blocker. Before this PR, the bip39 crate wiped nothing, so the change is no regression.
    Refutation unsettled: In mnemonic.rs, the clones at lines 190 and 198 are plain HmacEngine locals passed by value to finalize() at lines 194 and 200, and only the template inside Zeroizing is erased (lines 161-164, 186-188). But HmacEngine::finalize and Hmac::from_engine come from the external bitcoin_hashes 1.2 crate (re-exported at hashes/src/lib.rs:108-111), and its source is not in the checkout. So I could not check whether finalize leaves the inner and outer SHA-512 states in memory. Rule checked: In Rust, a value moved into a function by value is only wiped if that function or the type's Drop impl overwrites it; a plain clone that is not wrapped in Zeroizing gets no automatic erase.
  • Premise "HmacEngine::finalize / Hmac::from_engine in dashcore_hashes consumes the engine without erasing its inner and outer SHA-512 states" unsettled. dashcore_hashes only re-exports HmacEngine and Hmac from the external bitcoin_hashes crate (version 1.2.0 in the workspace manifest), and that crate's hmac.rs is not in the checkout, so I could not read what finalize and from_engine do with the engine."
  • Kept: "The salt buffer is built by hand instead of with the existing collect_zeroizing helper" (suggestion, medium confidence): "suggestion. collect_zeroizing exists in key-wallet/src/mnemonic.rs, as the tool check shows. Building the salt from "mnemonic".chars().chain(passphrase.nfkd()) with that helper would replace the hand-rolled length sum, buffer and scratch array at key-wallet/src/mnemonic.rs:171-178. This follows the repository's "Reuse before you add" rule. The current code is correct, so the change is optional."
  • Kept: "The new seed tests repeat existing vectors and pass equally without the change" (suggestion, medium confidence): "suggestion. The new tests do check the hand-written PBKDF2 against known vectors and against the bip39 crate, so they fail if the new derivation breaks. That makes them meaningful equivalence tests. No test checks the wiping itself, and some English TREZOR vectors appear to repeat existing tests in mnemonic.rs. Both are coverage and duplication issues, which are graded suggestion at most."

Timing:

  • Parse: 4.6s
  • Review agents: 117.0s
  • Judge: 89.5s
  • Total: 211.1s

@codecov

codecov Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.66%. Comparing base (470e4e7) to head (966df23).
⚠️ Report is 2 commits behind head on dev.

Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #1393   +/-   ##
=======================================
  Coverage   85.66%   85.66%           
=======================================
  Files         268      268           
  Lines       70259    70290   +31     
=======================================
+ Hits        60189    60217   +28     
- Misses      10070    10073    +3     
Flag Coverage Δ
core 82.80% <ø> (ø)
rpc 52.10% <ø> (ø)
spv 94.38% <ø> (-0.01%) ⬇️
wallet 83.52% <100.00%> (-0.02%) ⬇️
Files with missing lines Coverage Δ
key-wallet/src/mnemonic.rs 99.73% <100.00%> (-0.01%) ⬇️

... and 7 files with indirect coverage changes

manki-review[bot]
manki-review Bot previously approved these changes Nov 11, 2026

@manki-review manki-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved. 1 warning and 2 suggestions, none of which block.

What this does: Mnemonic::to_seed no longer calls the bip39 crate, which leaves copies of the passphrase and intermediate hash values in memory. It now runs its own BIP-39 seed derivation, which keeps the salt, round values and result in buffers that are wiped when dropped.


What to test

The review model wrote these steps. Check what a step runs before you follow it.

Setup: Build key-wallet with cargo test -p key-wallet --all-features.

  1. Derive the seed of abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about with passphrase TREZOR. Expect c55257c3...7463b04.
  2. Derive the same phrase with an empty passphrase. Expect 5eb00bbd...ce9e38e4.
  3. Restore an existing wallet from its mnemonic and passphrase. Expect the same master key and addresses as before the change.
  4. Parse a Japanese phrase separated by ideographic spaces (U+3000) and derive with passphrase ㍍ガバヴァぱばぐゞちぢ十人十色. Expect the published Japanese vector seed.
  5. Derive a French phrase given in NFC form and the same phrase in NFKD form. Expect identical seeds.
  6. Edge case: use a 24-word English phrase longer than 128 bytes. Expect the same seed as bip39::Mnemonic::to_seed.
  7. Edge case: use passphrases with compatibility characters such as \u{ff21}\u{fb01} and an emoji. Expect the same seed as bip39::Mnemonic::to_seed.
About this review
  • Reviewed 3391a92, round 1
  • 400 changed lines read in 3m 31s
  • Found by claude-sonnet-5-5 and claude-opus-5-5, judged by claude-opus-5-5
  • Tokens: 1.2M in (874k from cache) · 22k out · about $1.74 at API prices
  • How Manki reviews

Comment thread key-wallet/src/mnemonic.rs Resolved
Comment thread key-wallet/src/mnemonic.rs Resolved
Comment thread key-wallet/src/mnemonic_tests.rs Resolved
The seed salt is now built with collect_zeroizing, which already collects chars into a wiped buffer at its final size, so the hand-written salt loop and its UTF-8 scratch go away.

The English BIP-39 vector set moves into test_bip39_test_vectors, which now checks the phrase, word count and seed of all 24 vectors from their entropy. The 18- and 24-word tests and the English seed table repeated six of those vectors and are removed. A note on the seed tests says they guard seed compatibility.

The doc comment of pbkdf2_hmac_sha512_one_block now says that each round's engine clone and the value finalize returns are not wiped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@manki-review

manki-review Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

✅ Review complete in 3m 17s

Planner (5s)
    feat · 480 lines · 2 agents
    judge effort: high

Review (security · pair): 3 findings
    ✅ Claude Sonnet 5.5 · high: 0 findings (28s)
    ✅ Claude Opus 5.5 · high: 3 findings (1m 29s)

Judge: 1 kept · 2 dropped (1m 12s)
    kept: 1 warning
    dropped: 1 suggestion · 1 nitpick

Review metadata

Config:

  • Models: reviewer=claude-sonnet-5-5, judge=claude-opus-5-5
  • Triage: trivial=false, subtle=true, paired=true (planner, security-sensitive paths)
  • Team: Claude Sonnet 5.5 · high, Claude Opus 5.5 · high
  • Memory: enabled (central)

Account limits:

  • Claude subscription: weekly 15% (resets 2026-11-17 05:00 UTC)

Judge decisions:

  • Kept: "Copies of the keyed HMAC state and the round values stay on the stack unwiped" (warning, medium confidence): "warning, kept from round 1 (P1). The only change at this spot is the new doc comment at key-wallet/src/mnemonic.rs:177-178, which states the limit. The behaviour is unchanged. hmac.engine.clone() at :185 and :193 creates a plain local that finalize() consumes at :189 and :195, and the returned Hmac temporary is never erased. Both hold state derived from the phrase. The round-1 doubt about whether finalize erases is settled by the author's own comment at :177-178, which says it does not. The PR description still says the round values and the keyed engine sit in wiped buffers, so readers get a stronger guarantee than the code gives. This is memory hygiene with no outside-input path, so it is not a blocker. It is still strictly better than the previous bip39 call, which wiped nothing."
  • Dropped: "No added test fails without the fix" (ignore, high confidence): "ignore. This is the round-1 concern P3. Its fix was to keep one copy of the vectors and note that the tests guard seed compatibility, not the wiping. The author did both: the English vectors are now a single TREZOR_VECTORS table in mnemonic.rs, and the note sits at key-wallet/src/mnemonic_tests.rs:221-222. A test cannot observe whether memory was wiped. The remaining ask is a PR description or title change, which never blocks, so raising it again would reverse the earlier fix."
  • Dropped: "Doc comment on pbkdf2_hmac_sha512_one_block is longer than the three-line limit" (ignore, high confidence): "nitpick. The doc comment at key-wallet/src/mnemonic.rs:175-178 is four /// lines, and AGENTS.md sets three as the ceiling. This is a comment convention, so it is cosmetic."

Timing:

  • Parse: 7.5s
  • Review agents: 116.7s
  • Judge: 72.4s
  • Total: 196.6s

Last reviewed 966df23 · head 966df23 · up to date

  • Pause automatic reviews
  • Review again
  • Deeper review

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Waiting for bot review — coderabbitai not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added waiting-bots Waiting for the review bots to report on this head and removed waiting-self-review Waiting for the author to post /self-reviewed bot-review-skipped A required review bot did not report; it was skipped by the window or by a person. labels Nov 11, 2026

@manki-review manki-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved.

What this does: Turning a recovery phrase into a wallet seed used to leave copies of secret data in memory. The seed is now computed in this crate, and the passphrase buffer, the intermediate values and the result are wiped after use.


What to test

The review model wrote these steps. Check what a step runs before you follow it.

Setup: A Rust toolchain and a checkout of the branch.

  1. Run cargo test -p key-wallet --all-features mnemonic. Expect every test, including test_bip39_test_vectors and test_bip39_seed_japanese_vectors, to pass.
  2. Call Mnemonic::from_phrase with the 12-word abandon ... about phrase, then to_seed("TREZOR"). Expect the hex c55257c360c07c72...7463b04.
  3. Derive a seed from an existing wallet's phrase and passphrase on the base branch and on this branch. Expect the same 64 bytes and the same addresses.
  4. Parse a Japanese phrase that uses ideographic spaces and pass a passphrase with ㍍. Expect the reference seed from the BIP-39 Japanese vectors.
  5. Edge case: use a 24-word phrase whose text is longer than 128 bytes. Expect the same seed as bip39::Mnemonic::to_seed.
  6. Edge case: use passphrases in NFC and in NFD form, for example Åé. Expect both to give the same seed.
About this review
  • Reviewed 966df23, round 2
  • 480 changed lines read in 3m 17s
  • Found by claude-sonnet-5-5 and claude-opus-5-5, judged by claude-opus-5-5
  • Tokens: 929k in (635k from cache) · 20k out · about $1.74 at API prices
  • How Manki reviews

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Bots are done — your move: post /self-reviewed.
Full checklist in the description.

@github-actions github-actions Bot added waiting-self-review Waiting for the author to post /self-reviewed and removed waiting-bots Waiting for the review bots to report on this head labels Nov 11, 2026
@PastaPastaPasta

Copy link
Copy Markdown
Member Author

/self-reviewed 966df23

@github-actions github-actions Bot removed the waiting-self-review Waiting for the author to post /self-reviewed label Nov 11, 2026
@ZocoLini
ZocoLini merged commit d275dd3 into dev Nov 12, 2026
56 of 62 checks passed
@ZocoLini
ZocoLini deleted the pasta/key-wallet-bip39-seed-wiped-buffers branch November 12, 2026 13:40
manki-review Bot added a commit to manki-review/review-memory that referenced this pull request Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants