Skip to content

Password math v2: fix collisions and bias before first use - #3

Merged
edwest19 merged 1 commit into
mainfrom
engine/v2-password-math
Nov 5, 2026
Merged

edwest19 merged 1 commit into
mainfrom
engine/v2-password-math

Conversation

@edwest19

@edwest19 edwest19 commented Nov 5, 2026

Copy link
Copy Markdown
Owner

What this does

Replaces SecretKey's password math with a corrected version 2, before anyone starts using it. Every password SecretKey generates will be different from v1.0.0. That's intentional and safe, because no one has saved SecretKey passwords yet.

Why

The v1 math had four weaknesses (found in the evaluation, and locked by the tests from #2):

v1 problem Example v2
Only the first 32 bytes of title+URL+username counted alice@… and bob@… on bhphotovideo.com got the same password Every character counts → Ahluk3(oqe46 vs Yzlls2>wli85
Fields were joined with no separator (ab, c) and (a, bc) got the same password Fields are kept separate → different passwords
Some characters were slightly more likely e.g. A–V more often than W–Z Every character in a set is equally likely
Masks over 32 characters repeated x×40 = 32 letters + the first 8 again No repetition, any length

How v2 works

The exact recipe is in docs/password-derivation.md, so the passwords can be regenerated even without this app. In short:

  • Root key: must be 64 hex characters (what Generate New Key makes). It's read as a real 32-byte key. Anything else, including the REPLACE_WITH_YOUR_ROOT_KEY placeholder, is now rejected instead of silently producing weak passwords.
  • Monthly key: HKDF-SHA256 (the standard way to derive keys) from the root key and date code.
  • Per account: title, URL, username and mask, each length-prefixed. Spaces are trimmed, accents typed either way count the same, and https:// is added to bare URLs.
  • Characters: drawn from an HMAC-SHA256 stream, skipping bytes that would cause bias.

Files changed

  • SecretKey.Core/Crypto.cs: the new math.
  • SecretKey.Core/Processor.cs: calls the new math (CSV handling unchanged for now).
  • SecretKey/Program.cs: the command-line app prints a clear error for a bad root key instead of crashing. The UI already shows errors.
  • SecretKey.Core.Tests/: v1 tests replaced with 34 v2 tests (known passwords, plus tests proving each weakness above is gone).
  • docs/password-derivation.md: the spec.

How it was checked

  • Every expected value was re-computed by a separate implementation written only from the spec (all 25 matched). Its HKDF was itself checked against a standard crypto library and the RFC 5869 test vector.
  • Nine deliberate breaks of the math (no bias rejection, mask left out, no accent normalization, wrong label, wrong byte order, no length prefixes, old URL rule, literal characters using randomness, root key not decoded) were each caught by the tests.
  • The real xUnit run is the test check below (NuGet is blocked where this was written).

After merging

  • git pull on your PC.
  • If you've already generated a root key, it still works. Only the passwords it produces are new.

Generated by Claude Code

v1 hashed only the first 32 bytes of title+url+username with no
separator, so different logins on one site could share a password,
fields could run together, characters were slightly biased, and masks
over 32 characters repeated. Nobody depends on v1 passwords yet, so
this replaces it now, once, before the first release.

v2 (spec: docs/password-derivation.md):
- root key must be 64 hex chars and is decoded to 32 bytes; anything
  else (including the config.example placeholder) is rejected
- monthly key = HKDF-SHA256(root key, info = label + date code)
- account input = label, title, url, username, mask, each length-
  prefixed; fields are trimmed and NFC-normalized; URLs without
  http:// or https:// get https://
- password bytes = HMAC-SHA256(monthly key, input || counter) blocks
- each mask character uses rejection sampling, so picks are unbiased

Tests now lock v2. All expected values were re-computed by a separate
implementation written only from the spec, and nine deliberate breaks
of the math were each caught. The CLI reports a bad root key instead
of crashing; the UI already shows the error.

Every generated password changes from v1. This is intentional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QSQZn3X5gDJdRjbqMfKRpd
@edwest19
edwest19 merged commit d6c1a87 into main Nov 5, 2026
2 checks passed
@edwest19
edwest19 deleted the engine/v2-password-math branch November 6, 2026 03:16
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