AEAD records: AES-GCM nonces, associated data and key limits

Authenticated encryption with associated data takes a key, nonce, plaintext, and associated data, and returns ciphertext with an authentication tag. Decryption takes those inputs and either returns the original plaintext or fails. Associated data is authenticated but not encrypted, so it is suitable for context that can remain visible.

The tag authenticates only the bytes given to the construction. If every invoice uses associated data equal to the word invoice, a valid encrypted invoice can potentially be copied into another invoice slot under the same key. The tag still verifies because neither the key nor the authenticated context changed. Cryptography cannot infer the database row where the application intended the ciphertext to belong.

Bind the record’s purpose, format version, tenant, and stable record identifier using values obtained from the trusted destination context. If a copied envelope carries its own tenant and the decryptor blindly uses that tenant as associated data, the attacker has moved both the ciphertext and its claimed context together. Reconstruct expected context from the authorized record lookup.

Either: both are AEADs with 256-bit keys, 96-bit nonces and 128-bit tags, and both handle associated data the same way, so the record design on this page applies to both. Use AES-256-GCM on servers and phones with AES instructions or when you need a FIPS-approved algorithm, and ChaCha20-Poly1305 where code may run without AES hardware. The choice that matters more is how nonces are produced: if many writers draw random nonces under one key, prefer XChaCha20-Poly1305 or AES-GCM-SIV, or give each record its own data key. The comparison table in the cryptography quick reference at /domains/identity-crypto/encryption/crypto-quick-reference/ lists speed, approval status, nonce limits and message-size limits side by side.

A practical envelope may contain format version, algorithm identifier or profile, key identifier, nonce, ciphertext, and tag. Some libraries combine ciphertext and tag. Decide which representation you store and impose length limits before allocating or decoding large inputs. Unknown versions should fail explicitly rather than being guessed from parser success.

For this project, the authenticated context is the ordered JSON array [1, tenant, id, "invoice"]. The fixed array order and JSON string escaping preserve field boundaries, including tenant or ID strings containing colons. Validate that version is the number 1, purpose is exactly invoice, and tenant and ID are nonempty strings before encoding.

The envelope key identifier may help select from an allowed local key set, but is not permission to retrieve arbitrary keys or cross tenants. Authenticated encryption does not replace the authorization that decides whether a caller can read this record. It also does not prevent replay of an older valid version; use trusted revision state when rollback matters. The Node.js example below implements this format with Web Crypto: it rejects unsupported versions and purposes, keeps the authentication tag at 128 bits and counts encryptions per key.

// AES-256-GCM records with a 96-bit random IV, a 128-bit tag and the record's context as
// associated data. Random IVs allow at most 2^32 encryptions per key (NIST SP 800-38D).
const LIMIT = 2 ** 32;
const encoder = new TextEncoder();

function context({version, tenant, id, purpose}) {
  if (version !== 1 || purpose !== 'invoice') throw new Error('unsupported record');
  if (typeof tenant !== 'string' || !tenant || typeof id !== 'string' || !id)
    throw new Error('invalid record identifiers');
  return encoder.encode(JSON.stringify([version, tenant, id, purpose])); // keeps field boundaries
}

export async function encryptRecord(keyState, record, plaintext) {
  if (++keyState.uses > LIMIT) throw new Error('key exhausted: rotate the data key');
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const params = {name: 'AES-GCM', iv, additionalData: context(record), tagLength: 128};
  const ciphertext = new Uint8Array(await crypto.subtle.encrypt(params, keyState.key, plaintext));
  return {v: 1, kid: keyState.id, iv, ciphertext}; // ciphertext ends with the tag
}

// `destination` is the record you looked up and authorized; never the envelope's own claims.
export async function decryptRecord(keyState, destination, envelope) {
  if (envelope.v !== 1 || envelope.kid !== keyState.id) throw new Error('unknown key or format');
  const params = {name: 'AES-GCM', iv: envelope.iv, additionalData: context(destination), tagLength: 128};
  return new Uint8Array(await crypto.subtle.decrypt(params, keyState.key, envelope.ciphertext));
}

For AES-GCM, a nonce repeated under the same key is catastrophic: the two ciphertexts reveal the XOR of their plaintexts, and the repetition lets an attacker recover the GHASH authentication key and forge messages. NIST SP 800-38D limits a key to 2^32 encryptions when nonces are 96-bit random values, a limit NIST restated in its January 2025 call to revise the standard. Counters avoid that probability bound but need durable allocation across processes, restarts and restored snapshots; neither “random” nor “counter” is a complete lifecycle design by itself.

Stay inside the bound by design. Give each record or file its own data key through envelope encryption (/domains/identity-crypto/key-management-pki/envelope-encryption-rotation/), or count encryptions per key across every writer and rotate well before 2^32. The downloadable project uses fresh 12-byte random nonces with transient test keys, which is safe at its scale; it does not implement a fleet-wide counter or key budget. The AES-GCM nonce lab at /labs/nonces/ practices the counter design.

Where random nonces at high volume are unavoidable, choose an AEAD designed for them. XChaCha20-Poly1305 has a 192-bit nonce that libsodium describes as safe to choose at random for a practically unlimited number of messages, and AES-GCM-SIV (RFC 8452) does not fail catastrophically if a nonce repeats. A high-level library such as Tink, libsodium or the AWS Encryption SDK chooses nonces and key derivation for you.

Keep the full 128-bit tag: NIST’s June 2026 revision plan removes GCM tags shorter than 96 bits. AES-GCM also does not commit to its key, so a crafted ciphertext can decrypt under two different keys; when several keys or recipients could open the same ciphertext, use a key-committing scheme such as the AWS Encryption SDK’s default algorithm suite.

Do not release partially decrypted bytes before tag verification succeeds. Some streaming interfaces make provisional plaintext available, so the application must buffer or quarantine it until authentication completes. A JSON parser throwing an error after unauthenticated plaintext is used is not an integrity check.

Download the “Bind ciphertext to the correct record” project from the local project section below and extract it. With a supported Node.js release (22 or later), run node --test exercise.test.mjs; no package installation is required. The supplied records.mjs performs actual Web Crypto AES-GCM with temporary keys. The learner repairs recordContext in exercise.mjs.

The initial implementation authenticates only invoice. Consequently, the ordinary round trip and ciphertext-tamper checks can work while context-transplant and validation tests fail. This is why a successful round trip plus one modified-byte test is incomplete evidence for record binding.

After repair, all ten tests must pass. They cover the ordinary invoice, modified ciphertext, wrong tenant, wrong record ID, wrong purpose, wrong version, different key, separator-containing fields, unsupported format/purpose on encryption, and invalid identifiers. These are real encrypt/decrypt checks; production authorization, key persistence, and nonce durability remain outside the project.

Repair the code

AES-GCM nonce reuse lab: Fix a nonce allocator that breaks after restart

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. RFC 5116: Authenticated encryption interface. January 2008.
2. NIST SP 800-38D: GCM. November 2007.
3. NIST: SP 800-38D revision and the 2^32 random-nonce limit (January 2025)
4. NIST: SP 800-38D Rev. 1 second pre-draft call, tag lengths (June 2026)
5. RFC 8452: AES-GCM-SIV. April 2019.
6. libsodium: XChaCha20-Poly1305
7. OWASP Cryptographic Storage Cheat Sheet

Reference information

Tags

Encryption

SDLC phase

DesignDevelopment

Role

Developers

ASVS 5.0.0 requirements

v5.0.0-11.2.1 · v5.0.0-11.3.2 · v5.0.0-11.3.3 · v5.0.0-11.3.4

Download this guide as Markdown

Continue exploring