Skip to content

Session Resumption

Session Resumption is a high-performance protocol in Nalix that allows clients to reconnect and restore their previous state without performing a full X25519 Handshake. This is critical for mobile applications where network switching (e.g., Wi-Fi to 5G) or brief disconnections are common.

Source Mapping

  • src/Nalix.Codec/DataFrames/SignalFrames/SessionResume.cs
  • src/Nalix.Runtime/Handlers/SessionHandlers.cs
  • src/Nalix.SDK/Transport/Extensions/ResumeExtensions.cs
  • src/Nalix.Network/Sessions/SessionStoreBase.cs

Key Features

  • Fast Reconnection: Resumption happens in a single request-response cycle.
  • State Persistence: Restores authentication level, permissions, and custom connection attributes.
  • Token Rotation: Every successful resume returns a fresh session token for the next reconnect attempt.
  • Zero-Trust Validation: Uses HMAC-based proof-of-possession to verify the client owns the session secret.

The Resume Workflow

The following diagram illustrates how the Nalix SDK uses a stored token to resume a session on the Nalix Server.

sequenceDiagram
    participant SDK as Nalix SDK (Client)
    participant Srv as Nalix Server
    participant Store as Session Store

    Note over SDK: Load Stored Session Token & Secret
Compute MAC Proof: HMAC(Secret, Token)

    SDK->>Srv: SESSION_SIGNAL (REQUEST)
[SessionToken, MAC Proof]

    Note over Srv: Resolve SessionHandlers
Atomically Consume Token from Store

    Srv->>Store: ConsumeAsync(Token)
    Store-->>Srv: SessionEntry (Snapshot)

    Note over Srv: Verify MAC Proof using Snapshot Secret
Apply Snapshot to Live Connection
Store Current Connection

    Srv->>Store: StoreAsync(CurrentConnection)

    Srv->>SDK: SESSION_SIGNAL (RESPONSE)
[NewSessionToken, SUCCESS]

    Note over SDK: Update Stored Session with New Token
Restore Encrypted Channel

Atomic Token Consumption

To prevent Race Conditions and Double-Resume attacks, Nalix uses "Atomic Consumption". When a resume request arrives:

  1. The server attempts to remove the token from the ISessionStore immediately through ConsumeAsync(...).
  2. If the token was already used or doesn't exist, the request is rejected instantly.
  3. This ensures that a stolen token cannot be used twice, even if two requests arrive at the same millisecond.

Rotation and Security

The SessionToken is a "moving target". After a successful resumption:

  • The old token is invalidated by atomic consumption.
  • A fresh token is issued to the client.
  • The secret (derived during the original handshake) remains the same, maintaining the secure entropy for the encryption layer.

Implementation Guide

By default, the Nalix Hosting model handles session resumption automatically. However, you can control the behavior by implementing a custom ISessionStore (e.g., using Redis for distributed clusters).