Guide

Sessioned Messages

The currently supported messaging mode in HexaEight. Two parties agree on a sessionId out of band, each pins their half of the ASK pair under sha256(sessionId), and they exchange ciphertext addressed only by that session hash.

The four-step lifecycle

1. Exchange identity names + sessionId

Out of band. Could be your application's registry, a one-time exchange over an existing channel, or a deterministic pairing scheme. For most apps this is just the first message of your protocol.

string aliceName = "alice.example.com";   // known to Bob
string bobName   = "bob.example.com";     // known to Alice
string sessionId = Guid.NewGuid().ToString();   // agreed upon

2. Each side fetches its half of the ASK pair

// On Alice's machine
long kgt = CurrentKgt();
string askA = await alice.FetchAskAsync(bobName, kgt);
alice.PinAskForSession(sessionId, askA);

// On Bob's machine
string askB = await bob.FetchAskAsync(aliceName, kgt);
bob.PinAskForSession(sessionId, askB);

askA and askB are different — they're complementary halves of an asymmetric pair. Each side has the half that lets them participate; the platform did not know either party's password.

3. Send Sessioned envelopes

// Alice → Bob
string env = await alice.EncryptEnvelopeAsync(
    recipient: bobName,
    body:      "message N",
    sessionId: sessionId);
// env starts with "hsha:" — Variant B

4. Decrypt and verify sender

// Bob receives
var msg = await bob.DecryptEnvelopeAsync(env);
// msg.Sender      == "alice.example.com"  (cryptographically verified)
// msg.Body        == "message N"
// msg.FromSession == true

What an observer sees on the wire

hsha:8e92b1a4f7d3c5e29f6a08b1d4e7c2a5...|AQABwxYZ...

Just an opaque hash and ciphertext. Without the session secret, an observer cannot map the hash back to a sender or recipient. The same parties using a fresh sessionId next minute look completely unrelated to the previous traffic.

When to use this

Any bidirectional agent-to-agent communication where both parties know each other's Name.
High-volume channels where you want minimal on-wire metadata.
IoT fleets or device-to-device flows where device identity is a privacy concern.
Long-lived conversations — pin the session once, reuse for thousands of messages.

Session rotation

Cycle sessionId periodically (per session, per day, per N messages — your choice) for forward-secrecy-like properties. Discard the old sessionId and call UnpinAskForSession on both sides to evict the matching cache entry.

alice.UnpinAskForSession(oldSessionId);
bob.UnpinAskForSession(oldSessionId);

string nextSessionId = Guid.NewGuid().ToString();
// agree on it, fetch fresh ASKs, repeat