From 2da284e042a687ee434acde84d62b3d097601d67 Mon Sep 17 00:00:00 2001 From: net0well Date: Thu, 22 Oct 2026 22:59:27 -0300 Subject: [PATCH 1/2] feat(core): add alter ego model, keyed digests and token registry Alter egos carry a mandatory placement and a decoy class (generic or unique), with severity defaults derived from the class. The constructor validates every field, so an invalid alter ego cannot exist. Decoy values are registered only as HMAC-SHA256 digests, with one subkey per trigger domain derived through HKDF from a key of at least 32 bytes. Reading the configuration therefore does not reveal which values are decoys, and the same value has a different digest in each domain. The registry is immutable, validates the whole set at once and reports every problem without echoing digests or values. Lookups by identifier and by raw value do not allocate. --- CHANGELOG.md | 10 + src/WalterEgo.Core/Domain/DecoyClass.cs | 19 ++ src/WalterEgo.Core/Domain/HoneyToken.cs | 153 ++++++++++ src/WalterEgo.Core/Domain/HoneyTokenId.cs | 63 ++++ src/WalterEgo.Core/Domain/HoneyTokenKind.cs | 28 ++ src/WalterEgo.Core/Domain/HoneyTokenRules.cs | 108 +++++++ src/WalterEgo.Core/Domain/Severity.cs | 19 ++ src/WalterEgo.Core/Domain/TriggerDomain.cs | 19 ++ src/WalterEgo.Core/PublicAPI.Unshipped.txt | 67 +++++ .../Registry/HoneyTokenRegistration.cs | 18 ++ src/WalterEgo.Core/Registry/HoneyTrigger.cs | 3 + src/WalterEgo.Core/Registry/ITokenRegistry.cs | 47 +++ src/WalterEgo.Core/Registry/RegistryError.cs | 6 + src/WalterEgo.Core/Registry/TokenRegistry.cs | 55 ++++ .../Registry/TokenRegistryBuilder.cs | 175 +++++++++++ .../Secrets/HmacSecretHasher.cs | 81 +++++ src/WalterEgo.Core/Secrets/ISecretHasher.cs | 23 ++ src/WalterEgo.Core/Secrets/SecretDigest.cs | 127 ++++++++ .../ChangingCollections.cs | 44 +++ .../HmacSecretHasherTests.cs | 119 ++++++++ .../WalterEgo.Core.Tests/HoneyTokenIdTests.cs | 64 ++++ tests/WalterEgo.Core.Tests/HoneyTokenTests.cs | 165 +++++++++++ .../WalterEgo.Core.Tests/SecretDigestTests.cs | 78 +++++ tests/WalterEgo.Core.Tests/TestKeys.cs | 9 + tests/WalterEgo.Core.Tests/TestRegistry.cs | 22 ++ .../TokenRegistryAllocationTests.cs | 44 +++ .../TokenRegistryBuilderTests.cs | 280 ++++++++++++++++++ .../TokenRegistryTests.cs | 142 +++++++++ 28 files changed, 1988 insertions(+) create mode 100644 src/WalterEgo.Core/Domain/DecoyClass.cs create mode 100644 src/WalterEgo.Core/Domain/HoneyToken.cs create mode 100644 src/WalterEgo.Core/Domain/HoneyTokenId.cs create mode 100644 src/WalterEgo.Core/Domain/HoneyTokenKind.cs create mode 100644 src/WalterEgo.Core/Domain/HoneyTokenRules.cs create mode 100644 src/WalterEgo.Core/Domain/Severity.cs create mode 100644 src/WalterEgo.Core/Domain/TriggerDomain.cs create mode 100644 src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs create mode 100644 src/WalterEgo.Core/Registry/HoneyTrigger.cs create mode 100644 src/WalterEgo.Core/Registry/ITokenRegistry.cs create mode 100644 src/WalterEgo.Core/Registry/RegistryError.cs create mode 100644 src/WalterEgo.Core/Registry/TokenRegistry.cs create mode 100644 src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs create mode 100644 src/WalterEgo.Core/Secrets/HmacSecretHasher.cs create mode 100644 src/WalterEgo.Core/Secrets/ISecretHasher.cs create mode 100644 src/WalterEgo.Core/Secrets/SecretDigest.cs create mode 100644 tests/WalterEgo.Core.Tests/ChangingCollections.cs create mode 100644 tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs create mode 100644 tests/WalterEgo.Core.Tests/HoneyTokenIdTests.cs create mode 100644 tests/WalterEgo.Core.Tests/HoneyTokenTests.cs create mode 100644 tests/WalterEgo.Core.Tests/SecretDigestTests.cs create mode 100644 tests/WalterEgo.Core.Tests/TestKeys.cs create mode 100644 tests/WalterEgo.Core.Tests/TestRegistry.cs create mode 100644 tests/WalterEgo.Core.Tests/TokenRegistryAllocationTests.cs create mode 100644 tests/WalterEgo.Core.Tests/TokenRegistryBuilderTests.cs create mode 100644 tests/WalterEgo.Core.Tests/TokenRegistryTests.cs diff --git a/CHANGELOG.md b/CHANGELOG.md index f660614..7af1f40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,3 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] + +### Added + +- `WalterEgo.Core`: alter ego model (`HoneyToken`) with a mandatory placement, a decoy class (generic or unique) + and severity defaults derived from the class. +- `WalterEgo.Core`: immutable token registry (`ITokenRegistry`) with allocation-free lookups by identifier and by + raw value. +- `WalterEgo.Core`: keyed digests of decoy values (`ISecretHasher`, `SecretDigest`): HMAC-SHA256 with a mandatory + key of at least 32 bytes and one derived subkey per trigger domain, so reading the configuration does not reveal + which values are decoys. diff --git a/src/WalterEgo.Core/Domain/DecoyClass.cs b/src/WalterEgo.Core/Domain/DecoyClass.cs new file mode 100644 index 0000000..dc730b3 --- /dev/null +++ b/src/WalterEgo.Core/Domain/DecoyClass.cs @@ -0,0 +1,19 @@ +namespace WalterEgo; + +/// +/// How much a trip of an alter ego can be trusted. +/// +public enum DecoyClass +{ + /// + /// A well-known decoy that any scanner finds without a leak, such as /.env or admin. + /// Its trips signal reconnaissance and carry low confidence. + /// + Generic = 1, + + /// + /// A decoy that can only be found through the place where it was planted. + /// Its trips signal that this place leaked and carry high confidence. + /// + Unique = 2, +} diff --git a/src/WalterEgo.Core/Domain/HoneyToken.cs b/src/WalterEgo.Core/Domain/HoneyToken.cs new file mode 100644 index 0000000..90b248d --- /dev/null +++ b/src/WalterEgo.Core/Domain/HoneyToken.cs @@ -0,0 +1,153 @@ +using System.Collections.Frozen; + +namespace WalterEgo; + +/// +/// An alter ego: a fake asset that no legitimate user has a reason to touch. A trip of an alter ego tells where +/// it was planted () and how much the trip can be trusted (). +/// +/// +/// An instance only carries metadata. The decoy values that trip the alter ego are never part of it, so it can be +/// copied into events, logs and alert channels safely. Instances are immutable and always valid. +/// +public sealed record HoneyToken +{ + /// + /// Creates an alter ego. + /// + /// The identifier of the alter ego. + /// The kind of asset the alter ego imitates. + /// Whether the alter ego is a generic decoy or a unique one. + /// + /// Where the alter ego was planted, such as "LEGACY_KEY variable in the CI of the orders repository". Up to 512 + /// characters, not blank, without control characters or line separators. + /// + /// The severity of a trip of the alter ego. + /// + /// A readable name. Up to 128 characters, not blank, without control characters or line separators. When + /// , the identifier is used. + /// + /// + /// An optional description. Up to 1024 characters, without control characters or line separators. + /// + /// + /// Optional tags. Up to 16 entries; keys are lowercase slugs of up to 32 characters; values are not blank, have up + /// to 128 characters and no control characters or line separators. The entries are copied. + /// + /// Any argument breaks the rules above, is the default + /// value, or an enumeration argument is not a defined value. + public HoneyToken( + HoneyTokenId id, + HoneyTokenKind kind, + DecoyClass decoyClass, + string placement, + Severity severity, + string? name = null, + string? description = null, + IReadOnlyDictionary? tags = null) + { + if (id.IsDefault) + { + throw new ArgumentException("The identifier is required.", nameof(id)); + } + + ThrowIfUndefined(HoneyTokenRules.IsDefined(kind), nameof(kind)); + ThrowIfUndefined(HoneyTokenRules.IsDefined(decoyClass), nameof(decoyClass)); + ThrowIfUndefined(HoneyTokenRules.IsDefined(severity), nameof(severity)); + ThrowIfInvalid(HoneyTokenRules.CheckPlacement(placement), nameof(placement)); + ThrowIfInvalid(HoneyTokenRules.CheckName(name), nameof(name)); + ThrowIfInvalid(HoneyTokenRules.CheckDescription(description), nameof(description)); + + // The copy is validated, not the argument, so a dictionary that changes after the check cannot slip invalid + // tags in. + var frozenTags = tags?.ToFrozenDictionary(StringComparer.Ordinal); + ThrowIfInvalid(HoneyTokenRules.CheckTags(frozenTags), nameof(tags)); + + Id = id; + Kind = kind; + Class = decoyClass; + Placement = placement; + Severity = severity; + Name = name ?? id.Value; + Description = description; + Tags = frozenTags ?? FrozenDictionary.Empty; + } + + /// Gets the identifier of the alter ego. + public HoneyTokenId Id { get; } + + /// Gets the kind of asset the alter ego imitates. + public HoneyTokenKind Kind { get; } + + /// Gets whether the alter ego is a generic decoy or a unique one. + public DecoyClass Class { get; } + + /// Gets the readable name, which is the identifier when no name was given. + public string Name { get; } + + /// Gets where the alter ego was planted. + public string Placement { get; } + + /// Gets the optional description. + public string? Description { get; } + + /// Gets the severity of a trip of the alter ego. + public Severity Severity { get; } + + /// Gets the tags, compared by ordinal keys. Empty when no tags were given. + public IReadOnlyDictionary Tags { get; } + + /// + /// Compares two alter egos by all their values, including the content of . + /// + /// The alter ego to compare with. + /// when both alter egos have the same values. + public bool Equals(HoneyToken? other) => + other is not null + && Id == other.Id + && Kind == other.Kind + && Class == other.Class + && Severity == other.Severity + && string.Equals(Name, other.Name, StringComparison.Ordinal) + && string.Equals(Placement, other.Placement, StringComparison.Ordinal) + && string.Equals(Description, other.Description, StringComparison.Ordinal) + && TagsEqual(Tags, other.Tags); + + /// + public override int GetHashCode() => + HashCode.Combine(Id, Kind, Class, Severity, Name, Placement, Description, Tags.Count); + + private static bool TagsEqual(IReadOnlyDictionary left, IReadOnlyDictionary right) + { + if (left.Count != right.Count) + { + return false; + } + + foreach (var (key, value) in left) + { + if (!right.TryGetValue(key, out var otherValue) || !string.Equals(value, otherValue, StringComparison.Ordinal)) + { + return false; + } + } + + return true; + } + + private static void ThrowIfUndefined(bool isDefined, string parameterName) + { + if (!isDefined) + { + throw new ArgumentException("The value is not defined in its enumeration.", parameterName); + } + } + + private static void ThrowIfInvalid(string? error, string parameterName) + { + if (error is not null) + { + throw new ArgumentException(error, parameterName); + } + } +} diff --git a/src/WalterEgo.Core/Domain/HoneyTokenId.cs b/src/WalterEgo.Core/Domain/HoneyTokenId.cs new file mode 100644 index 0000000..e848944 --- /dev/null +++ b/src/WalterEgo.Core/Domain/HoneyTokenId.cs @@ -0,0 +1,63 @@ +using System.Diagnostics.CodeAnalysis; + +namespace WalterEgo; + +/// +/// Identifies an alter ego. The identifier is chosen by the user, must stay the same across restarts and is +/// included in every alert about the alter ego. +/// +/// +/// A valid identifier has 1 to 64 characters, starts with a lowercase ASCII letter or digit and contains only +/// lowercase ASCII letters, digits, -, . and _. Identifiers compare ordinally. +/// The default value is not a valid identifier and is rejected wherever an identifier is required. +/// +public readonly record struct HoneyTokenId +{ + private readonly string? _value; + + /// + /// Creates an identifier. + /// + /// The identifier text. + /// is not a valid identifier. + public HoneyTokenId(string value) + { + if (!HoneyTokenRules.IsSlug(value, HoneyTokenRules.MaxIdLength)) + { + throw new ArgumentException(HoneyTokenRules.InvalidIdMessage, nameof(value)); + } + + _value = value; + } + + /// + /// Gets the identifier text, or an empty string for the default value. + /// + public string Value => _value ?? string.Empty; + + internal bool IsDefault => _value is null; + + /// + /// Tries to create an identifier. + /// + /// The identifier text. + /// The identifier, or the default value when is not valid. + /// when is a valid identifier. + public static bool TryCreate([NotNullWhen(true)] string? value, out HoneyTokenId id) + { + if (!HoneyTokenRules.IsSlug(value, HoneyTokenRules.MaxIdLength)) + { + id = default; + return false; + } + + id = new HoneyTokenId(value); + return true; + } + + /// + /// Returns the identifier text. + /// + /// The identifier text, or an empty string for the default value. + public override string ToString() => Value; +} diff --git a/src/WalterEgo.Core/Domain/HoneyTokenKind.cs b/src/WalterEgo.Core/Domain/HoneyTokenKind.cs new file mode 100644 index 0000000..177c4f2 --- /dev/null +++ b/src/WalterEgo.Core/Domain/HoneyTokenKind.cs @@ -0,0 +1,28 @@ +namespace WalterEgo; + +/// +/// The kind of asset an alter ego imitates. +/// +public enum HoneyTokenKind +{ + /// An HTTP route that no legitimate client calls. + Endpoint = 1, + + /// A username or e-mail address that belongs to nobody. + User = 2, + + /// An API key in the application's own format that never authorizes anything. + ApiKey = 3, + + /// A fictitious database row. + Row = 4, + + /// A configuration entry that carries a beacon or another decoy value. + Config = 5, + + /// A session token, such as a JWT or a cookie, that never validates. + SessionToken = 6, + + /// A file that carries decoy credentials or a beacon. + File = 7, +} diff --git a/src/WalterEgo.Core/Domain/HoneyTokenRules.cs b/src/WalterEgo.Core/Domain/HoneyTokenRules.cs new file mode 100644 index 0000000..35fc61e --- /dev/null +++ b/src/WalterEgo.Core/Domain/HoneyTokenRules.cs @@ -0,0 +1,108 @@ +using System.Diagnostics.CodeAnalysis; +using System.Globalization; + +namespace WalterEgo; + +internal static class HoneyTokenRules +{ + internal const int MaxIdLength = 64; + internal const int MaxNameLength = 128; + internal const int MaxPlacementLength = 512; + internal const int MaxDescriptionLength = 1024; + internal const int MaxTagCount = 16; + internal const int MaxTagKeyLength = 32; + internal const int MaxTagValueLength = 128; + + internal const string InvalidIdMessage = + "The identifier must have 1 to 64 characters, start with a lowercase ASCII letter or digit and contain only lowercase ASCII letters, digits, '-', '.' and '_'."; + + internal static bool IsSlug([NotNullWhen(true)] string? value, int maxLength) + { + if (string.IsNullOrEmpty(value) || value.Length > maxLength || !IsLowercaseAlphanumeric(value[0])) + { + return false; + } + + foreach (var c in value.AsSpan(1)) + { + if (!IsLowercaseAlphanumeric(c) && c is not ('-' or '.' or '_')) + { + return false; + } + } + + return true; + } + + internal static bool IsDefined(HoneyTokenKind kind) => kind is >= HoneyTokenKind.Endpoint and <= HoneyTokenKind.File; + + internal static bool IsDefined(DecoyClass decoyClass) => decoyClass is DecoyClass.Generic or DecoyClass.Unique; + + internal static bool IsDefined(Severity severity) => severity is >= Severity.Low and <= Severity.Critical; + + internal static bool IsDefined(TriggerDomain domain) => domain is >= TriggerDomain.ApiKey and <= TriggerDomain.RequestPath; + + internal static string? CheckPlacement(string? placement) => + CheckText(placement, "The placement", MaxPlacementLength, allowBlank: false); + + internal static string? CheckName(string? name) => + name is null ? null : CheckText(name, "The name", MaxNameLength, allowBlank: false); + + internal static string? CheckDescription(string? description) => + description is null ? null : CheckText(description, "The description", MaxDescriptionLength, allowBlank: true); + + internal static string? CheckTags(IReadOnlyDictionary? tags) + { + if (tags is null) + { + return null; + } + + if (tags.Count > MaxTagCount) + { + return "An alter ego can have at most 16 tags."; + } + + foreach (var (key, value) in tags) + { + if (!IsSlug(key, MaxTagKeyLength)) + { + return "Tag keys must have 1 to 32 characters, start with a lowercase ASCII letter or digit and contain only lowercase ASCII letters, digits, '-', '.' and '_'."; + } + + if (CheckText(value, "Each tag value", MaxTagValueLength, allowBlank: false) is { } error) + { + return error; + } + } + + return null; + } + + private static string? CheckText(string? text, string subject, int maxLength, bool allowBlank) + { + if (text is null || (!allowBlank && string.IsNullOrWhiteSpace(text))) + { + return $"{subject} must not be empty or white space."; + } + + if (text.Length > maxLength) + { + return $"{subject} must have at most {maxLength} characters."; + } + + // Line and paragraph separators are rejected with the control characters because they also break + // log lines and message layouts in alert channels. + foreach (var c in text) + { + if (char.GetUnicodeCategory(c) is UnicodeCategory.Control or UnicodeCategory.LineSeparator or UnicodeCategory.ParagraphSeparator) + { + return $"{subject} must not contain control characters or line separators."; + } + } + + return null; + } + + private static bool IsLowercaseAlphanumeric(char c) => char.IsAsciiLetterLower(c) || char.IsAsciiDigit(c); +} diff --git a/src/WalterEgo.Core/Domain/Severity.cs b/src/WalterEgo.Core/Domain/Severity.cs new file mode 100644 index 0000000..b3c7117 --- /dev/null +++ b/src/WalterEgo.Core/Domain/Severity.cs @@ -0,0 +1,19 @@ +namespace WalterEgo; + +/// +/// The severity of a trip. +/// +public enum Severity +{ + /// Low severity, the default for generic decoys. + Low = 1, + + /// Medium severity. + Medium = 2, + + /// High severity, the default for unique decoys. + High = 3, + + /// Critical severity. + Critical = 4, +} diff --git a/src/WalterEgo.Core/Domain/TriggerDomain.cs b/src/WalterEgo.Core/Domain/TriggerDomain.cs new file mode 100644 index 0000000..6d0880d --- /dev/null +++ b/src/WalterEgo.Core/Domain/TriggerDomain.cs @@ -0,0 +1,19 @@ +namespace WalterEgo; + +/// +/// Where a sensor looks for a decoy value. The same value produces a different digest in each domain. +/// +public enum TriggerDomain +{ + /// The value of an API key presented to the application. + ApiKey = 1, + + /// A username or e-mail address used in a sign-in attempt. + Username = 2, + + /// A session token, such as a bearer token or a session cookie. + SessionToken = 3, + + /// The path of an HTTP request, such as a beacon or a unique honey endpoint. + RequestPath = 4, +} diff --git a/src/WalterEgo.Core/PublicAPI.Unshipped.txt b/src/WalterEgo.Core/PublicAPI.Unshipped.txt index 7dc5c58..abc899d 100644 --- a/src/WalterEgo.Core/PublicAPI.Unshipped.txt +++ b/src/WalterEgo.Core/PublicAPI.Unshipped.txt @@ -1 +1,68 @@ #nullable enable +WalterEgo.DecoyClass +WalterEgo.DecoyClass.Generic = 1 -> WalterEgo.DecoyClass +WalterEgo.DecoyClass.Unique = 2 -> WalterEgo.DecoyClass +WalterEgo.HoneyToken +WalterEgo.HoneyToken.$() -> WalterEgo.HoneyToken! +WalterEgo.HoneyToken.Class.get -> WalterEgo.DecoyClass +WalterEgo.HoneyToken.Description.get -> string? +override WalterEgo.HoneyToken.Equals(object? obj) -> bool +WalterEgo.HoneyToken.Equals(WalterEgo.HoneyToken? other) -> bool +override WalterEgo.HoneyToken.GetHashCode() -> int +WalterEgo.HoneyToken.HoneyToken(WalterEgo.HoneyTokenId id, WalterEgo.HoneyTokenKind kind, WalterEgo.DecoyClass decoyClass, string! placement, WalterEgo.Severity severity, string? name = null, string? description = null, System.Collections.Generic.IReadOnlyDictionary? tags = null) -> void +WalterEgo.HoneyToken.Id.get -> WalterEgo.HoneyTokenId +WalterEgo.HoneyToken.Kind.get -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyToken.Name.get -> string! +static WalterEgo.HoneyToken.operator !=(WalterEgo.HoneyToken? left, WalterEgo.HoneyToken? right) -> bool +static WalterEgo.HoneyToken.operator ==(WalterEgo.HoneyToken? left, WalterEgo.HoneyToken? right) -> bool +WalterEgo.HoneyToken.Placement.get -> string! +WalterEgo.HoneyToken.Severity.get -> WalterEgo.Severity +WalterEgo.HoneyToken.Tags.get -> System.Collections.Generic.IReadOnlyDictionary! +override WalterEgo.HoneyToken.ToString() -> string! +WalterEgo.HoneyTokenId +~override WalterEgo.HoneyTokenId.Equals(object obj) -> bool +WalterEgo.HoneyTokenId.Equals(WalterEgo.HoneyTokenId other) -> bool +override WalterEgo.HoneyTokenId.GetHashCode() -> int +WalterEgo.HoneyTokenId.HoneyTokenId() -> void +WalterEgo.HoneyTokenId.HoneyTokenId(string! value) -> void +static WalterEgo.HoneyTokenId.operator !=(WalterEgo.HoneyTokenId left, WalterEgo.HoneyTokenId right) -> bool +static WalterEgo.HoneyTokenId.operator ==(WalterEgo.HoneyTokenId left, WalterEgo.HoneyTokenId right) -> bool +override WalterEgo.HoneyTokenId.ToString() -> string! +static WalterEgo.HoneyTokenId.TryCreate(string? value, out WalterEgo.HoneyTokenId id) -> bool +WalterEgo.HoneyTokenId.Value.get -> string! +WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.ApiKey = 3 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.Config = 5 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.Endpoint = 1 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.File = 7 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.Row = 4 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.SessionToken = 6 -> WalterEgo.HoneyTokenKind +WalterEgo.HoneyTokenKind.User = 2 -> WalterEgo.HoneyTokenKind +WalterEgo.ISecretHasher +WalterEgo.ISecretHasher.ComputeDigest(WalterEgo.TriggerDomain domain, System.ReadOnlySpan value) -> WalterEgo.SecretDigest +WalterEgo.ITokenRegistry +WalterEgo.ITokenRegistry.HasTriggers(WalterEgo.TriggerDomain domain) -> bool +WalterEgo.ITokenRegistry.Tokens.get -> System.Collections.Generic.IReadOnlyList! +WalterEgo.ITokenRegistry.TryGet(WalterEgo.HoneyTokenId id, out WalterEgo.HoneyToken? token) -> bool +WalterEgo.ITokenRegistry.TryMatch(WalterEgo.TriggerDomain domain, System.ReadOnlySpan value, out WalterEgo.HoneyToken? token) -> bool +WalterEgo.SecretDigest +override WalterEgo.SecretDigest.Equals(object? obj) -> bool +WalterEgo.SecretDigest.Equals(WalterEgo.SecretDigest other) -> bool +override WalterEgo.SecretDigest.GetHashCode() -> int +const WalterEgo.SecretDigest.Length = 32 -> int +static WalterEgo.SecretDigest.operator !=(WalterEgo.SecretDigest left, WalterEgo.SecretDigest right) -> bool +static WalterEgo.SecretDigest.operator ==(WalterEgo.SecretDigest left, WalterEgo.SecretDigest right) -> bool +static WalterEgo.SecretDigest.Parse(System.ReadOnlySpan text) -> WalterEgo.SecretDigest +WalterEgo.SecretDigest.SecretDigest() -> void +override WalterEgo.SecretDigest.ToString() -> string! +static WalterEgo.SecretDigest.TryParse(System.ReadOnlySpan text, out WalterEgo.SecretDigest digest) -> bool +WalterEgo.Severity +WalterEgo.Severity.Critical = 4 -> WalterEgo.Severity +WalterEgo.Severity.High = 3 -> WalterEgo.Severity +WalterEgo.Severity.Low = 1 -> WalterEgo.Severity +WalterEgo.Severity.Medium = 2 -> WalterEgo.Severity +WalterEgo.TriggerDomain +WalterEgo.TriggerDomain.ApiKey = 1 -> WalterEgo.TriggerDomain +WalterEgo.TriggerDomain.RequestPath = 4 -> WalterEgo.TriggerDomain +WalterEgo.TriggerDomain.SessionToken = 3 -> WalterEgo.TriggerDomain +WalterEgo.TriggerDomain.Username = 2 -> WalterEgo.TriggerDomain diff --git a/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs b/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs new file mode 100644 index 0000000..d2d6bd5 --- /dev/null +++ b/src/WalterEgo.Core/Registry/HoneyTokenRegistration.cs @@ -0,0 +1,18 @@ +namespace WalterEgo; + +// Raw input for the registry builder. Every field may be invalid; the builder reports what is wrong instead of +// throwing, so a configuration with several mistakes is fixed in one pass. +internal sealed record HoneyTokenRegistration(string? Id, HoneyTokenKind Kind, string? Placement) +{ + public DecoyClass? Class { get; init; } + + public Severity? Severity { get; init; } + + public string? Name { get; init; } + + public string? Description { get; init; } + + public IReadOnlyDictionary? Tags { get; init; } + + public IReadOnlyList Triggers { get; init; } = []; +} diff --git a/src/WalterEgo.Core/Registry/HoneyTrigger.cs b/src/WalterEgo.Core/Registry/HoneyTrigger.cs new file mode 100644 index 0000000..0716005 --- /dev/null +++ b/src/WalterEgo.Core/Registry/HoneyTrigger.cs @@ -0,0 +1,3 @@ +namespace WalterEgo; + +internal readonly record struct HoneyTrigger(TriggerDomain Domain, SecretDigest Digest); diff --git a/src/WalterEgo.Core/Registry/ITokenRegistry.cs b/src/WalterEgo.Core/Registry/ITokenRegistry.cs new file mode 100644 index 0000000..52d9ebb --- /dev/null +++ b/src/WalterEgo.Core/Registry/ITokenRegistry.cs @@ -0,0 +1,47 @@ +using System.Diagnostics.CodeAnalysis; + +namespace WalterEgo; + +/// +/// The immutable set of alter egos of the application, built once at startup. +/// +/// +/// The registry stores only keyed digests of decoy values, never the values themselves. Lookups never throw because +/// of their arguments and do not allocate for values of up to 1024 UTF-8 bytes (longer values use pooled buffers), +/// so sensors can call them on every request. Instances are safe for concurrent use. +/// +public interface ITokenRegistry +{ + /// + /// Gets every alter ego, ordered by identifier (ordinal). + /// + IReadOnlyList Tokens { get; } + + /// + /// Finds an alter ego by identifier. + /// + /// The identifier. + /// The alter ego, or when none has . + /// when an alter ego has . + bool TryGet(HoneyTokenId id, [NotNullWhen(true)] out HoneyToken? token); + + /// + /// Tells whether any alter ego has a trigger in a domain. When it returns , a sensor can + /// skip that domain entirely. + /// + /// The domain. + /// when at least one alter ego has a trigger in . + bool HasTriggers(TriggerDomain domain); + + /// + /// Finds the alter ego tripped by a value seen in a domain. + /// + /// Where the value was seen. + /// + /// The value as seen by the sensor, after the normalization of its domain. It is hashed and compared with the + /// stored digests; the value itself is not kept. + /// + /// The alter ego, or when the value is not a decoy. + /// when is a decoy value in . + bool TryMatch(TriggerDomain domain, ReadOnlySpan value, [NotNullWhen(true)] out HoneyToken? token); +} diff --git a/src/WalterEgo.Core/Registry/RegistryError.cs b/src/WalterEgo.Core/Registry/RegistryError.cs new file mode 100644 index 0000000..0e095cf --- /dev/null +++ b/src/WalterEgo.Core/Registry/RegistryError.cs @@ -0,0 +1,6 @@ +namespace WalterEgo; + +// TokenId is null when the identifier itself is invalid; the message then points to the position of the entry. +internal sealed record RegistryError(string? TokenId, string Message); + +internal sealed record TokenRegistryBuildResult(TokenRegistry? Registry, IReadOnlyList Errors); diff --git a/src/WalterEgo.Core/Registry/TokenRegistry.cs b/src/WalterEgo.Core/Registry/TokenRegistry.cs new file mode 100644 index 0000000..68f7c65 --- /dev/null +++ b/src/WalterEgo.Core/Registry/TokenRegistry.cs @@ -0,0 +1,55 @@ +using System.Collections.Frozen; +using System.Diagnostics.CodeAnalysis; + +namespace WalterEgo; + +internal sealed class TokenRegistry : ITokenRegistry +{ + private readonly ISecretHasher _hasher; + private readonly FrozenDictionary _byId; + + // Indexed by the numeric value of TriggerDomain; null when no alter ego has a trigger in that domain. + private readonly FrozenDictionary?[] _byDomain = new FrozenDictionary?[(int)TriggerDomain.RequestPath + 1]; + + internal TokenRegistry(ISecretHasher hasher, IReadOnlyList<(HoneyToken Token, IReadOnlyList Triggers)> entries) + { + _hasher = hasher; + _byId = entries.ToFrozenDictionary(entry => entry.Token.Id, entry => entry.Token); + Tokens = Array.AsReadOnly([.. entries.Select(entry => entry.Token).OrderBy(token => token.Id.Value, StringComparer.Ordinal)]); + + foreach (var group in entries.SelectMany(entry => entry.Triggers, (entry, trigger) => (trigger, entry.Token)).GroupBy(pair => pair.trigger.Domain)) + { + _byDomain[(int)group.Key] = group.ToFrozenDictionary(pair => pair.trigger.Digest, pair => pair.Token); + } + } + + public IReadOnlyList Tokens { get; } + + public bool TryGet(HoneyTokenId id, [NotNullWhen(true)] out HoneyToken? token) + { + if (id.IsDefault) + { + token = null; + return false; + } + + return _byId.TryGetValue(id, out token); + } + + public bool HasTriggers(TriggerDomain domain) => Index(domain) is not null; + + public bool TryMatch(TriggerDomain domain, ReadOnlySpan value, [NotNullWhen(true)] out HoneyToken? token) + { + // Returning before hashing keeps requests cheap when a domain has no decoys. + if (value.IsEmpty || Index(domain) is not { } index) + { + token = null; + return false; + } + + return index.TryGetValue(_hasher.ComputeDigest(domain, value), out token); + } + + private FrozenDictionary? Index(TriggerDomain domain) => + HoneyTokenRules.IsDefined(domain) ? _byDomain[(int)domain] : null; +} diff --git a/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs b/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs new file mode 100644 index 0000000..0cbc084 --- /dev/null +++ b/src/WalterEgo.Core/Registry/TokenRegistryBuilder.cs @@ -0,0 +1,175 @@ +using System.Collections.Frozen; + +namespace WalterEgo; + +internal static class TokenRegistryBuilder +{ + public static TokenRegistryBuildResult Build(ISecretHasher hasher, IEnumerable registrations) + { + List errors = []; + List<(HoneyToken Token, IReadOnlyList Triggers)> entries = []; + HashSet ids = []; + Dictionary triggerOwners = []; + var position = 0; + + foreach (var registration in registrations) + { + position++; + if (!HoneyTokenId.TryCreate(registration.Id, out var id)) + { + errors.Add(new(null, $"The alter ego at position {position} has an invalid identifier. {HoneyTokenRules.InvalidIdMessage}")); + continue; + } + + if (!ids.Add(id)) + { + errors.Add(new(id.Value, "The identifier is used by more than one alter ego.")); + continue; + } + + // Inputs are read once, so what is validated is exactly what gets indexed. + HoneyTrigger[] triggers = [.. registration.Triggers ?? []]; + var tags = registration.Tags?.ToFrozenDictionary(StringComparer.Ordinal); + + var errorCount = errors.Count; + CheckSharedTriggers(id, triggers, triggerOwners, errors); + if (Validate(id, registration, triggers, tags, errors) is { } token && errors.Count == errorCount) + { + entries.Add((token, triggers)); + } + } + + return errors.Count > 0 + ? new TokenRegistryBuildResult(null, errors) + : new TokenRegistryBuildResult(new TokenRegistry(hasher, entries), []); + } + + private static HoneyToken? Validate( + HoneyTokenId id, + HoneyTokenRegistration registration, + HoneyTrigger[] triggers, + IReadOnlyDictionary? tags, + List errors) + { + var errorCount = errors.Count; + void Fail(string message) => errors.Add(new(id.Value, message)); + + var kind = registration.Kind; + var kindIsDefined = HoneyTokenRules.IsDefined(kind); + if (!kindIsDefined) + { + Fail("The kind is not defined."); + } + + DecoyClass? decoyClass = registration.Class; + if (decoyClass is { } givenClass && !HoneyTokenRules.IsDefined(givenClass)) + { + Fail("The class is not defined."); + } + else if (decoyClass is null && kindIsDefined) + { + if (kind is HoneyTokenKind.Endpoint or HoneyTokenKind.User) + { + Fail($"A {kind} alter ego needs an explicit class, because it can be either a generic or a unique decoy."); + } + else + { + decoyClass = DecoyClass.Unique; + } + } + + var severity = registration.Severity; + if (severity is { } givenSeverity && !HoneyTokenRules.IsDefined(givenSeverity)) + { + Fail("The severity is not defined."); + } + + AddIfInvalid(HoneyTokenRules.CheckPlacement(registration.Placement)); + AddIfInvalid(HoneyTokenRules.CheckName(registration.Name)); + AddIfInvalid(HoneyTokenRules.CheckDescription(registration.Description)); + AddIfInvalid(HoneyTokenRules.CheckTags(tags)); + + HashSet seen = []; + foreach (var trigger in triggers) + { + if (!HoneyTokenRules.IsDefined(trigger.Domain)) + { + Fail("A trigger has an undefined domain."); + } + else if (kindIsDefined && !AcceptsDomain(kind, trigger.Domain)) + { + Fail($"A {kind} alter ego does not accept {trigger.Domain} triggers."); + } + + if (trigger.Digest.IsDefault) + { + Fail("A trigger has an uninitialized digest."); + } + + if (!seen.Add(trigger)) + { + Fail("A trigger is repeated."); + } + } + + if (kindIsDefined && triggers.Length < MinimumTriggers(kind)) + { + Fail($"A {kind} alter ego needs at least one trigger."); + } + + if (errors.Count > errorCount || decoyClass is not { } resolvedClass) + { + return null; + } + + return new HoneyToken( + id, + kind, + resolvedClass, + registration.Placement!, + severity ?? (resolvedClass is DecoyClass.Generic ? Severity.Low : Severity.High), + registration.Name, + registration.Description, + tags); + + void AddIfInvalid(string? error) + { + if (error is not null) + { + Fail(error); + } + } + } + + private static void CheckSharedTriggers( + HoneyTokenId id, + HoneyTrigger[] triggers, + Dictionary triggerOwners, + List errors) + { + foreach (var trigger in triggers) + { + if (!HoneyTokenRules.IsDefined(trigger.Domain) || trigger.Digest.IsDefault) + { + continue; + } + + if (!triggerOwners.TryAdd(trigger, id) && triggerOwners[trigger] != id) + { + errors.Add(new(id.Value, $"A {trigger.Domain} trigger is shared with the alter ego '{triggerOwners[trigger]}'.")); + } + } + } + + private static bool AcceptsDomain(HoneyTokenKind kind, TriggerDomain domain) => kind switch + { + HoneyTokenKind.Endpoint => domain is TriggerDomain.RequestPath, + HoneyTokenKind.User => domain is TriggerDomain.Username, + HoneyTokenKind.ApiKey => domain is TriggerDomain.ApiKey, + HoneyTokenKind.SessionToken => domain is TriggerDomain.SessionToken, + HoneyTokenKind.Config or HoneyTokenKind.File => true, + _ => false, + }; + + private static int MinimumTriggers(HoneyTokenKind kind) => kind is HoneyTokenKind.Endpoint or HoneyTokenKind.Row ? 0 : 1; +} diff --git a/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs b/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs new file mode 100644 index 0000000..4e62d98 --- /dev/null +++ b/src/WalterEgo.Core/Secrets/HmacSecretHasher.cs @@ -0,0 +1,81 @@ +using System.Buffers; +using System.Diagnostics; +using System.Security.Cryptography; +using System.Text; + +namespace WalterEgo; + +internal sealed class HmacSecretHasher : ISecretHasher +{ + internal const int MinimumKeyLength = 32; + + private const int SubkeyLength = 32; + private const int StackBufferLength = 1024; + + // Indexed by the numeric value of TriggerDomain; index 0 stays empty. + private readonly byte[][] _subkeys = new byte[(int)TriggerDomain.RequestPath + 1][]; + + public HmacSecretHasher(ReadOnlySpan key) + { + if (key.Length < MinimumKeyLength) + { + throw new ArgumentException("The HMAC key must have at least 32 bytes.", nameof(key)); + } + + // Only the derived subkeys are kept, so the key itself never stays in memory owned by the hasher. + ReadOnlySpan domains = [TriggerDomain.ApiKey, TriggerDomain.Username, TriggerDomain.SessionToken, TriggerDomain.RequestPath]; + foreach (var domain in domains) + { + var subkey = new byte[SubkeyLength]; + HKDF.DeriveKey(HashAlgorithmName.SHA256, key, subkey, salt: [], info: Info(domain)); + _subkeys[(int)domain] = subkey; + } + } + + public SecretDigest ComputeDigest(TriggerDomain domain, ReadOnlySpan value) + { + if (!HoneyTokenRules.IsDefined(domain)) + { + throw new ArgumentOutOfRangeException(nameof(domain), domain, "The trigger domain is not defined."); + } + + if (value.IsEmpty) + { + throw new ArgumentException("The value must not be empty.", nameof(value)); + } + + var byteCount = Encoding.UTF8.GetByteCount(value); + byte[]? rented = null; + Span utf8 = byteCount <= StackBufferLength + ? stackalloc byte[StackBufferLength] + : rented = ArrayPool.Shared.Rent(byteCount); + utf8 = utf8[..byteCount]; + + try + { + Encoding.UTF8.GetBytes(value, utf8); + Span digest = stackalloc byte[SecretDigest.Length]; + HMACSHA256.HashData(_subkeys[(int)domain], utf8, digest); + return SecretDigest.FromBytes(digest); + } + finally + { + // Sensors hash every value they see, so the buffer may hold the real secret of a legitimate user. + CryptographicOperations.ZeroMemory(utf8); + if (rented is not null) + { + ArrayPool.Shared.Return(rented); + } + } + } + + // These labels are part of every digest: changing one invalidates all digests already planted in its domain. + private static ReadOnlySpan Info(TriggerDomain domain) => domain switch + { + TriggerDomain.ApiKey => "walterego/v1/api-key"u8, + TriggerDomain.Username => "walterego/v1/username"u8, + TriggerDomain.SessionToken => "walterego/v1/session-token"u8, + TriggerDomain.RequestPath => "walterego/v1/request-path"u8, + _ => throw new UnreachableException(), + }; +} diff --git a/src/WalterEgo.Core/Secrets/ISecretHasher.cs b/src/WalterEgo.Core/Secrets/ISecretHasher.cs new file mode 100644 index 0000000..9f4f43f --- /dev/null +++ b/src/WalterEgo.Core/Secrets/ISecretHasher.cs @@ -0,0 +1,23 @@ +namespace WalterEgo; + +/// +/// Computes the keyed digest of a decoy value. +/// +/// +/// A subkey is derived from a secret key for each , so the same value has a different +/// digest in each domain, and nobody without the key can compute a digest or test whether a value is a decoy. +/// The value is hashed as UTF-8 exactly as given, with invalid UTF-16 replaced by U+FFFD. Any normalization, such +/// as the case of a username, must happen before. +/// +public interface ISecretHasher +{ + /// + /// Computes the digest of a value. + /// + /// Where the value is looked for. + /// The value to hash. + /// The digest of in . + /// is empty. + /// is not a defined value. + SecretDigest ComputeDigest(TriggerDomain domain, ReadOnlySpan value); +} diff --git a/src/WalterEgo.Core/Secrets/SecretDigest.cs b/src/WalterEgo.Core/Secrets/SecretDigest.cs new file mode 100644 index 0000000..e1cd285 --- /dev/null +++ b/src/WalterEgo.Core/Secrets/SecretDigest.cs @@ -0,0 +1,127 @@ +using System.Buffers; +using System.Buffers.Binary; +using System.Buffers.Text; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.CompilerServices; +using System.Security.Cryptography; + +namespace WalterEgo; + +/// +/// A keyed digest (HMAC-SHA256) of a decoy value. The token registry stores digests instead of decoy values, so +/// reading the configuration does not reveal which values are decoys. +/// +/// +/// The canonical text form is the 32 bytes in base64url without padding: exactly 43 characters. Comparing two +/// digests takes the same time whatever their bytes are. +/// +public readonly struct SecretDigest : IEquatable +{ + /// The number of bytes in a digest. + public const int Length = 32; + + private const int TextLength = 43; + + private static readonly SearchValues Base64UrlAlphabet = + SearchValues.Create("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"); + + private readonly DigestBytes _bytes; + + private SecretDigest(ReadOnlySpan bytes) => bytes.CopyTo(_bytes); + + internal bool IsDefault => AsSpan().IndexOfAnyExcept((byte)0) < 0; + + /// + /// Reads a digest from its canonical text form. + /// + /// 43 base64url characters, without padding or white space. + /// The digest. + /// is not the canonical text form of a digest. + public static SecretDigest Parse(ReadOnlySpan text) => + TryParse(text, out var digest) + ? digest + : throw new FormatException("A digest must be written as 43 base64url characters, without padding or white space."); + + /// + /// Tries to read a digest from its canonical text form. + /// + /// 43 base64url characters, without padding or white space. + /// The digest, or the default value when is not canonical. + /// when is the canonical text form of a digest. + public static bool TryParse(ReadOnlySpan text, out SecretDigest digest) + { + digest = default; + if (text.Length != TextLength || text.ContainsAnyExcept(Base64UrlAlphabet)) + { + return false; + } + + // The OperationStatus overload is used because TryDecodeFromChars throws on some malformed inputs. + Span bytes = stackalloc byte[Length]; + if (Base64Url.DecodeFromChars(text, bytes, out _, out var bytesWritten) != OperationStatus.Done || bytesWritten != Length) + { + return false; + } + + // Re-encoding rejects texts whose unused trailing bits are not zero, so each digest has a single text form. + Span canonical = stackalloc char[TextLength]; + if (!Base64Url.TryEncodeToChars(bytes, canonical, out var charsWritten) || !canonical[..charsWritten].SequenceEqual(text)) + { + return false; + } + + digest = new SecretDigest(bytes); + return true; + } + + internal static SecretDigest FromBytes(ReadOnlySpan bytes) + { + if (bytes.Length != Length) + { + throw new ArgumentException("A digest has exactly 32 bytes.", nameof(bytes)); + } + + return new SecretDigest(bytes); + } + + [UnscopedRef] + internal ReadOnlySpan AsSpan() => _bytes; + + /// + /// Compares two digests in constant time. + /// + /// The digest to compare with. + /// when both digests have the same bytes. + public bool Equals(SecretDigest other) => CryptographicOperations.FixedTimeEquals(AsSpan(), other.AsSpan()); + + /// + public override bool Equals([NotNullWhen(true)] object? obj) => obj is SecretDigest other && Equals(other); + + // HMAC output is uniform and an attacker cannot choose it without the key, so the first bytes are a good hash. + /// + public override int GetHashCode() => BinaryPrimitives.ReadInt32LittleEndian(AsSpan()); + + /// + /// Returns the canonical text form of the digest. + /// + /// 43 base64url characters, without padding. + public override string ToString() => Base64Url.EncodeToString(AsSpan()); + + /// Compares two digests in constant time. + /// The first digest. + /// The second digest. + /// when both digests have the same bytes. + public static bool operator ==(SecretDigest left, SecretDigest right) => left.Equals(right); + + /// Compares two digests in constant time. + /// The first digest. + /// The second digest. + /// when the digests have different bytes. + public static bool operator !=(SecretDigest left, SecretDigest right) => !left.Equals(right); + + [InlineArray(Length)] + private struct DigestBytes + { + private byte _element; + } +} diff --git a/tests/WalterEgo.Core.Tests/ChangingCollections.cs b/tests/WalterEgo.Core.Tests/ChangingCollections.cs new file mode 100644 index 0000000..6567602 --- /dev/null +++ b/tests/WalterEgo.Core.Tests/ChangingCollections.cs @@ -0,0 +1,44 @@ +using System.Collections; +using System.Diagnostics.CodeAnalysis; + +namespace WalterEgo.Core.Tests; + +// Collections that return different content after the first enumeration, to prove that inputs are read once. +internal sealed class ChangingList(IReadOnlyList first, IReadOnlyList later) : IReadOnlyList +{ + private int _reads; + + private IReadOnlyList Current => _reads == 0 ? first : later; + + public int Count => Current.Count; + + public T this[int index] => Current[index]; + + public IEnumerator GetEnumerator() => (_reads++ == 0 ? first : later).GetEnumerator(); + + IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); +} + +internal sealed class ChangingDictionary(IReadOnlyDictionary first, IReadOnlyDictionary later) + : IReadOnlyDictionary +{ + private int _reads; + + private IReadOnlyDictionary Current => _reads == 0 ? first : later; + + public int Count => Current.Count; + + public IEnumerable Keys => Current.Keys; + + public IEnumerable Values => Current.Values; + + public string this[string key] => Current[key]; + + public bool ContainsKey(string key) => Current.ContainsKey(key); + + public bool TryGetValue(string key, [MaybeNullWhen(false)] out string value) => Current.TryGetValue(key, out value); + + public IEnumerator> GetEnumerator() => (_reads++ == 0 ? first : later).GetEnumerator(); + + IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); +} diff --git a/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs b/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs new file mode 100644 index 0000000..206a397 --- /dev/null +++ b/tests/WalterEgo.Core.Tests/HmacSecretHasherTests.cs @@ -0,0 +1,119 @@ +namespace WalterEgo.Core.Tests; + +public sealed class HmacSecretHasherTests +{ + private const string DecoyValue = "fictional-decoy-0001"; + + // Computed outside .NET with a hand-written RFC 5869 HKDF over Python's hmac and hashlib modules: + // subkey = HKDF-SHA256(ikm = bytes 0..31, salt = empty, info = "walterego/v1/