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.