Crypto from the stdlib, used correctly: argon2 for passwords, constant-time compares, and the GCM nonce invariant

Route every job to its primitive

When you see a secret-handling task in code review — password storage, token generation, comparison — the question is not “is this crypto correct?” but “is this the approved primitive for this job?” That framing is what this lesson trains.

Senior crypto discipline in Go is not “know cryptography” — it is “refuse to invent it”. The approved surface is the stdlib crypto/* tree plus golang.org/x/crypto, which is maintained by the same team to the same bar. Every secret-handling job in a service maps to exactly one of a handful of answers, and the engineering work is routing, not designing: password storage, token generation, secret comparison, encryption at rest, TLS. The moment a design needs a primitive composed in a way no stdlib API offers directly — encrypting with a hand-built mode, deriving keys with an ad-hoc sha256 chain — that is the signal to stop and get a design review, because misuse at this layer is silent: the code works, the tests pass, and the failure only appears in someone else’s write-up.

Passwords: cost is the feature

sha256 and sha512 are designed to be fast — that is the whole point for signatures and integrity checks, and the fatal flaw for passwords. One modern GPU computes on the order of 10–20 billion SHA-256 hashes per second; an eight-character human password falls in minutes, salted or not (a salt defeats precomputed tables, it does nothing about per-target brute force). Password hashing functions invert the goal: they are deliberately expensive. The stdlib answer lives in x/crypto — bcrypt, scrypt, and argon2, with argon2id the current default recommendation (RFC 9106 suggests 64 MiB of memory, 1 pass, parallelism 4):

import "golang.org/x/crypto/argon2"

func hashPassword(password, salt []byte) []byte {
	// RFC 9106 first recommendation: 1 pass, 64 MiB, 4 lanes, 32-byte key.
	// Tune until one call costs ~100ms-1s on production hardware.
	return argon2.IDKey(password, salt, 1, 64*1024, 4, 32)
}

The honest tuning rule: target roughly 100 ms to 1 s per hash on your real servers, then do the memory math. The memory cost is a feature against GPUs (64 MiB per guess starves their parallelism) and a trap for you: 50 concurrent logins at 64 MiB each is 3.2 GB on one pod. Production answers are a login queue or rate limit, not lowering memory until the attacker is comfortable again. The same trap has a runtime-specific shape elsewhere — Node’s crypto.scrypt enforces a 32 MiB maxmem default and rejects bigger parameters — but Go’s x/crypto/scrypt has no guard at all: it allocates 128 * N * r bytes per call and will happily let an unthrottled login endpoint OOM your own service. Store the parameters next to the hash (the standard encoded formats do this) and re-hash on successful login when parameters age.

Compare secrets in constant time

Before you reach for == on a token or API key, ask yourself: could someone measure how long that comparison takes? With enough samples, they can.

A plain == on strings or bytes.Equal exits at the first differing byte. That makes comparison time proportional to the length of the matched prefix — a measurable signal. The attack is concrete: against a token check, an attacker fixes the first byte, tries all 256 values, and keeps the one with the slowest median response; then the second byte, and so on. A 32-byte secret falls in roughly 256 * 32 guided guesses per position-sweep instead of 2^256 — thousands of requests, not lifetimes. Network jitter does not save you; it averages out over a few thousand samples per guess on a LAN or between co-located services.

import (
	"crypto/sha256"
	"crypto/subtle"
)

func tokenEqual(presented, stored []byte) bool {
	// Hash both sides first: inputs become equal-length, so the
	// length-mismatch early exit in ConstantTimeCompare leaks nothing
	// about the secret itself.
	hp, hs := sha256.Sum256(presented), sha256.Sum256(stored)
	return subtle.ConstantTimeCompare(hp[:], hs[:]) == 1
}

subtle.ConstantTimeCompare examines every byte regardless of where mismatches occur — but it returns 0 immediately when lengths differ, which leaks the secret’s length. Hashing both sides first, as above, closes that and is the standard idiom for MACs, API tokens, and webhook signatures.

Randomness: crypto/rand for anything an attacker must not guess

math/rand v1 is a seedable, deterministic generator — recover the seed (often a timestamp) and you recover every token it ever produced, which is exactly the Hook’s breach. Go 1.22 quietly improved the floor: math/rand and math/rand/v2 now run on ChaCha8 seeded from OS entropy, so accidentally using them is no longer instantly fatal. The nuance to keep honest: that is a hardening of the default, not a contract — the package still documents itself as unsuitable for security work, and explicit seeding reintroduces full predictability. The rule stays one sentence: keys, tokens, session IDs, salts, and nonces come from crypto/rand, period. Since Go 1.24, crypto/rand.Read is documented never to fail (it crashes the program rather than return weak bytes), and rand.Text() gives you a ready-made random token string.

AES-GCM: nonce uniqueness is the invariant

GCM is CTR-mode encryption plus a GHASH authenticator, and both halves depend on one invariant: a (key, nonce) pair is used for exactly one message. Reuse a nonce and the same keystream encrypts two messages — XOR of the ciphertexts equals XOR of the plaintexts, which against structured data (JSON bodies, fixed headers) usually yields both. Worse, nonce reuse exposes the GHASH authentication key — the classic “forbidden attack” — after which the attacker forges ciphertexts your service authenticates and accepts. This is the catastrophic class: not “one message weakened” but key-level compromise. The safe pattern is mechanical:

func encrypt(key, plaintext []byte) ([]byte, error) {
	block, err := aes.NewCipher(key) // 32-byte key -> AES-256
	if err != nil {
		return nil, err
	}
	gcm, err := cipher.NewGCM(block)
	if err != nil {
		return nil, err
	}
	nonce := make([]byte, gcm.NonceSize()) // 12 bytes
	if _, err := rand.Read(nonce); err != nil {
		return nil, err
	}
	// Seal appends to its first arg: output is nonce || ciphertext || tag,
	// so decrypt can split the nonce back off the front.
	return gcm.Seal(nonce, nonce, plaintext, nil), nil
}

Random 12-byte nonces are safe up to a birthday bound: NIST guidance caps a single key at 2^32 messages with random nonces. For most services that is comfortably unreachable; for high-volume pipelines it is a key-rotation requirement you write down, not a detail you discover.

TLS: do nothing, then verify you did nothing

Go’s TLS defaults are good: modern minimum versions, sane cipher suites, full certificate verification. The production failure mode is not weak defaults but humans lowering them — InsecureSkipVerify: true added “temporarily” for a staging self-signed cert, shipped to prod, where it silently disables the entire point of TLS. The cheap, effective control is the grep test: CI fails on any InsecureSkipVerify: true outside test files. The legitimate need it usually masks — trusting an internal CA — has a correct answer: add the CA to RootCAs in the client config. The same skepticism applies to copy-pasted CipherSuites and MinVersion blocks from decade-old blog posts: deleting them is usually the security upgrade.