skills/docs/security-stack/crypto/crypto-cipher/src/primitives/aes-256-gcm/aes-256-gcm.md

aes-256-gcm

(no submodules)

• aes-256-gcm.select — (no submodules)- aes-256-gcm.native — (no submodules) - aes-256-gcm.native — (no submodules)- aes-256-gcm.noble — (no submodules) - aes-256-gcm.noble — (no submodules)- aes-256-gcm — (no submodules)- aes-256-gcm.select — _(no s…
• aes-256-gcm.select — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm — (no submodules)- aes-256-gcm.select — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm — (no submodules)- aes-256-gcm.select — <!-- be…
• aes-256-gcm.select — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.native — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm.noble — (no submodules)- aes-256-gcm — (no submodules)- aes-256-gcm.select — _(no…
• aes-256-gcm.select — (no submodules)- aes-256-gcm.native — (no submodules) - aes-256-gcm.native — (no submodules)- aes-256-gcm.noble — (no submodules) - aes-256-gcm.noble — (no submodules)- aes-256-gcm — (no submodules)

Purpose

aes-256-gcm.ts is the stable public entry point for the AES-256-GCM AEAD primitive in @suaveplan/crypto-cipher. It re-exports everything from the generated aes-256-gcm.select.ts, which forwards to either the Noble-backed or native implementation according to crypto.config.ts.

AES-256-GCM (NIST SP 800-38D) is a widely deployed authenticated encryption scheme that provides both confidentiality and integrity. It is mandatory in TLS 1.3, common in cloud storage encryption, and natively available in WebCrypto. This entry point provides the stable import path and exposes the constants KEY_LENGTH, NONCE_LENGTH, and TAG_LENGTH.

Features

• encrypt(key, nonce, plaintext, aad?) — AEAD encryption; returns ciphertext ‖ tag.
• decrypt(key, nonce, ciphertext, aad?) — AEAD decryption; throws CryptoCipherError on tag mismatch.
• KEY_LENGTH = 32 — 256-bit key requirement.
• NONCE_LENGTH = 12 — 96-bit (12-byte) nonce as per NIST recommendation.
• TAG_LENGTH = 16 — 128-bit authentication tag.
• Key and nonce length validated before any cipher operation.

Usage: Basic Example

import { encrypt, decrypt, KEY_LENGTH, NONCE_LENGTH } from "@suaveplan/crypto-cipher/aes-256-gcm";

const key = crypto.getRandomValues(new Uint8Array(KEY_LENGTH));
const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
const plaintext = new TextEncoder().encode("secret");

const ciphertext = encrypt(key, nonce, plaintext);
const recovered = decrypt(key, nonce, ciphertext);
console.log(new TextDecoder().decode(recovered)); // "secret"

Usage: Advanced Example

import { encrypt, decrypt, KEY_LENGTH, NONCE_LENGTH } from "@suaveplan/crypto-cipher/aes-256-gcm";

// Encrypt with Additional Authenticated Data (AAD) for binding.
function encryptWithContext(
    key: Uint8Array,
    plaintext: Uint8Array,
    context: string
): { nonce: Uint8Array; ciphertext: Uint8Array } {
    const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
    const aad = new TextEncoder().encode(context);
    const ciphertext = encrypt(key, nonce, plaintext, aad);
    return { nonce, ciphertext };
}

function decryptWithContext(
    key: Uint8Array,
    nonce: Uint8Array,
    ciphertext: Uint8Array,
    context: string
): Uint8Array {
    const aad = new TextEncoder().encode(context);
    return decrypt(key, nonce, ciphertext, aad); // throws CryptoCipherError on mismatch
}

API Reference

All symbols re-exported from aes-256-gcm.select.ts:

• encrypt(key, nonce, plaintext, aad?): Uint8Array
• decrypt(key, nonce, ciphertext, aad?): Uint8Array
• KEY_LENGTH: 32
• NONCE_LENGTH: 12
• TAG_LENGTH: 16

Implementation Notes

Nonce generation is the caller's responsibility — this module never generates nonces internally. For AES-256-GCM, nonces must never be reused with the same key; a reused (key, nonce) pair destroys both confidentiality and authenticity. Callers should use random 12-byte nonces (96-bit) or a counter-based scheme. The 16-byte authentication tag is appended to the ciphertext in the output of encrypt and expected at the end of the ciphertext in decrypt.