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.