Module aes_gcm

Expand description

AES-GCM key minting (NIST SP 800-38D).

Keys minted here drive aead.aead-key.seal/open with the parameters as the Web Cryptography API’s AesGcmParams defines them, per call.

Security:

The caller owns nonce uniqueness. Nonce reuse under one key defeats the algorithm’s confidentiality and authenticity guarantees; use a deterministic per-key uniqueness scheme (SP 800-38D §8), or draw 96-bit nonces at random only within §8.2.2’s invocation bounds.
Short tags weaken the forgery bound (SP 800-38D Appendix C) and are opt-in only, behind an explicit tag-size.
96 bits (12 bytes) is the standard nonce size (the nonce-size getter) and the fast path. Other lengths cost an extra GHASH pass (SP 800-38D §7.1) and forfeit §8.2’s deterministic-construction guidance.

Parameter acceptance:

Nonce: 12 to 128 bytes inclusive; a length outside that window fails error.invalid-nonce on every implementation (see README.md, “Portability contract”). The window is the range every implementation serves identically. Nonces shorter than the 96-bit standard size are cryptographically discouraged (SP 800-38D recommends the 96-bit construction), and lengths beyond 128 bytes serve no protocol in use.
Tag size: 16 bytes by default (tag-size of none); the algorithm’s set is 4, 8, 12, 13, 14, 15, or 16 bytes (the registry’s 32–128-bit set). Implementations MAY decline sizes their security policy does not serve with error.unsupported.
Bounds: GCM defines a maximum plaintext of 2^39 − 256 bits (~64 GiB) per invocation and an AAD bound of 2^64 − 1 bits. Implementations reaching them fail rather than wrap, but their buffering limits (error.other) are reached far earlier in practice.

Functions§

derive_key: Mint a key from a parameterized derivation: the derivation runs at the variant’s key length (WebCrypto’s deriveKey chain — get key length, derive bits, import) and the result is subject to import-key-raw’s contract.
generate_key: Generate a fresh random key of the given AES variant. Fails with error.unsupported if this implementation does not serve the variant.
import_key_jwk: Import an RFC 7517 JSON Web Key as an AES-GCM key of the declared variant.
import_key_raw: Import raw key material as the declared AES variant.
unwrap_key_jwk: Mint a key from unwrapped key material read as an RFC 7517 JSON Web Key, subject to import-key-jwk’s contract plus the unwrap-path use/key_ops checks (see README.md, “JWK contract”). input is consumed; see unwrap-key-raw for the options model.
unwrap_key_raw: Mint a key from unwrapped key material (see the wrapping interface): input’s bytes are read as raw key material, subject to import-key-raw’s contract. input is consumed.