From 987bc796703b9e206f981940845e0f35a17468cb Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Nov 2026 15:12:29 -0500 Subject: [PATCH] Password math v2: fix collisions and bias before first use 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 Claude-Session: https://claude.ai/code/session_01QSQZn3X5gDJdRjbqMfKRpd --- SecretKey.Core.Tests/CryptoTests.cs | 69 ++++--- .../PasswordDerivationTests.cs | 112 +++++++++++ .../PasswordDerivationV1Tests.cs | 110 ----------- .../{V1TestHelper.cs => TestHelper.cs} | 25 ++- SecretKey.Core/Crypto.cs | 179 ++++++++++++++---- SecretKey.Core/Processor.cs | 15 +- SecretKey.Core/SecretKey.Core.csproj | 5 + SecretKey/Program.cs | 23 ++- docs/password-derivation.md | 73 +++++++ 9 files changed, 404 insertions(+), 207 deletions(-) create mode 100644 SecretKey.Core.Tests/PasswordDerivationTests.cs delete mode 100644 SecretKey.Core.Tests/PasswordDerivationV1Tests.cs rename SecretKey.Core.Tests/{V1TestHelper.cs => TestHelper.cs} (68%) create mode 100644 docs/password-derivation.md diff --git a/SecretKey.Core.Tests/CryptoTests.cs b/SecretKey.Core.Tests/CryptoTests.cs index 08dd304..3efa2a5 100644 --- a/SecretKey.Core.Tests/CryptoTests.cs +++ b/SecretKey.Core.Tests/CryptoTests.cs @@ -1,57 +1,72 @@ -using System.Text; using SecretKey.Core; +using static SecretKey.Core.Tests.TestHelper; namespace SecretKey.Core.Tests; /// -/// Known-answer tests for the building blocks in Crypto.cs. -/// If any of these fail, previously generated passwords can no longer be reproduced. +/// Tests for the building blocks of the password math (docs/password-derivation.md). /// public class CryptoTests { [Fact] - public void MonthlyMasterKey_IsSha256OfRootKeyTextPlusDateCode() + public void MonthlyKey_IsKnownValue() { - byte[] key = Crypto.DeriveMonthlyMasterKey(V1TestHelper.TestRootKey, "2611"); - - Assert.Equal("4E0F0B5B77491DCA67A584A58EC1F6D4859775346265F8C03B51878FE2CF8A12", Convert.ToHexString(key)); + Assert.Equal("D38F4A15A5783BA78B9A80FF2D2AA0FA8086E6AB88D33C9A20206978658A3BB6", Convert.ToHexString(MonthlyKey("2611"))); + Assert.Equal("A516AF24CE369E121466A7FD928EC7170CC44590FC6DAAC0E1B77DFD326C9702", Convert.ToHexString(MonthlyKey("2612"))); } [Fact] - public void HmacSha256_MatchesRfc4231TestCase2() + public void RootKey_IgnoresLetterCaseAndSurroundingSpaces() { - byte[] mac = Crypto.HmacSha256(Encoding.ASCII.GetBytes("Jefe"), Encoding.ASCII.GetBytes("what do ya want for nothing?")); + byte[] expected = MonthlyKey("2611"); - Assert.Equal("5BDCC146BF60754E6A042426089575C75A003F089D2739839DEC58B964EC3843", Convert.ToHexString(mac)); + Assert.Equal(expected, Crypto.DeriveMonthlyMasterKey(TestRootKey.ToLowerInvariant(), "2611")); + Assert.Equal(expected, Crypto.DeriveMonthlyMasterKey(" " + TestRootKey + "\n", "2611")); } - [Fact] - public void HmacSha256_OfAccountBlock_IsStable() + [Theory] + [InlineData("")] + [InlineData("REPLACE_WITH_YOUR_ROOT_KEY")] + [InlineData("000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1")] // 63 characters + [InlineData("000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F00")] // 66 characters + [InlineData("G00102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F")] // not hexadecimal + public void RootKey_ThatIsNot32HexBytes_IsRejected(string badKey) { - byte[] key = Crypto.DeriveMonthlyMasterKey(V1TestHelper.TestRootKey, "2611"); - var block = new byte[32]; // v1: title + url + username, UTF-8, cut or zero-padded to 32 bytes - byte[] text = Encoding.UTF8.GetBytes("Bank" + "https://bank.example" + "ed"); - Array.Copy(text, block, text.Length); - - Assert.Equal("0F803F563CA1F44777139CCC4BB04B81DA0373509D3D28FC76E896BB234AD5C9", Convert.ToHexString(Crypto.HmacSha256(key, block))); + Assert.Throws(() => Crypto.DeriveMonthlyMasterKey(badKey, "2611")); } [Fact] - public void MapBlobToPattern_MapsEachMaskTokenFromOneHashByte() + public void EncodeFields_WritesBigEndianLengthThenUtf8() { - byte[] bytes = Enumerable.Range(0, 32).Select(i => (byte)i).ToArray(); + Assert.Equal( + new byte[] { 0, 0, 0, 1, (byte)'a', 0, 0, 0, 0, 0, 0, 0, 2, 0xC3, 0xA9 }, + Crypto.EncodeFields("a", "", "é")); + } - // X -> A-Z, x -> a-z, N -> 0-9, S -> "!@#$%&*()-_=+[]{}<>?", anything else is copied as-is. - // A literal still uses up a hash byte (v1 behavior). - Assert.Equal("Ab2$-Fg7)", Crypto.MapBlobToPattern(bytes, "XxNS-XxNS")); + [Theory] + [InlineData("X", new byte[] { 234, 255, 0 }, "A")] // 234 and 255 are skipped for 26-letter sets + [InlineData("x", new byte[] { 233 }, "z")] // 233 is the highest accepted byte: 233 mod 26 = 25 + [InlineData("N", new byte[] { 250, 249 }, "9")] // digits accept bytes below 250 + [InlineData("S", new byte[] { 240, 239 }, "?")] // symbols accept bytes below 240 + [InlineData("X-x.N", new byte[] { 0, 1, 2 }, "A-b.2")] // other characters are copied and use no bytes + public void MapStreamToMask_SkipsBiasedBytes(string mask, byte[] stream, string expected) + { + Assert.Equal(expected, Crypto.MapStreamToMask(stream, mask)); } [Fact] - public void MapBlobToPattern_WrapsAfter32Characters_V1Behavior() + public void MapStreamToMask_FailsLoudlyIfStreamRunsOut() { - byte[] bytes = Enumerable.Range(0, 32).Select(i => (byte)i).ToArray(); + Assert.Throws(() => Crypto.MapStreamToMask(new byte[] { 255 }, "x")); + } - // Known v1 weakness: mask positions 33+ reuse the same 32 hash bytes. - Assert.Equal("0123456789012345678901234567890101234567", Crypto.MapBlobToPattern(bytes, new string('N', 40))); + [Fact] + public void NormalizeUrl_AddsHttpsOnlyWhenNoScheme() + { + Assert.Equal("", Crypto.NormalizeUrl(" ")); + Assert.Equal("https://paramountplus.com", Crypto.NormalizeUrl(" paramountplus.com ")); + Assert.Equal("https://httpbin.org", Crypto.NormalizeUrl("httpbin.org")); + Assert.Equal("http://example.org", Crypto.NormalizeUrl("http://example.org")); + Assert.Equal("HTTPS://Example.com", Crypto.NormalizeUrl("HTTPS://Example.com")); } } diff --git a/SecretKey.Core.Tests/PasswordDerivationTests.cs b/SecretKey.Core.Tests/PasswordDerivationTests.cs new file mode 100644 index 0000000..d466894 --- /dev/null +++ b/SecretKey.Core.Tests/PasswordDerivationTests.cs @@ -0,0 +1,112 @@ +using static SecretKey.Core.Tests.TestHelper; + +namespace SecretKey.Core.Tests; + +/// +/// Locks the passwords SecretKey produces (password math version 2, docs/password-derivation.md). +/// +/// Why this exists: the whole point of SecretKey is that the same root key and date code +/// give the same passwords forever. If any test here fails, a code change has altered +/// users' passwords. Do not "fix" the expected values to make a test pass. Change the +/// code back, or put the new behavior behind an explicit new version. +/// +public class PasswordDerivationTests +{ + [Theory] + [InlineData("Bhphotovideo", "https://www.bhphotovideo.com", "email@sample.com", DefaultMask, "2611", "Fiipc3]jpv38")] + [InlineData("Bhphotovideo", "https://www.bhphotovideo.com", "email@sample.com", DefaultMask, "2612", "Fnisb8-erb99")] + [InlineData("Paramount+", "paramountplus.com", "email@yahoo.com", DefaultMask, "2611", "Xxkch8{gnc91")] + [InlineData("Paramount+", "paramountplus.com", "email@yahoo.com", "xxxxxxxxNNNN", "2611", "hleziocv3322")] + [InlineData("MTA eTix", "https://www.mta.info/", "email@sample.com", DefaultMask, "2611", "Qlljp5[oht46")] + [InlineData("Solterra", "", "email@sample.com", DefaultMask, "2611", "Iuxxy3$rud15")] + [InlineData("Old Site", "http://example.org", "me", DefaultMask, "2611", "Xipxr9[mxi91")] + [InlineData("PayPal", "WWW.PayPal.com", "ed", DefaultMask, "2611", "Hggpe8_fvq80")] + [InlineData("Httpbin", "httpbin.org", "me", DefaultMask, "2611", "Egtku9-cfo98")] + [InlineData("Café", "https://café.example", "josé", DefaultMask, "2611", "Iuenu3{gbu25")] + [InlineData("Bank", "https://bank.example", "ed", "Xxx-NNN.x", "2611", "Haj-814.w")] + [InlineData("Long", "https://long.example", "me", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "2611", "ilfatcuwqmrjhrcjasefmjhhaewksivvwvzbnqgt")] + public void KnownAccounts_ProduceKnownPasswords(string title, string url, string username, string mask, string dateCode, string expected) + { + Assert.Equal(expected, Password(title, url, username, mask, dateCode)); + } + + [Fact] + public void DifferentLoginsOnTheSameSite_GetDifferentPasswords() + { + // v1 gave both of these the same password because only the first 32 bytes counted. + Assert.Equal("Ahluk3(oqe46", Password("Bhphotovideo", "https://www.bhphotovideo.com", "alice@sample.com")); + Assert.Equal("Yzlls2>wli85", Password("Bhphotovideo", "https://www.bhphotovideo.com", "bob@other.org")); + } + + [Fact] + public void FieldsCannotRunTogether() + { + // v1 gave ("ab", "", "c") and ("a", "", "bc") the same password. + Assert.Equal("Snapz9[amp36", Password("ab", "", "c")); + Assert.Equal("Yreib0$zwl99", Password("a", "", "bc")); + } + + [Fact] + public void LongMask_DoesNotRepeat() + { + string password = Password("Long", "https://long.example", "me", new string('x', 40)); + + Assert.NotEqual(password[..8], password[32..]); + } + + [Fact] + public void ChangingTheMask_GivesAnUnrelatedPassword() + { + Assert.Equal("hzfqhyct", Password("Masks", "https://masks.example", "me", "xxxxxxxx")); + Assert.Equal("gxsjunbz69", Password("Masks", "https://masks.example", "me", "xxxxxxxxNN")); + } + + [Fact] + public void AccentsTypedEitherWay_GiveTheSamePassword() + { + // "é" as one character (U+00E9) or as "e" + combining accent (U+0301). + Assert.Equal( + Password("Café", "https://café.example", "josé"), + Password("Café", "https://café.example", "josé")); + } + + [Fact] + public void Csv_ProducesNormalizedFieldsAndPasswords() + { + string[] lines = Run(new[] + { + Row("Paramount+", "paramountplus.com", "email@yahoo.com"), + Row(" Padded ", " example.com ", " user "), + "\" Padded \",\" example.com \",\" user \",,,false,false,,", + "\"Smith, John Bank\",https://bank.example,john,,,false,false,,", + Row("Café", "https://café.example", "josé"), + }); + + Assert.Equal(new[] + { + OutputHeader, + "Paramount+,https://paramountplus.com,email@yahoo.com,Xxkch8{gnc91", + "Padded,https://example.com,user,Mbcza0=lmb30", + "Padded,https://example.com,user,Mbcza0=lmb30", + "\"Smith, John Bank\",https://bank.example,john,Ykiid5=rrm94", + "Café,https://café.example,josé,Iuenu3{gbu25", + }, lines); + } + + [Fact] + public void SampleInputFile_ProducesKnownOutput() + { + // Solterra's "passwordmask=" note is not applied yet, so it gets the default mask. + string sample = Path.Combine(AppContext.BaseDirectory, "TestData", "sample_input.csv"); + string[] rows = File.ReadAllLines(sample).Skip(1).ToArray(); + + Assert.Equal(new[] + { + OutputHeader, + "Bhphotovideo,https://www.bhphotovideo.com,email@sample.com,Fiipc3]jpv38", + "Paramount+,https://paramountplus.com,email@yahoo.com,Xxkch8{gnc91", + "Solterra,,email@sample.com,Iuxxy3$rud15", + "MTA eTix,https://www.mta.info/,email@sample.com,Qlljp5[oht46", + }, Run(rows)); + } +} diff --git a/SecretKey.Core.Tests/PasswordDerivationV1Tests.cs b/SecretKey.Core.Tests/PasswordDerivationV1Tests.cs deleted file mode 100644 index fb26de1..0000000 --- a/SecretKey.Core.Tests/PasswordDerivationV1Tests.cs +++ /dev/null @@ -1,110 +0,0 @@ -using static SecretKey.Core.Tests.V1TestHelper; - -namespace SecretKey.Core.Tests; - -/// -/// Locks the passwords SecretKey v1.0.0 produces, end to end (CSV in, CSV out). -/// -/// Why this exists: the whole point of SecretKey is that the same root key and date code -/// give the same passwords forever. If any test here fails, a code change has altered -/// users' passwords. Do not "fix" the expected values to make a test pass — change the -/// code back, or put the new behavior behind an explicit, opt-in new version. -/// -public class PasswordDerivationV1Tests -{ - [Theory] - [InlineData("Bhphotovideo", "https://www.bhphotovideo.com", "email@sample.com", DefaultMask, "2611", - "Bhphotovideo,https://www.bhphotovideo.com,email@sample.com,Wocqe8 -/// Shared setup for the v1 known-answer tests. -/// Every expected value in this project was produced by the v1.0.0 engine and -/// cross-checked against an independent implementation of the same algorithm. +/// Shared setup for the password tests. +/// Every expected password in this project was produced by the engine and independently +/// re-computed from docs/password-derivation.md by a separate implementation. /// -internal static class V1TestHelper +internal static class TestHelper { // TEST-ONLY root key. Never use this for real passwords. public const string TestRootKey = "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F"; @@ -18,6 +18,12 @@ internal static class V1TestHelper public const string InputHeader = "Title,Url,Username,Password,OTPAuth,Favorite,Archived,Tags,Notes"; public const string OutputHeader = "Title,Url,Username,Password"; + public static byte[] MonthlyKey(string dateCode = DateCode) => + Crypto.DeriveMonthlyMasterKey(TestRootKey, dateCode); + + public static string Password(string title, string url, string username, string mask = DefaultMask, string dateCode = DateCode) => + Crypto.GeneratePassword(MonthlyKey(dateCode), title, url, username, mask); + /// Builds an unquoted input row in the 1Password-style column order the engine reads. public static string Row(string title, string url, string username) => $"{title},{url},{username},,,false,false,,"; @@ -36,7 +42,7 @@ public static string[] Run(IEnumerable inputRows, string mask = DefaultM string output = Path.Combine(dir, "output.csv"); File.WriteAllLines(input, new[] { InputHeader }.Concat(inputRows)); - Processor.Process(input, output, Crypto.DeriveMonthlyMasterKey(TestRootKey, dateCode), mask); + Processor.Process(input, output, MonthlyKey(dateCode), mask); return File.ReadAllLines(output); } @@ -45,13 +51,4 @@ public static string[] Run(IEnumerable inputRows, string mask = DefaultM Directory.Delete(dir, recursive: true); } } - - /// Runs one account through the engine and returns its output line. - public static string OutputLineFor(string title, string url, string username, string mask = DefaultMask, string dateCode = DateCode) - { - string[] lines = Run(new[] { Row(title, url, username) }, mask, dateCode); - Assert.Equal(2, lines.Length); - Assert.Equal(OutputHeader, lines[0]); - return lines[1]; - } } diff --git a/SecretKey.Core/Crypto.cs b/SecretKey.Core/Crypto.cs index 4f88c1f..67f3fb5 100644 --- a/SecretKey.Core/Crypto.cs +++ b/SecretKey.Core/Crypto.cs @@ -1,64 +1,169 @@ using System; +using System.Buffers.Binary; +using System.Collections.Generic; using System.Security.Cryptography; using System.Text; namespace SecretKey.Core; +/// +/// SecretKey password math, version 2. The exact specification is in docs/password-derivation.md. +/// +/// Changing anything in this file changes users' passwords. The known-answer tests in +/// SecretKey.Core.Tests must keep passing; a deliberate change must become a new version. +/// public static class Crypto { + public const int RootKeyByteLength = 32; + + private const string Upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"; + private const string Lower = "abcdefghijklmnopqrstuvwxyz"; + private const string Digits = "0123456789"; + private const string Specials = "!@#$%&*()-_=+[]{}<>?"; + + private const string MonthlyKeyLabel = "SecretKey v2 monthly key "; + private const string PasswordLabel = "SecretKey v2 password"; + + /// + /// Derives the month's key: HKDF-SHA256 over the 32-byte root key, with the date code in the info. + /// + /// The root key as 64 hexadecimal characters (either case; surrounding spaces ignored). + /// The date code, used exactly as given. public static byte[] DeriveMonthlyMasterKey(string rootKey, string dateCode) { - if (rootKey == null) throw new ArgumentNullException(nameof(rootKey)); - if (dateCode == null) throw new ArgumentNullException(nameof(dateCode)); + ArgumentNullException.ThrowIfNull(rootKey); + ArgumentNullException.ThrowIfNull(dateCode); + + byte[] root = ParseRootKey(rootKey); + try + { + byte[] info = Encoding.UTF8.GetBytes(MonthlyKeyLabel + dateCode); + return HKDF.DeriveKey(HashAlgorithmName.SHA256, root, 32, Array.Empty(), info); + } + finally + { + CryptographicOperations.ZeroMemory(root); + } + } + + /// + /// Generates one account's password from the month's key, the account fields and the mask. + /// Fields are normalized first (see and ). + /// + public static string GeneratePassword(byte[] monthlyKey, string title, string url, string username, string mask) + { + ArgumentNullException.ThrowIfNull(monthlyKey); + ArgumentNullException.ThrowIfNull(mask); + + byte[] accountInput = EncodeFields(PasswordLabel, NormalizeField(title), NormalizeUrl(url), NormalizeField(username), mask); + return MapStreamToMask(PasswordStream(monthlyKey, accountInput), mask); + } + + /// Removes surrounding whitespace and applies Unicode NFC normalization. + public static string NormalizeField(string? value) => + (value ?? string.Empty).Trim().Normalize(NormalizationForm.FormC); + + /// Normalizes like any field, then adds "https://" when a non-empty URL has no http:// or https:// prefix. + public static string NormalizeUrl(string? url) + { + string normalized = NormalizeField(url); + if (normalized.Length > 0 + && !normalized.StartsWith("http://", StringComparison.OrdinalIgnoreCase) + && !normalized.StartsWith("https://", StringComparison.OrdinalIgnoreCase)) + { + normalized = "https://" + normalized; + } + return normalized; + } - string combined = rootKey + dateCode; - using var sha = SHA256.Create(); - return sha.ComputeHash(Encoding.UTF8.GetBytes(combined)); + internal static byte[] ParseRootKey(string rootKey) + { + string hex = rootKey.Trim(); + if (hex.Length != RootKeyByteLength * 2 || !hex.All(char.IsAsciiHexDigit)) + { + throw new ArgumentException( + "The root key must be exactly 64 hexadecimal characters (a 32-byte key). Use \"Generate New Key\" to create one."); + } + return Convert.FromHexString(hex); } - public static byte[] HmacSha256(byte[] key, byte[] data) + /// Writes each string as a 4-byte big-endian length followed by its UTF-8 bytes. + internal static byte[] EncodeFields(params string[] fields) { - using var hmac = new HMACSHA256(key); - return hmac.ComputeHash(data); + var output = new List(); + Span length = stackalloc byte[4]; + foreach (string field in fields) + { + byte[] utf8 = Encoding.UTF8.GetBytes(field); + BinaryPrimitives.WriteUInt32BigEndian(length, (uint)utf8.Length); + output.AddRange(length.ToArray()); + output.AddRange(utf8); + } + return output.ToArray(); } - public static string MapBlobToPattern(byte[] hash, string mask) + /// + /// An endless deterministic byte stream: HMAC-SHA256(monthlyKey, accountInput || counter) for counter = 0, 1, 2, ... + /// (counter as a 4-byte big-endian number), concatenated. + /// + internal static IEnumerable PasswordStream(byte[] monthlyKey, byte[] accountInput) { - if (hash == null) throw new ArgumentNullException(nameof(hash)); - if (mask == null) throw new ArgumentNullException(nameof(mask)); + using var hmac = new HMACSHA256(monthlyKey); + byte[] block = new byte[accountInput.Length + 4]; + accountInput.CopyTo(block, 0); + + for (uint counter = 0; ; counter++) + { + BinaryPrimitives.WriteUInt32BigEndian(block.AsSpan(accountInput.Length), counter); + foreach (byte b in hmac.ComputeHash(block)) + { + yield return b; + } + } + } - ReadOnlySpan upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ".AsSpan(); - ReadOnlySpan lower = "abcdefghijklmnopqrstuvwxyz".AsSpan(); - ReadOnlySpan digits = "0123456789".AsSpan(); - ReadOnlySpan special = "!@#$%&*()-_=+[]{}<>?".AsSpan(); + /// + /// Builds the password from the mask: X = A-Z, x = a-z, N = 0-9, S = one of "!@#$%&*()-_=+[]{}<>?". + /// Each token takes the next stream byte that is below the largest multiple of its set size (others are skipped), + /// so every character in a set is equally likely. Any other mask character is copied as-is and uses no bytes. + /// + internal static string MapStreamToMask(IEnumerable stream, string mask) + { + var password = new StringBuilder(mask.Length); + using IEnumerator bytes = stream.GetEnumerator(); - var result = new char[mask.Length]; - int byteIndex = 0; - for (int i = 0; i < mask.Length; i++) + foreach (char token in mask) { - byte b = hash[byteIndex % hash.Length]; - char m = mask[i]; - switch (m) + string? set = token switch { - case 'X': - result[i] = upper[b % upper.Length]; - break; - case 'x': - result[i] = lower[b % lower.Length]; - break; - case 'N': - result[i] = digits[b % digits.Length]; - break; - case 'S': - result[i] = special[b % special.Length]; - break; - default: - result[i] = m; + 'X' => Upper, + 'x' => Lower, + 'N' => Digits, + 'S' => Specials, + _ => null, + }; + + if (set is null) + { + password.Append(token); + continue; + } + + int limit = 256 - (256 % set.Length); + while (true) + { + if (!bytes.MoveNext()) + { + throw new InvalidOperationException("The password byte stream ended unexpectedly."); + } + if (bytes.Current < limit) + { + password.Append(set[bytes.Current % set.Length]); break; + } } - byteIndex++; } - return new string(result); + return password.ToString(); } } diff --git a/SecretKey.Core/Processor.cs b/SecretKey.Core/Processor.cs index f28d68f..39d9397 100644 --- a/SecretKey.Core/Processor.cs +++ b/SecretKey.Core/Processor.cs @@ -38,18 +38,11 @@ public static void Process(string inputPath, string outputPath, byte[] monthlyMa { var parts = ParseCsvLine(lines[i]); if (parts.Count < 3) continue; - string title = parts.Count > 0 ? parts[0].Trim() : string.Empty; - string url = parts.Count > 1 ? parts[1].Trim() : string.Empty; - string username = parts.Count > 2 ? parts[2].Trim() : string.Empty; + string title = Crypto.NormalizeField(parts[0]); + string url = Crypto.NormalizeUrl(parts[1]); + string username = Crypto.NormalizeField(parts[2]); - if (!url.StartsWith("http", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrEmpty(url)) url = "https://" + url; - - var block = new byte[32]; - var bytes = Encoding.UTF8.GetBytes((title + url + username)); - Array.Copy(bytes, block, Math.Min(bytes.Length, block.Length)); - - var hash = Crypto.HmacSha256(monthlyMasterKey, block); - var password = Crypto.MapBlobToPattern(hash, passwordMask); + var password = Crypto.GeneratePassword(monthlyMasterKey, title, url, username, passwordMask); outLines.Add(JoinCsvLine(new[] { title, url, username, password })); diff --git a/SecretKey.Core/SecretKey.Core.csproj b/SecretKey.Core/SecretKey.Core.csproj index 93f5ab4..ad12dc6 100644 --- a/SecretKey.Core/SecretKey.Core.csproj +++ b/SecretKey.Core/SecretKey.Core.csproj @@ -6,4 +6,9 @@ enable + + + + + diff --git a/SecretKey/Program.cs b/SecretKey/Program.cs index 5263aee..14e48f6 100644 --- a/SecretKey/Program.cs +++ b/SecretKey/Program.cs @@ -66,15 +66,22 @@ static void Main(string[] args) Console.WriteLine($"Root Key: {rootPreview}"); Console.WriteLine("--------------------------------"); - // Derive Monthly Master Key - var masterKey = Crypto.DeriveMonthlyMasterKey(config?.RootKey ?? string.Empty, dateCode); + try + { + // Derive Monthly Master Key + var masterKey = Crypto.DeriveMonthlyMasterKey(config?.RootKey ?? string.Empty, dateCode); - // Run processor with configurable mask/length from config - Processor.Process( - config?.InputPath ?? string.Empty, - config?.OutputPath ?? string.Empty, - masterKey, - config?.PasswordMask ?? "XxxxxNSxxxNN"); + // Run processor with configurable mask/length from config + Processor.Process( + config?.InputPath ?? string.Empty, + config?.OutputPath ?? string.Empty, + masterKey, + config?.PasswordMask ?? "XxxxxNSxxxNN"); + } + catch (ArgumentException ex) + { + Console.WriteLine($"Error: {ex.Message}"); + } } else { diff --git a/docs/password-derivation.md b/docs/password-derivation.md new file mode 100644 index 0000000..29d6a8e --- /dev/null +++ b/docs/password-derivation.md @@ -0,0 +1,73 @@ +# How SecretKey derives passwords (version 2) + +This is the exact recipe SecretKey uses. With it, anyone holding the root key and date code can regenerate the passwords, even without this app. The known-answer tests in `SecretKey.Core.Tests` lock it; a change to anything here must become a new version, never an edit to this one. + +## Inputs + +- **Root key**: 64 hexadecimal characters (upper or lower case), decoded to 32 bytes. Surrounding whitespace is ignored. Anything else is rejected. +- **Date code**: a string such as `2611`, used exactly as given. +- **Per account**: Title, URL and Username from the input CSV. +- **Mask**: the password pattern, e.g. `XxxxxNSxxxNN`. + +## Step 1: monthly key + +``` +monthlyKey = HKDF-SHA256(IKM = rootKey (32 bytes), + salt = empty, + info = UTF-8("SecretKey v2 monthly key " + dateCode), + L = 32) +``` + +HKDF is defined in RFC 5869. An empty salt means a salt of 32 zero bytes. + +## Step 2: normalize the account fields + +For Title, URL and Username: + +1. Remove leading and trailing whitespace. +2. Apply Unicode normalization form C (NFC), so "é" typed as one character or as "e" plus an accent gives the same result. + +Then, if the URL is not empty and does not start with `http://` or `https://` (case-insensitive), prefix it with `https://`. Letter case is otherwise kept as typed. + +Changing any of Title, URL, Username or the mask changes that account's password. + +## Step 3: account input + +Write these five strings, in order, each as a 4-byte big-endian length followed by its UTF-8 bytes: + +1. `SecretKey v2 password` +2. Title +3. URL +4. Username +5. Mask + +Call the result `accountInput`. + +## Step 4: byte stream + +``` +stream = HMAC-SHA256(monthlyKey, accountInput || BE32(0)) + || HMAC-SHA256(monthlyKey, accountInput || BE32(1)) + || ... +``` + +`BE32(n)` is `n` as a 4-byte big-endian number. Use as many blocks as needed. + +## Step 5: build the password from the mask + +Go through the mask one character at a time: + +| Mask character | Set (in this order) | Set size | Accept bytes below | +|---|---|---|---| +| `X` | `ABCDEFGHIJKLMNOPQRSTUVWXYZ` | 26 | 234 | +| `x` | `abcdefghijklmnopqrstuvwxyz` | 26 | 234 | +| `N` | `0123456789` | 10 | 250 | +| `S` | `!@#$%&*()-_=+[]{}<>?` | 20 | 240 | + +For `X`, `x`, `N` or `S`, take the next byte `b` from the stream. If `b` is below the limit in the table, output `set[b mod size]`; otherwise discard it and take the next byte. This makes every character in a set equally likely. + +Any other mask character is copied into the password as-is and uses no stream bytes. + +## What changed from version 1 (v1.0.0) + +Version 1 hashed only the first 32 bytes of Title+URL+Username, joined with no separator. Different logins on the same site could therefore get the same password, and so could accounts whose fields ran together. Version 1 also favored some characters slightly and repeated masks longer than 32 characters. Version 2 fixes all of these. Every password differs from version 1.