AEAD Encryption and Nonces

## Two packages, two calls Go splits symmetric encryption across two standard-library packages, and the split is the thing to understand first. `crypto/aes` gives you a **block cipher**; `crypto/cipher` gives you the **mode** that turns a block cipher into something that can encrypt a message of any length and detect tampering. ```go block, err := aes.NewCipher(key) if err != nil { return err } gcm, err := cipher.NewGCM(block) if err != nil { return err } ``` `aes.NewCipher(key []byte) (cipher.Block, error)` accepts a key of **16, 24 or 32 bytes**, selecting AES-128, AES-192 or AES-256. Any other length comes back as an `aes.KeySizeError`. The returned `cipher.Block` has `BlockSize()`, `Encrypt(dst, src []byte)` and `Decrypt(dst, src []byte)` — each of those transforms **exactly one 16-byte block**, with no chaining, no padding and no integrity. Calling `Encrypt` in a loop over a buffer is the classic misuse; that is ECB, and it is never what you want. `cipher.NewGCM(block) (cipher.AEAD, error)` requires a block cipher with a 128-bit block size, which AES is, and returns an error otherwise. There are two siblings for unusual requirements — `cipher.NewGCMWithNonceSize` for a non-standard nonce length and `cipher.NewGCMWithTagSize` for a truncated tag — and reaching for either without a specific reason is a review smell. ## The cipher.AEAD interface `cipher.AEAD` is a four-method interface, and every AEAD in Go presents the same shape: - `NonceSize() int` — how many bytes the nonce argument must be. For `cipher.NewGCM` this is 12. - `Overhead() int` — how much longer the ciphertext is than the plaintext. For GCM this is 16, the authentication tag. - `Seal(dst, nonce, plaintext, additionalData []byte) []byte` - `Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)` Because the API is an interface, code that takes a `cipher.AEAD` is not tied to AES-GCM; the construction is the only AES-specific part. ## Seal and Open ```go record := gcm.Seal(nil, nonce, chunk, nil) plain, err := gcm.Open(nil, nonce, record, nil) ``` Three things about `Seal` surprise newcomers: 1. **The first parameter is a destination to append to, not a preallocated output buffer.** `Seal` behaves like the `append` builtin: it appends the sealed output to `dst` and returns the extended slice. Passing `nil` means "allocate a fresh slice", which is the correct default. 2. **`Seal` does not choose the nonce for you.** With an AEAD from `cipher.NewGCM`, the nonce is a caller-supplied argument that must be exactly `NonceSize()` bytes; a wrong length is a programming error and `Seal` panics rather than returning an error. (`cipher.NewGCMWithRandomNonce`, added in Go 1.24, is the variant that does pick nonces itself.) 3. **The tag is not returned separately.** The 16 bytes of `Overhead()` are appended to the ciphertext in the single returned slice, so `len(record) == len(chunk) + gcm.Overhead()`. `Open` is the mirror image. It takes the same nonce and the same `additionalData`, verifies the tag, and only then returns the plaintext. Its error is the whole safety mechanism of the API: **if `err != nil` you have no plaintext**, and you must not look at, log, or partially process whatever is in the destination slice. A decrypt path that ignores `Open`'s error has thrown away the reason for using an AEAD in the first place. The `additionalData` argument is data that is authenticated but not encrypted — it travels in the clear, and `Open` fails if it differs from what `Seal` saw. Passing `nil` on both sides is normal when there is nothing to bind. ## A batch job, end to end An offline job that encrypts archive chunks on their way to object storage typically builds the AEAD **once** — a `cipher.AEAD` is safe for concurrent use and cheap to reuse, while `aes.NewCipher` does key expansion work you do not want per chunk — and then loops: ```go for _, chunk := range chunks { // nonce is 12 bytes, unique for this chunk record := gcm.Seal(nonce, nonce, chunk, nil) if _, err := sink.Write(record); err != nil { return err } } ``` Here `dst` is the nonce slice itself, so the record comes out as nonce, then ciphertext, then tag, in one buffer — the standard framing, because the reader needs the nonce and it is not secret. The reader splits at `gcm.NonceSize()`. ## What goes wrong The errors are worth handling rather than dropping: `aes.NewCipher` fails on a wrong-sized key, which usually means a key that was hex-decoded incorrectly or read as a string. `cipher.NewGCM` fails on a block cipher of the wrong block size. Neither error is recoverable at run time, but swallowing them yields a nil AEAD and a nil dereference one line later.