namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Security; /// /// The OpcUa:CredentialLockout section: how many failed UserName activations one client may make /// before its UserName activations are refused for a while (lmxopcua#833). /// /// /// The defaults are the OPC Foundation SDK 2.0.1 SessionManager lockout this replaces: 5 failures, /// each inside 60 s of the previous one, lock the client out for 5 minutes. When enabled /// ( > 0) every duration must be positive — enforced at host start by /// OpcUaApplicationHostOptionsValidator. /// public sealed class OpcUaCredentialLockoutOptions { /// /// Failed UserName activations for ONE credential identity (an API key id, else the username) from one client /// that lock that client out of using that identity; 0 or less disables the whole lockout. A success /// with the same identity clears its count (lmxopcua#844). /// public int MaxFailedAttempts { get; set; } = 5; /// /// Failed UserName activations from one client, across EVERY identity, that lock the client out of all /// UserName activations (lmxopcua#844). A success does NOT reset this count — it only ages out through /// or an expired lockout — so a client cannot make /// − 1 guesses at someone else's key, sign in with its own, and repeat; nor /// spray a few guesses at each of many key ids. 0 (the default) means 2 × ; /// an explicit value must be at least . /// public int MaxFailedAttemptsPerClient { get; set; } /// A failure more than this many seconds after the previous one starts a fresh count. public int FailureWindowSeconds { get; set; } = 60; /// How long a locked-out client's UserName activations are refused, in seconds. public int LockoutSeconds { get; set; } = 300; /// /// How long a UserName activation waits for one of its client's verification slots before that one attempt /// is failed (BadTimeout, NOT counted as a credential failure). Only reached when a client has more /// verifications in progress than minus its recorded failures; a verification /// is milliseconds, so in practice this bounds a pathological store stall. Kept well under the SDK's /// operation timeout so the client gets this answer rather than a transport timeout. /// public int SlotWaitSeconds { get; set; } = 10; } /// The outcome of . public enum CredentialLockoutVerdict { /// A verification slot is held — authenticate, then call . Proceed, /// The client, or the credential identity it presented, is locked out; refuse without authenticating. LockedOut, /// No slot freed within the wait; fail this one attempt, uncounted. SlotWaitTimedOut, } /// What decided. /// Proceed, locked out, or timed out waiting. /// Time left on the lockout when . /// True for the first refusal of a lockout episode (log it at Information, the rest at Debug). /// What is locked out when . public readonly record struct CredentialLockoutDecision( CredentialLockoutVerdict Verdict, TimeSpan Remaining, bool FirstRefusal, CredentialLockoutScope Scope = CredentialLockoutScope.None); /// What a lockout covers (lmxopcua#844). public enum CredentialLockoutScope { /// Nothing is locked. None, /// One credential identity (key id / username) from one client. Credential, /// Every UserName activation from one client. Client, } /// /// Brute-force lockout for UserName (API-key) activations, scoped so it can never refuse an /// anonymous activation (lmxopcua#833), and counted per credential identity as well as per client /// (lmxopcua#844). /// /// /// /// Why this exists instead of the SDK's own lockout. OPC Foundation SDK 2.0.1's /// SessionManager.ActivateSessionAsync counts every failed identity validation per client and, /// at ServerConfiguration.MaxFailedAuthenticationAttempts (default 5), refuses every /// activation from that client for 5 minutes with BadUserAccessDenied — the lockout check runs /// before the token is even looked at, so it refuses Anonymous too, and a successful anonymous /// activation does not clear it. The host therefore sets MaxFailedAuthenticationAttempts = 0 and /// enforces this narrower lockout instead. /// /// /// Client key. Only UserName activations are counted and refused; Anonymous never consults it. The /// client key is the presented client certificate thumbprint and the observed peer address together. /// ⚠️ On a None endpoint clients commonly present no certificate, so the key is effectively the IP /// alone and NAT neighbours there share the client-wide count (UserName only). The client's /// ApplicationUri is deliberately NOT part of the key (lmxopcua#845): it is a free, unauthenticated /// string on a None channel, so adding it would let one attacker reset its count by varying it. /// /// /// Two counts (lmxopcua#844). Each failure is charged to the (client, credential identity) /// pair — the API key id, or the username when the credential carries no key id — AND to the client as a /// whole. A success clears only its own identity's count. At /// failures of one identity, that client is /// refused that identity for ; at the /// per-client cap (, default 2× that), which a success never resets, the client /// is refused every UserName activation. So a client holding a valid key can no longer launder guesses /// at another key id by signing in with its own between them (the success does not touch the victim /// identity's count), and spraying a few guesses at each of many key ids still hits the client-wide cap. A /// legitimate client with one stale key and one good key loses only the stale one. Timing per count: a /// failure more than after the previous one /// of that count starts it afresh; a refusal during a lockout is not counted; an expired lockout starts a /// fresh count (an expired client-wide lockout clears every identity's too). /// /// /// Only a definite bad credential counts (lmxopcua#845). The caller completes a transient denial — a /// key-store timeout, a miss-budget refusal, an authenticator exception, cancellation — with /// , which releases the slot uncounted; a ConfigDb stall therefore /// cannot lock every keyed client out. /// /// /// Concurrency — parallelism waits, it is never refused. /// hands out a verification slot only /// while both identityFailures + identityInFlight < MaxFailedAttempts and /// clientFailures + clientInFlight < ClientThreshold; an activation beyond that waits for a /// slot (a waiter whose identity has room is not held behind one whose identity has none). No more /// unverified guesses than either threshold are ever in progress-or-failed, while a legitimate client opening /// many keyed sessions at once (a ScadaBridge site node behind one NAT IP) just queues for milliseconds. /// Waiters are refused only when what they need locks out, or (uncounted) after /// ; a cancelled waiter is dequeued. /// /// /// Memory is bounded at clients and /// identities per client (identities beyond that share one /// overflow count — conservative, never laxer). Entries with nothing to remember are pruned when the table /// fills; a client that still finds it full is not tracked. When a prune frees nothing, the next one waits /// until the earliest entry could have expired (lmxopcua#845), so a flood of new client keys at a full table /// does not rescan it under the lock on every failure. /// /// public sealed class FailedCredentialLockout { /// The most clients tracked at once. public const int MaxTrackedClients = 4096; /// The most credential identities tracked per client; further ones share one overflow count. public const int MaxTrackedIdentitiesPerClient = 64; /// The identity used when the caller supplies none (a direct caller / test seam). public const string NoIdentity = ""; private const string OverflowIdentity = "\0overflow"; private const int MaxIdentityLength = 256; private readonly OpcUaCredentialLockoutOptions _options; private readonly TimeProvider _time; private readonly Dictionary _entries = new(StringComparer.Ordinal); private readonly object _gate = new(); private DateTimeOffset _nextPruneAt = DateTimeOffset.MinValue; private int _pruneScans; /// Initializes a new instance of the class. /// The configured thresholds. /// The clock; when null. public FailedCredentialLockout(OpcUaCredentialLockoutOptions options, TimeProvider? time = null) { _options = options ?? throw new ArgumentNullException(nameof(options)); _time = time ?? TimeProvider.System; } /// Whether the lockout is switched on. public bool Enabled => _options.MaxFailedAttempts > 0; /// The effective per-client cap: the configured value, or 2 × MaxFailedAttempts when unset. public int ClientThreshold => _options.MaxFailedAttemptsPerClient > 0 ? _options.MaxFailedAttemptsPerClient : 2 * Math.Max(0, _options.MaxFailedAttempts); private int IdentityThreshold => _options.MaxFailedAttempts; /// Builds the lockout key for a client. /// The presented client certificate's thumbprint, if any. /// The transport-observed peer address, if known. /// The key; never null. public static string KeyFor(string? certificateThumbprint, System.Net.IPAddress? peer) => $"{(string.IsNullOrEmpty(certificateThumbprint) ? "-" : certificateThumbprint)}@{peer?.ToString() ?? "-"}"; /// with . /// The client key from . /// Cancels the wait. /// The decision. public ValueTask BeginAsync(string key, CancellationToken ct = default) => BeginAsync(key, NoIdentity, ct); /// /// Acquires a verification slot for from , waiting for one /// when the client or the identity already has as many in progress as it may. On /// the caller MUST release the slot with /// or , passing the same /// identity. /// /// The client key from . /// The credential identity (key id, else username) the attempt presents. /// Cancels the wait; a cancelled waiter is dequeued and the exception propagates. /// The decision. public async ValueTask BeginAsync(string key, string identity, CancellationToken ct = default) { if (!Enabled) return new(CredentialLockoutVerdict.Proceed, TimeSpan.Zero, false); identity = Normalize(identity); Waiter waiter; Entry entry; lock (_gate) { var now = _time.GetUtcNow(); if (!_entries.TryGetValue(key, out var existing)) { existing = TryAddEntry(key, now); // Untracked when still full: it gets no slot accounting (see remarks). if (existing is null) return new(CredentialLockoutVerdict.Proceed, TimeSpan.Zero, false); } entry = existing; Refresh(entry, now); var slotIdentity = SlotIdentity(entry, identity); if (TryLockedOut(entry, slotIdentity, now, out var refused)) return refused; if (entry.Waiters.Count == 0 && HasFreeSlot(entry, slotIdentity)) { TakeSlot(entry, slotIdentity); return new(CredentialLockoutVerdict.Proceed, TimeSpan.Zero, false); } waiter = new Waiter(identity); entry.Waiters.AddLast(waiter.Node = new LinkedListNode(waiter)); // A waiter whose identity has room is not held behind one whose identity has none. Pump(entry, now); } var wait = TimeSpan.FromSeconds(Math.Max(1, _options.SlotWaitSeconds)); try { return await waiter.Completion.Task.WaitAsync(wait, _time, ct).ConfigureAwait(false); } catch (Exception ex) when (ex is TimeoutException or OperationCanceledException) { lock (_gate) { if (waiter.Completion.Task.IsCompletedSuccessfully) { // Decided in the same instant the wait gave up. A timeout takes the decision as made; a // cancellation hands a granted slot back (waking the next waiter) so nothing leaks. var decided = waiter.Completion.Task.Result; if (ex is not OperationCanceledException) return decided; if (decided.Verdict == CredentialLockoutVerdict.Proceed) ReleaseCore(key, entry, identity, outcome: null); } else { entry.Waiters.Remove(waiter.Node!); waiter.Completion.TrySetCanceled(); Pump(entry, _time.GetUtcNow()); RemoveIfIdle(key, entry); } } if (ex is OperationCanceledException) throw; return new(CredentialLockoutVerdict.SlotWaitTimedOut, TimeSpan.Zero, false); } } /// with . /// The client key. /// Whether the activation was admitted. /// What this failure locked out, if anything. public CredentialLockoutScope Complete(string key, bool succeeded) => Complete(key, NoIdentity, succeeded); /// /// Releases a slot from and records a DEFINITE /// outcome: admitted, or refused for a bad credential. A transient denial goes to /// instead (#845). /// /// The client key. /// The identity passed to BeginAsync. /// Whether the activation was admitted. /// What this failure locked out, if anything. public CredentialLockoutScope Complete(string key, string identity, bool succeeded) { if (!Enabled) return CredentialLockoutScope.None; identity = Normalize(identity); lock (_gate) { return _entries.TryGetValue(key, out var entry) ? ReleaseCore(key, entry, identity, succeeded) : CredentialLockoutScope.None; } } /// with . /// The client key. public void Abandon(string key) => Abandon(key, NoIdentity); /// /// Releases a slot without recording an outcome: the activation was cancelled or threw, or was denied for a /// transient reason (store timeout, miss budget, authenticator fault) rather than a bad credential (#845). /// /// The client key. /// The identity passed to BeginAsync. public void Abandon(string key, string identity) { if (!Enabled) return; identity = Normalize(identity); lock (_gate) { if (_entries.TryGetValue(key, out var entry)) ReleaseCore(key, entry, identity, outcome: null); } } /// Whether is locked out client-wide or for . /// The client key from . /// The time left on the lockout when this returns true. /// when such an activation would be refused. public bool IsLockedOut(string key, out TimeSpan remaining) => IsLockedOut(key, NoIdentity, out remaining); /// /// Whether an activation presenting from would be refused /// right now — client-wide or for that identity (observation; reserves nothing). /// /// The client key from . /// The credential identity. /// The time left on the lockout when this returns true. /// when the activation would be refused. public bool IsLockedOut(string key, string identity, out TimeSpan remaining) { remaining = TimeSpan.Zero; if (!Enabled) return false; identity = Normalize(identity); var now = _time.GetUtcNow(); lock (_gate) { if (!_entries.TryGetValue(key, out var entry)) return false; Refresh(entry, now); if (entry.LockedUntil > now) { remaining = entry.LockedUntil - now; return true; } if (!entry.Identities.TryGetValue(SlotIdentity(entry, identity), out var id) || id.LockedUntil <= now) return false; remaining = id.LockedUntil - now; return true; } } /// Records one failed UserName activation with no slot (test seam / direct callers). /// The client key. /// The credential identity. /// when this failure locked the identity or the client out. public bool RecordFailure(string key, string identity = NoIdentity) { if (!Enabled) return false; identity = Normalize(identity); var now = _time.GetUtcNow(); lock (_gate) { if (!_entries.TryGetValue(key, out var entry)) { entry = TryAddEntry(key, now); if (entry is null) return false; } var locked = RecordFailureCore(entry, SlotIdentity(entry, identity), now); Pump(entry, now); return locked != CredentialLockoutScope.None; } } /// Clears one identity's count after a successful UserName activation (no slot). /// The client key. /// The credential identity that succeeded. public void RecordSuccess(string key, string identity = NoIdentity) { identity = Normalize(identity); lock (_gate) { if (!_entries.TryGetValue(key, out var entry)) return; RecordSuccessCore(entry, SlotIdentity(entry, identity)); Pump(entry, _time.GetUtcNow()); RemoveIfIdle(key, entry); } } /// How many clients are tracked (test observation). internal int TrackedCount { get { lock (_gate) return _entries.Count; } } /// How many full-table prune scans have run (test observation, #845). internal int PruneScanCount { get { lock (_gate) return _pruneScans; } } /// How many activations are waiting for a slot on (test observation). internal int WaitingCount(string key) { lock (_gate) return _entries.TryGetValue(key, out var e) ? e.Waiters.Count : 0; } /// Bounds an attacker-chosen identity string; distinct long values stay distinct. private static string Normalize(string? identity) { identity ??= NoIdentity; if (identity.Length <= MaxIdentityLength) return identity; var hash = System.Security.Cryptography.SHA256.HashData(System.Text.Encoding.UTF8.GetBytes(identity)); return "\0sha256:" + Convert.ToHexString(hash); } private Entry? TryAddEntry(string key, DateTimeOffset now) { if (_entries.Count >= MaxTrackedClients && now >= _nextPruneAt) Prune(now); if (_entries.Count >= MaxTrackedClients) return null; var entry = new Entry(); _entries[key] = entry; return entry; } /// /// The identity a slot / failure is charged to: the identity itself while it is tracked or there is room to /// track it, else the one shared overflow identity (a slot is always reserved for it). /// private static string SlotIdentity(Entry entry, string identity) => entry.Identities.ContainsKey(identity) || entry.Identities.Count < MaxTrackedIdentitiesPerClient - 1 ? identity : OverflowIdentity; private static IdentityState GetOrAddIdentity(Entry entry, string slotIdentity) { if (!entry.Identities.TryGetValue(slotIdentity, out var id)) { id = new IdentityState(); entry.Identities[slotIdentity] = id; } return id; } private bool ClientHasRoom(Entry entry) => entry.Failures + entry.InFlight < ClientThreshold; private bool HasFreeSlot(Entry entry, string slotIdentity) => ClientHasRoom(entry) && (!entry.Identities.TryGetValue(slotIdentity, out var id) || id.Failures + id.InFlight < IdentityThreshold); private static void TakeSlot(Entry entry, string slotIdentity) { entry.InFlight++; GetOrAddIdentity(entry, slotIdentity).InFlight++; } private static bool TryLockedOut(Entry entry, string slotIdentity, DateTimeOffset now, out CredentialLockoutDecision refused) { refused = default; if (entry.LockedUntil > now) { refused = new(CredentialLockoutVerdict.LockedOut, entry.LockedUntil - now, !entry.RefusalLogged, CredentialLockoutScope.Client); entry.RefusalLogged = true; return true; } if (!entry.Identities.TryGetValue(slotIdentity, out var id) || id.LockedUntil <= now) return false; refused = new(CredentialLockoutVerdict.LockedOut, id.LockedUntil - now, !id.RefusalLogged, CredentialLockoutScope.Credential); id.RefusalLogged = true; return true; } /// Releases one slot, records (null = uncounted) and wakes waiters. private CredentialLockoutScope ReleaseCore(string key, Entry entry, string identity, bool? outcome) { var now = _time.GetUtcNow(); if (entry.InFlight > 0) entry.InFlight--; // The slot was charged to the identity itself or, when the table was full, to the overflow identity. var slotIdentity = entry.Identities.TryGetValue(identity, out var own) && own.InFlight > 0 ? identity : entry.Identities.TryGetValue(OverflowIdentity, out var overflow) && overflow.InFlight > 0 ? OverflowIdentity : SlotIdentity(entry, identity); if (entry.Identities.TryGetValue(slotIdentity, out var held) && held.InFlight > 0) held.InFlight--; var locked = CredentialLockoutScope.None; if (outcome == true) RecordSuccessCore(entry, slotIdentity); else if (outcome == false) locked = RecordFailureCore(entry, slotIdentity, now); Pump(entry, now); RemoveIfIdle(key, entry); return locked; } /// /// Hands freed slots to waiters in order — passing over one whose identity is full — and refuses every /// waiter whose identity, or whose client, is locked out (they never reach the authenticator). Called under /// the gate after anything that can free a slot or lock the key. /// private void Pump(Entry entry, DateTimeOffset now) { Refresh(entry, now); var node = entry.Waiters.First; while (node is not null) { var next = node.Next; var waiter = node.Value; var slotIdentity = SlotIdentity(entry, waiter.Identity); if (TryLockedOut(entry, slotIdentity, now, out var refused)) { entry.Waiters.Remove(node); waiter.Completion.TrySetResult(refused); } else if (ClientHasRoom(entry) && HasFreeSlot(entry, slotIdentity)) { entry.Waiters.Remove(node); if (waiter.Completion.TrySetResult(new(CredentialLockoutVerdict.Proceed, TimeSpan.Zero, false))) TakeSlot(entry, slotIdentity); // a waiter that already gave up never takes the slot } node = next; } } private static void RecordSuccessCore(Entry entry, string slotIdentity) { // Only this identity's count — never the client-wide one (#844). if (!entry.Identities.TryGetValue(slotIdentity, out var id)) return; id.Failures = 0; id.LockedUntil = default; id.RefusalLogged = false; if (id.InFlight == 0) entry.Identities.Remove(slotIdentity); } private CredentialLockoutScope RecordFailureCore(Entry entry, string slotIdentity, DateTimeOffset now) { Refresh(entry, now); if (entry.LockedUntil > now) return CredentialLockoutScope.None; // a late in-flight failure never extends it var lockFor = TimeSpan.FromSeconds(Math.Max(0, _options.LockoutSeconds)); var result = CredentialLockoutScope.None; var id = GetOrAddIdentity(entry, slotIdentity); if (id.LockedUntil <= now) { id.Failures++; id.LastFailure = now; if (id.Failures >= IdentityThreshold && lockFor > TimeSpan.Zero) { id.LockedUntil = now + lockFor; id.RefusalLogged = false; result = CredentialLockoutScope.Credential; } } entry.Failures++; entry.LastFailure = now; if (entry.Failures >= ClientThreshold && lockFor > TimeSpan.Zero) { entry.LockedUntil = now + lockFor; entry.RefusalLogged = false; result = CredentialLockoutScope.Client; } return result; } /// /// Forgets runs of failures that have gone stale: an expired lockout always starts a fresh count (else a /// LockoutSeconds shorter than FailureWindowSeconds relocked on the first failure after it), /// and so does a failure older than the window. Applies to the client-wide count and each identity's. /// private void Refresh(Entry entry, DateTimeOffset now) { var window = TimeSpan.FromSeconds(Math.Max(0, _options.FailureWindowSeconds)); if (entry.LockedUntil != default && entry.LockedUntil <= now) { // An expired client-wide lockout clears every identity's count as well. ClearCount(ref entry.Failures, ref entry.LockedUntil, ref entry.RefusalLogged); foreach (var id in entry.Identities.Values) ClearCount(ref id.Failures, ref id.LockedUntil, ref id.RefusalLogged); } else if (entry.LockedUntil == default && entry.Failures > 0 && now - entry.LastFailure > window) { entry.Failures = 0; entry.RefusalLogged = false; } if (entry.Identities.Count == 0) return; List? idle = null; foreach (var (name, id) in entry.Identities) { if (id.LockedUntil != default && id.LockedUntil <= now) { ClearCount(ref id.Failures, ref id.LockedUntil, ref id.RefusalLogged); } else if (id.LockedUntil == default && id.Failures > 0 && now - id.LastFailure > window) { id.Failures = 0; id.RefusalLogged = false; } if (id.Failures == 0 && id.InFlight == 0 && id.LockedUntil == default) (idle ??= []).Add(name); } if (idle is null) return; foreach (var name in idle) entry.Identities.Remove(name); } private static void ClearCount(ref int failures, ref DateTimeOffset lockedUntil, ref bool refusalLogged) { failures = 0; lockedUntil = default; refusalLogged = false; } private void RemoveIfIdle(string key, Entry entry) { if (!IsIdle(entry, _time.GetUtcNow())) return; _entries.Remove(key); _nextPruneAt = DateTimeOffset.MinValue; // room was made; a full table may prune again } private void Prune(DateTimeOffset now) { _pruneScans++; var earliest = DateTimeOffset.MaxValue; List? idle = null; foreach (var (key, entry) in _entries) { if (IsIdle(entry, now)) (idle ??= []).Add(key); else if (EarliestIdle(entry) is var at && at < earliest) earliest = at; } if (idle is not null) { foreach (var key in idle) _entries.Remove(key); } // #845 — when nothing could be freed, do not rescan the full table on every new client's failure: wait // until the earliest entry could have gone idle by the clock. An entry holding a slot or a waiter goes // idle only through a release, and RemoveIfIdle resets this when that frees room. _nextPruneAt = _entries.Count >= MaxTrackedClients ? earliest : DateTimeOffset.MinValue; } /// The earliest instant could be idle by the clock alone. private DateTimeOffset EarliestIdle(Entry entry) { if (entry.InFlight > 0 || entry.Waiters.Count > 0) return DateTimeOffset.MaxValue; var window = TimeSpan.FromSeconds(Math.Max(0, _options.FailureWindowSeconds)); var at = Expiry(entry.LockedUntil, entry.Failures, entry.LastFailure, window); foreach (var id in entry.Identities.Values) { var idAt = Expiry(id.LockedUntil, id.Failures, id.LastFailure, window); if (idAt > at) at = idAt; } return at; static DateTimeOffset Expiry(DateTimeOffset lockedUntil, int failures, DateTimeOffset lastFailure, TimeSpan window) => lockedUntil != default ? lockedUntil : failures > 0 ? lastFailure + window + TimeSpan.FromTicks(1) : DateTimeOffset.MinValue; } /// Idle = nothing to remember: no failures, lockout, slot, waiter or identity. private bool IsIdle(Entry entry, DateTimeOffset now) { Refresh(entry, now); return entry.InFlight == 0 && entry.Waiters.Count == 0 && entry.Failures == 0 && entry.LockedUntil == default && entry.Identities.Count == 0; } /// One activation waiting for a slot. private sealed class Waiter(string identity) { public readonly TaskCompletionSource Completion = new(TaskCreationOptions.RunContinuationsAsynchronously); public readonly string Identity = identity; public LinkedListNode? Node; } /// One credential identity's count, slots and lockout within one client. Mutated only under the gate. private sealed class IdentityState { public int Failures; public int InFlight; public DateTimeOffset LastFailure; public DateTimeOffset LockedUntil; public bool RefusalLogged; } /// One client's aggregate count, slots, waiters, lockout and identities. Mutated only under the gate. private sealed class Entry { public int Failures; public int InFlight; public DateTimeOffset LastFailure; public DateTimeOffset LockedUntil; public bool RefusalLogged; public readonly LinkedList Waiters = new(); public readonly Dictionary Identities = new(StringComparer.Ordinal); } }