End-to-End Encryption (E2EE) means that messages are encrypted on the sender device and can be decrypted only on recipient devices. The server routes packets but cannot read plaintext content.
This topic explains the technical flow for:
Direct messages (1:1) between two peers.
Group messages using a sender-key model with membership-based key rotation.
Cryptographic building blocks
Identity / key agreement: Elliptic Curve Diffie-Hellman (ECDH) P-256.
Symmetric encryption: AES-256-GCM.
Key derivation: HKDF-SHA-256 to derive encryption keys from shared secrets.
Message authentication: AEAD authentication tag (provided by AES-GCM).
Replay protection: per-message nonce/IV plus sender sequence counters.
Direct messages (1:1) technical flow
Public key discovery
Each peer publishes a public identity key. The server may distribute public keys, but private keys never leave the client device.
Shared secret establishment
The sender and recipient perform ECDH (private key + peer public key) and obtain the same shared secret.
Session key derivation
HKDF-SHA-256 derives one or more symmetric keys (encryption key, optional header key) from the ECDH output.
Message encryption
The plaintext is encrypted with AES-256-GCM using a unique nonce/IV. Output includes ciphertext + authentication tag.
Transport
The server forwards encrypted payloads and metadata (for example: sender id, key id, counter, timestamp) without plaintext access.
Recipient decryption
The recipient derives the same session key, verifies the authentication tag, and decrypts. Any tampering causes authentication failure.
Group messages technical flow (Sender Keys)
For groups, encrypting each message separately for every member is expensive. A common optimization is a sender key design:
Each sender maintains a Sender Key State per group.
The state contains a symmetric chain key and message counter.
For every outgoing group message, the sender derives a one-time message key from the chain key and advances the chain (hash ratchet).
The message key encrypts the payload with AES-256-GCM.
How a sender key is distributed
When a sender joins a group, it creates a fresh sender key state.
The sender key state is shared to each current member over existing 1:1 encrypted sessions (pairwise E2EE).
After distribution, normal group payloads use the sender-key fast path (single encryption per message).
Membership changes and sender key rotation
To preserve forward and backward secrecy, group sender keys must rotate on membership events:
User joins group: rotate sender keys so the new member cannot decrypt older history unless explicitly shared.
User leaves or is removed: rotate sender keys immediately so the removed member cannot decrypt new traffic.
Periodic rotation: optional time-based or message-count rotation reduces impact of key compromise.
Typical rotation sequence:
Create a new sender key state (new key id, new chain key).
Distribute it only to currently authorized members through pairwise E2EE channels.
Start encrypting new group messages with the new key id.
Accept old key id only during a short transition window, then retire it.
Security properties
Confidentiality: only clients with valid keys can decrypt.
Integrity and authenticity: AEAD verification detects tampering and forged ciphertexts.
Server blindness: relay servers do not hold plaintext keys for message content.
Post-membership protection: rotated keys block former members from future group messages.
TsgcWSPServer_E2EE: Server Protocol E2EE component. It forwards encrypted messages between clients without knowing message contents.
TsgcWSPClient_E2EE: Client Protocol E2EE component. It manages key exchange, encryption and decryption on peer devices.