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/src/WalterEgo.Core/WalterEgo.Core.csproj b/src/WalterEgo.Core/WalterEgo.Core.csproj index 82586b0..27bf1ed 100644 --- a/src/WalterEgo.Core/WalterEgo.Core.csproj +++ b/src/WalterEgo.Core/WalterEgo.Core.csproj @@ -7,6 +7,7 @@ + diff --git a/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs b/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs new file mode 100644 index 0000000..21f650d --- /dev/null +++ b/tests/WalterEgo.Benchmarks/TokenRegistryBenchmarks.cs @@ -0,0 +1,42 @@ +using BenchmarkDotNet.Attributes; + +namespace WalterEgo.Benchmarks; + +[MemoryDiagnoser] +public class TokenRegistryBenchmarks +{ + private const string DecoyKey = "fictional-key-0050"; + private const string LegitimateKey = "a-real-key-presented-by-a-legitimate-client-0123456789"; + + private TokenRegistry _registry = null!; + private HoneyTokenId _id; + + [GlobalSetup] + public void Setup() + { + // Fictitious key, only used to build the benchmark registry. + byte[] key = [.. Enumerable.Range(0, 32).Select(i => (byte)i)]; + var hasher = new HmacSecretHasher(key); + var registrations = Enumerable.Range(0, 100).Select(i => + new HoneyTokenRegistration($"key-{i:D3}", HoneyTokenKind.ApiKey, $"fictional placement {i}") + { + Triggers = [new HoneyTrigger(TriggerDomain.ApiKey, hasher.ComputeDigest(TriggerDomain.ApiKey, $"fictional-key-{i:D4}"))], + }); + + _registry = TokenRegistryBuilder.Build(hasher, registrations).Registry + ?? throw new InvalidOperationException("The benchmark registry is invalid."); + _id = new HoneyTokenId("key-050"); + } + + [Benchmark(Baseline = true)] + public bool TryMatchWithoutMatch() => _registry.TryMatch(TriggerDomain.ApiKey, LegitimateKey, out _); + + [Benchmark] + public bool TryMatchWithMatch() => _registry.TryMatch(TriggerDomain.ApiKey, DecoyKey, out _); + + [Benchmark] + public bool TryMatchInEmptyDomain() => _registry.TryMatch(TriggerDomain.RequestPath, "/orders/42", out _); + + [Benchmark] + public bool TryGetById() => _registry.TryGet(_id, out _); +} diff --git a/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj b/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj index b0ac756..1268259 100644 --- a/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj +++ b/tests/WalterEgo.Benchmarks/WalterEgo.Benchmarks.csproj @@ -8,4 +8,8 @@ + + + + diff --git a/tests/WalterEgo.Benchmarks/packages.lock.json b/tests/WalterEgo.Benchmarks/packages.lock.json index 39b8dde..ace19eb 100644 --- a/tests/WalterEgo.Benchmarks/packages.lock.json +++ b/tests/WalterEgo.Benchmarks/packages.lock.json @@ -171,6 +171,9 @@ "type": "Transitive", "resolved": "4.7.0", "contentHash": "VybpaOQQhqE6siHppMktjfGBw1GCwvCqiufqmP8F1nj7fTUNtW35LOEt3UZTEsECfo+ELAl/9o9nJx3U91i7vA==" + }, + "walterego.core": { + "type": "Project" } } } 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/