Skip to content

feat(storage): version PIN KDF hardening - #335

Draft
BitHighlander wants to merge 1 commit into
developfrom
agent/version-pin-kdf
Draft

feat(storage): version PIN KDF hardening#335
BitHighlander wants to merge 1 commit into
developfrom
agent/version-pin-kdf

Conversation

@BitHighlander

@BitHighlander BitHighlander commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Security goal

Restore a material offline work factor for the user PIN. Storage v16 reduced the production PBKDF2 count used for the PIN wrapping key from 100,000 to 10.

Change

  • introduces storage v19 and an explicit pin_kdf_v2 selector in flags bit 20
  • uses 100,000 iterations for v19 production builds and 1,000 for debug/emulator builds
  • unwraps existing v15/v16 wallets with their original parameters
  • only after a correct PIN, rewraps the storage key with v19 and persists the selector
  • creates new PINs directly with v19
  • leaves wipe-code and authdata derivation unchanged pending their own versioned migrations

Evidence

  • clean isolated Docker build
  • direct make xunit execution: firmware 390/390, board 2/2, crypto 4/4, Pallas constant-time 7/7
  • wrong-PIN regression proves the wrapped key and migration flags do not change
  • v16-to-v19 regression proves return state, selector, wrapped-key replacement, and successful v19 unwrap
  • v19 serialization round-trips the selector; the v18 reader ignores it
  • negative control: disabling rewrap makes the targeted test fail four assertions and exits 1
  • release device build passed (firmware.keepkey.bin: 650,196 bytes)
  • bitcoin-only release build passed (firmware.keepkey.bin: 361,588 bytes)

Draft blockers

Do not merge for production until all of these are resolved:

  • anti-rollback bootloader/security-epoch policy is implemented and proven, because older signed firmware cannot read storage v19 safely
  • 100,000-iteration unlock latency and watchdog margin are measured on every supported hardware revision
  • v15/v16/v18 migration and power loss at each commit boundary are exercised on real devices
  • downgrade attempts after migration are shown to fail closed without modifying storage

The design and release ordering are documented in docs/security/pin-kdf-v19-migration.md; the wider hardening sequence and anti-rollback RFC are in #334.

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.

1 participant