Class TokenService

Namespace

FishMMO.Auth.Implementation

Assembly

FishMMO-AuthShared.dll

Transport-agnostic service for authentication token operations. Provides token generation, encryption, decryption, and verification for both server-side issuance and client/server token authentication.

public static class TokenService

Inheritance

object

TokenService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

BuildToken(string, long, long, DateTime, byte[], AccessLevel, string?)

Builds a raw HMAC-signed auth token for the specified account. This is a thin wrapper around BuildAuthToken(string, long, long, DateTime, byte[], AccessLevel, string?) that validates the signing key before use.

public static byte[]? BuildToken(string username, long loginServerId, long signingKeyId, DateTime expiresUtc, byte[] signingKey, AccessLevel accessLevel, string? realIp = null)

Parameters

username string

Account name to embed in the token.

loginServerId long

ID of the issuing login server.

signingKeyId long

Database ID of the signing key used for this token.

expiresUtc DateTime

Token expiration timestamp (UTC).

signingKey byte[]

HMAC-SHA256 signing key. Must be at least HmacKeyLength bytes.

accessLevel AccessLevel

Account access level to embed.

realIp string

Returns

byte[]

Raw signed token bytes, or null if the signing key is invalid.

ClientEncryptToken(byte[], byte[], GcmNonceContext, ushort, out byte[], out uint)

Encrypts a stored auth token for transmission to a World/Scene server using AES-GCM with TokenAuth AAD type.

public static void ClientEncryptToken(byte[] rawToken, byte[] clientToServerKey, CryptoHelper.GcmNonceContext sendNonceCtx, ushort agreedVersion, out byte[] encryptedToken, out uint seq)

Parameters

rawToken byte[]

Raw auth token bytes to encrypt.

clientToServerKey byte[]

AES-256 key for client→server direction.

sendNonceCtx CryptoHelper.GcmNonceContext

Client's send nonce context.

agreedVersion ushort

Negotiated protocol version.

encryptedToken byte[]

Encrypted token output.

seq uint

Sequence number used (for broadcast).

EncryptTokenForSend(byte[], ConnectionEncryptionData)

Encrypts a raw token for transmission using AES-GCM with TokenTransfer AAD type.

public static byte[] EncryptTokenForSend(byte[] rawToken, ConnectionEncryptionData encryptionData)

Parameters

rawToken byte[]

Raw token bytes.

encryptionData ConnectionEncryptionData

Connection encryption state.

Returns

byte[]

AES-GCM encrypted token bytes.

GenerateAndEncryptToken(ConnectionEncryptionData, string, long, long, int, byte[], AccessLevel, out byte[]?, string?)

Builds, signs, and encrypts an auth token for transmission to the client over an AES-GCM encrypted channel. Used by login servers after successful SRP authentication.

public static byte[]? GenerateAndEncryptToken(ConnectionEncryptionData encryptionData, string username, long loginServerId, long signingKeyId, int tokenExpirationMinutes, byte[] signingKey, AccessLevel accessLevel, out byte[]? rawTokenForHashing, string? realIp = null)

Parameters

encryptionData ConnectionEncryptionData

Connection encryption state (keys, nonces, version).

username string

Account name to embed in the token.

loginServerId long

ID of the issuing login server.

signingKeyId long

Database ID of the signing key used for this token.

tokenExpirationMinutes int

Token validity duration in minutes.

signingKey byte[]

HMAC-SHA256 signing key.

accessLevel AccessLevel

Account access level to embed.

rawTokenForHashing byte[]

Raw token bytes (caller must hash for DB storage, then zero).

realIp string

Returns

byte[]

Encrypted token bytes for transmission, or null if generation failed.

HashToken(byte[])

Computes the SHA-256 hex hash of a raw token for revocation tracking.

public static string HashToken(byte[] rawToken)

Parameters

rawToken byte[]

Raw token bytes to hash.

Returns

string

Lowercase hex-encoded SHA-256 hash string.

TryDecryptAndPartialParse(byte[], ConnectionEncryptionData, uint, out byte[]?, out long, out long)

Decrypts a token from an AES-GCM encrypted payload and performs partial parsing to extract the login server ID for signing key lookup. Does NOT verify the HMAC. Call VerifyToken(byte[], byte[], bool, long, long) after obtaining the signing key.

public static bool TryDecryptAndPartialParse(byte[] encryptedToken, ConnectionEncryptionData encryptionData, uint seq, out byte[]? rawToken, out long loginServerId, out long signingKeyId)

Parameters

encryptedToken byte[]

AES-GCM encrypted token bytes from client.

encryptionData ConnectionEncryptionData

Connection encryption state.

seq uint

Broadcast sequence number.

rawToken byte[]

Decrypted raw token bytes (caller must zero after use).

loginServerId long

Extracted login server ID for signing key ownership checks.

signingKeyId long

Extracted signing-key ID for signing key lookup.

Returns

bool

true if decryption and partial parse succeeded.

Remarks

Pre-decryption size gate: No explicit ciphertext length check is performed here because DecryptAES(byte[], byte[], byte[], byte[]) enforces a hard cap of MaxAesCiphertextSize (64 KiB) and a minimum of AesGcmTagLengthBytes (16 B). Since GCM decryption is authenticated, oversized or malformed payloads are rejected before any plaintext is exposed, making an additional pre-check redundant.

VerifyToken(byte[], byte[], bool, long, long)

Verifies the HMAC on a raw token and parses all fields. Equalizes timing regardless of whether the signing key is real or dummy.

public static TokenService.TokenVerifyResult VerifyToken(byte[] rawToken, byte[] hmacKey, bool signingKeyFound, long preParseLoginServerId, long preParseSigningKeyId)

Parameters

rawToken byte[]

Raw decrypted token bytes.

hmacKey byte[]

HMAC signing key. If the key was not found, pass a random dummy key of HmacKeyLength bytes to equalize timing.

signingKeyFound bool

Whether the signing key was actually found in the database.

preParseLoginServerId long

Login server ID from partial parse. Cross-checked against the HMAC-verified value.

preParseSigningKeyId long

Signing-key ID from partial parse. Cross-checked against the HMAC-verified value.

Returns

TokenService.TokenVerifyResult

Verification result with parsed token fields.