> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AES-256-GCM Encryption

> Specifications of the authenticated symmetric encryption model protecting state snapshots.

**sovseal** uses the standard **AES-256-GCM** (Advanced Encryption Standard in Galois/Counter Mode) authenticated encryption algorithm to secure memory payloads before replication.

***

## Technical Details

* **Key Size:** 256 bits (32 bytes), generated locally using a cryptographically secure pseudorandom number generator (CSPRNG).
* **IV Size:** 96 bits (12 bytes), generated fresh for every encryption call.
* **Tag Size:** 128 bits (16 bytes), ensuring integrity checks are mathematically robust.
* **Library Compatibility:** Implemented using the standard Web Crypto API (`crypto.subtle.encrypt`), ensuring compatibility across Node.js, Deno, Bun, Cloudflare Workers, and modern browsers.

***

## Envelope Wire Format

The serialized snapshot payload consists of the ciphertext base64 string and associated verification hashes:

```json theme={null}
{
  "agent_id": "sha256_hash",
  "sequence_number": 42,
  "parent_snapshot": "previous_tx_hash",
  "client_payload_hash": "sha256_hash_of_plaintext",
  "ciphertext_b64": "base64_encoded_iv_and_ciphertext",
  "byte_size": 256
}
```

The ciphertext bytes contain:

1. **IV Prefix:** First 12 bytes of the raw binary payload represent the initialization vector.
2. **Ciphertext Body:** The middle bytes.
3. **AES-GCM Auth Tag:** The final 16 bytes.

***

## Verified Semantic Recall (VSR)

When an agent triggers a memory restore operation, `sovseal` executes Verified Semantic Recall (VSR):

1. Downloads the ciphertext from the replication endpoint.
2. Extracts the 12-byte IV prefix and the 16-byte auth tag.
3. Decrypts the body using the locally held 256-bit key.
4. Re-derives `sha256(canonicalize(decrypted_payload))`.
5. Compares it against the server-returned `client_payload_hash`.
6. If any verification step fails (tag mismatch or hash mismatch), the payload should be treated as tampered and never handed to the agent.

<Warning>
  **This check is not automatic.** Neither `@sovseal/sdk` nor `sovseal-sdk` runs it for you, and there is no built-in `vsr_hash_mismatch` error class — the SDK gives you the primitives (`decryptJson`, `canonicalize`, the `client_payload_hash` anchor) and you implement the comparison. See [Verified Semantic Recall](/platform/core-concepts/verified-semantic-recall) for a ready-to-use implementation.
</Warning>