In Go's AES-GCM API, why is Seal(nonce, nonce, plaintext, nil) the idiomatic way to prepend a nonce?

## dst is an append target, not an output buffer The signature is: ```go Seal(dst, nonce, plaintext, additionalData []byte) []byte ``` Almost every mistake with this call comes from reading `dst` as "the buffer the result will be written into, which I must size correctly". It is not. `Seal` follows the same convention as the `append` builtin and as `hash.Hash.Sum`: it appends its output to `dst` and returns the extended slice. Whatever was already in `dst` is **kept**, and sits in front of the output. That has two consequences. First, `Seal(nil, ...)` is a perfectly good call and simply allocates a fresh slice. Second, anything you put in `dst` beforehand becomes a prefix of the record for free — which is precisely what you want for the nonce. ## Why the nonce goes in front The decrypting side must pass `Open` the same nonce that `Seal` used, so the nonce has to reach it somehow. It does not have to be kept secret — its requirement is uniqueness per key, not confidentiality — so the simplest transport is to ship it with the ciphertext. Putting it first makes parsing trivial, because `NonceSize()` is a constant for a given AEAD: ```go n := gcm.NonceSize() if len(record) < n { return nil, errShort } plain, err := gcm.Open(nil, record[:n], record[n:], nil) ``` The length check matters: slicing a record shorter than the nonce panics, and a corrupt or truncated object in storage is exactly the input that will produce one. ## The one-line idiom Putting those together gives the form that appears in the `crypto/cipher` documentation itself: ```go record := gcm.Seal(nonce, nonce, chunk, nil) ``` The same slice is passed twice, in two different roles: as `dst`, the prefix to append to, and as `nonce`, the value that seeds the counter. This is safe because `Seal` consumes the nonce before it writes anything after `dst`'s length, and the output region begins past the end of the nonce. It reads oddly the first time, which is why it is worth being able to explain rather than merely copy. ## Sizing the buffer The `cipher.AEAD` interface exposes exactly the two numbers you need to size a record without guessing: - `NonceSize()` — 12 for an AEAD from `cipher.NewGCM`. - `Overhead()` — 16 for GCM, the authentication tag. So the finished record is `NonceSize() + len(plaintext) + Overhead()` bytes. In a batch job that seals a stream of archive chunks, allocating with that capacity up front means `Seal` never has to grow the slice: ```go out := make([]byte, gcm.NonceSize(), gcm.NonceSize()+len(chunk)+gcm.Overhead()) copy(out, nonce) record := gcm.Seal(out, out, chunk, nil) // no reallocation ``` If capacity is short, `Seal` allocates a bigger array and copies, exactly as `append` would — correct, just not free. Hard-coding 12 and 16 instead of calling the methods works today for standard GCM and breaks the day someone swaps in `cipher.NewGCMWithNonceSize` or a different AEAD behind the same interface. ## The nonce length is checked with a panic `Seal` requires `len(nonce) == NonceSize()`. A shorter or longer nonce is not an error return — it is a panic, because it is a programming mistake rather than a runtime condition. The practical consequence is that a nonce read from a decoded header must be length-checked before it reaches `Seal` or `Open`, or a malformed input turns into a panicking goroutine. On the `Open` side, a wrong-length nonce panics for the same reason, so validate the record's length first and return your own error. ## What this idiom is not It is not a way to hide the nonce, and it is not a substitute for `Open`'s error check. It is a framing convention: a self-describing record whose fixed-size header is a nonce. If your storage format already carries the nonce in a separate metadata field, you can pass `nil` as `dst` and keep the two apart — the API is indifferent. What matters is that the decrypter can reconstruct the exact nonce bytes, byte for byte, that `Seal` was given.