Key Derivation

## The problem a KDF solves A real service ends up needing several independent secret keys: one to authenticate session cookies, one to sign download URLs, one to encrypt a column, one per tenant. Provisioning four secrets means four things to generate, distribute, rotate, back up and eventually leak. Using one secret everywhere is worse: a single mistake in one feature compromises all of them, and rotation becomes all-or-nothing. A key derivation function collapses that to one stored secret. You keep a single high-entropy master secret and derive a per-purpose key from it on demand. The derived keys are computationally unrelated: knowing the cookie key tells an attacker nothing about the URL-signing key. ## The Go call `crypto/hkdf` joined the standard library in Go 1.24. Its one-call form is: ```go func Key[Hash hash.Hash](h func() Hash, secret, salt []byte, info string, keyLength int) ([]byte, error) ``` Five arguments: - **`h`** — a hash *constructor*, almost always `sha256.New`. Note you pass the function, not a hash value; the package calls it to build the instances it needs internally. It is a type parameter, so the compiler infers `Hash` from the argument and you never write it out. - **`secret`** — the master secret. HKDF assumes this is already high-entropy: a value from a secure random source, a shared secret from a key agreement, or a key that came out of an earlier derivation. It is emphatically not the place for a human-typed passphrase. - **`salt`** — a non-secret, ideally random value. It strengthens the internal extract step. It may be `nil`, in which case the package substitutes a run of zero bytes as long as the hash's output. - **`info`** — the per-purpose label, and the argument that does the work you actually care about. Two calls that differ only here return unrelated keys. - **`keyLength`** — how many bytes you want back. The error return is narrow: `keyLength` may not exceed the hash's `Size()` times 255, which is 8160 bytes with SHA-256. A `nil` salt, an empty `info` string and a short `secret` are all accepted without complaint, so any validation beyond the length bound has to live in code you write. ## Determinism is the point Given the same hash, secret, salt, info and length, `hkdf.Key` returns the same bytes every time, on every machine, forever. Three consequences follow, and they are what an interviewer is usually probing for: 1. **You do not store derived keys.** The service derives them at startup or per request and keeps only the master secret in its secret store. That shrinks the number of protected items to one. 2. **The info string is part of the key's identity.** Change the label and you have a different key, so anything already protected by the old key stops verifying or decrypting. Labels are therefore a contract, not a comment, and they normally carry an explicit version suffix from day one. 3. **Identical inputs across environments give identical keys.** If staging and production share a master secret and pass the same info string, they derive the same key. That is a determinism property, not a bug — but it is a common way a cross-environment leak happens. ## What a wrapper looks like The idiomatic shape for a library other teams import is a small type holding the master secret and salt, exposing one method per purpose: ```go type Deriver struct { master []byte salt []byte } func (d *Deriver) SessionCookieKey() ([]byte, error) { return hkdf.Key(sha256.New, d.master, d.salt, "acme/session-cookie/v1", 32) } ``` Naming the purposes as methods rather than taking a `purpose string` parameter is deliberate. A raw string parameter means callers invent their own labels, and two callers that happen to pass the same string — or the empty string — get the same key with no error and no warning. ## Length and truncation One detail worth knowing: HKDF's output for a shorter length is a *prefix* of its output for a longer one. Asking for 16 bytes and asking for 32 with otherwise identical arguments does not give you two independent keys; the first is the first half of the second. Length is not a separation mechanism. The `info` string is. ## History Before Go 1.24 the same algorithm lived in `golang.org/x/crypto/hkdf`, with an older interface that handed you an `io.Reader` to read key material from. The standard-library version returns the bytes directly and returns an error rather than deferring failure to a read. New code should use `crypto/hkdf`.