Class CryptoHelper.GcmNonceContext

Namespace

FishMMO.Auth.Implementation

Assembly

FishMMO-AuthShared.dll

public sealed class CryptoHelper.GcmNonceContext : IDisposable

Inheritance

object

CryptoHelper.GcmNonceContext

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

GcmNonceContext(byte[], NonceSide)

Creates a nonce context that copies the session prefix.

public GcmNonceContext(byte[] sessionPrefix, CryptoHelper.NonceSide side)

Parameters

sessionPrefix byte[]

4-byte session prefix (copied, not aliased).

side CryptoHelper.NonceSide

Traffic direction — determines the direction byte in generated nonces.

GcmNonceContext(byte[], bool)

Creates a nonce context that copies the session prefix. Prefer the CryptoHelper.NonceSide overload for clarity.

public GcmNonceContext(byte[] sessionPrefix, bool serverToClient)

Parameters

sessionPrefix byte[]

4-byte session prefix (copied, not aliased).

serverToClient bool

true for server→client direction; false for client→server.

Properties

ShouldRekey

Whether the counter has exceeded 90% of the practical maximum (MaxValue), indicating an imminent rekey. The practical limit is uint.MaxValue because NextNonce() caps the counter at that value.

public bool ShouldRekey { get; }

Property Value

bool

Methods

BuildNonceForSequence(uint)

Builds a nonce for a specific externally-validated sequence number. Use for the receive direction where the sequence comes from the peer's message.

public byte[] BuildNonceForSequence(uint sequence)

Parameters

sequence uint

The validated sequence number.

Returns

byte[]

A 12-byte GCM nonce.

Clone()

Creates an independent clone for async worker processing. The clone has its own prefix copy and counter snapshot — mutations on the clone do not affect the original and vice versa. Both instances must be independently disposed.

public CryptoHelper.GcmNonceContext Clone()

Returns

CryptoHelper.GcmNonceContext

Dispose()

Zeros the session prefix, preventing further nonce generation.

public void Dispose()

NextNonce()

Atomically increments the internal counter and builds a 12-byte GCM nonce. Use for the send direction where the caller controls sequencing.

public (byte[] Nonce, uint Sequence) NextNonce()

Returns

(byte[] Nonce, uint Sequence)

Tuple of (12-byte nonce, sequence number used).

Exceptions

CryptographicException

Thrown when the counter exceeds MaxGcmNonceCounter.

NextSequenceOnly()

Atomically increments the internal counter and returns the sequence number without building a nonce. Use when the caller needs the sequence for AAD construction and will build the nonce separately via BuildNonceForSequence(uint). Avoids the heap allocation of a 12-byte nonce array that would be immediately discarded.

public uint NextSequenceOnly()

Returns

uint

The next sequence number.

Exceptions

CryptographicException

Thrown when the counter exceeds MaxValue.

TryConsumeSequence(uint)

Atomically validates and consumes an expected receive sequence number. Returns true and advances the counter if seq is exactly one greater than the current counter. Returns false for duplicates or gaps.

public bool TryConsumeSequence(uint seq)

Parameters

seq uint

The expected incoming sequence number.

Returns

bool

true if consumed; false otherwise.

Remarks

Threading model: This method is designed for a single-producer receive path — typically one thread processing inbound messages per connection. The CAS loop exists as a safety net, not as a concurrency strategy. If multiple threads call this concurrently on the same context, the strict in-order requirement (seq == current + 1) means at most one can succeed per round — the others will return false or retry. Under genuine multi-producer contention, legitimate messages may be spuriously rejected after FishMMO.Auth.Implementation.CryptoHelper.GcmNonceContext.MaxCasRetries iterations.

If concurrent receive processing is needed, serialise calls to this method behind a lock or channel, or use a single-threaded receive loop.

TryConsumeSequenceRange(uint, uint)

Atomically validates and consumes a contiguous range of receive sequence numbers [baseSeq, baseSeq + count - 1] in a single CAS. Used by multi-field protocol decoders (SRP verify, account-creation payload) that must not leave the counter advanced partway through a logical message if one field fails to decrypt.

public bool TryConsumeSequenceRange(uint baseSeq, uint count)

Parameters

baseSeq uint

First sequence number in the range.

count uint

Number of consecutive sequences to consume; must be > 0.

Returns

bool

true on success; false on duplicate, gap, exhaustion or invalid count.