How do you use Go's crypto/mlkem package to agree a shared secret outside TLS?

## What a KEM is, in API terms A key encapsulation mechanism is not encryption of a message you supply. It is a one-round protocol that leaves both parties holding the same fresh random symmetric key: 1. The receiver generates a keypair and publishes the public half (the *encapsulation key*). 2. The sender feeds that public half into `Encapsulate`, which returns two things: a shared key that the sender keeps, and a ciphertext. 3. The sender transmits **only the ciphertext**. 4. The receiver runs `Decapsulate` on it with the private half (the *decapsulation key*) and obtains the same shared key. The naming in `crypto/mlkem` follows that vocabulary exactly, which is why there is no `PublicKey`/`PrivateKey` pair — the types are `EncapsulationKey768` and `DecapsulationKey768`. ## The concrete Go flow ```go dk, err := mlkem.GenerateKey768() // receiver, once pub := dk.EncapsulationKey().Bytes() // 1184 bytes, published ek, err := mlkem.NewEncapsulationKey768(pub) // sender parses it secret, ct := ek.Encapsulate() // secret stays here, ct goes on the wire same, err := dk.Decapsulate(ct) // receiver recovers the same secret ``` Sizes worth carrying in your head, because they decide whether this fits your transport: the encapsulation key is 1184 bytes, the ciphertext 1088, and the shared key is `mlkem.SharedKeySize` — 32 bytes. The 1024 parameter set exists as `GenerateKey1024` and friends with larger values; 768 is the level TLS uses and the sensible default. `Encapsulate` returns no error. It draws its own randomness internally, and a failure of the system random source is treated as unrecoverable rather than something you branch on. `Decapsulate` does return an error — a malformed ciphertext is a real, attacker-controlled input. ## Seeds, not blobs `DecapsulationKey768.Bytes()` returns a **64-byte seed** (`mlkem.SeedSize`), not the expanded private key. `mlkem.NewDecapsulationKey768(seed)` reconstructs the key from it. This is a deliberate API choice with two practical consequences. What you persist or put in a secret manager is 64 bytes, which is pleasant. And the expanded form never leaves the package, so there is no invalid intermediate representation for you to mishandle. ## What the package does not do for you **It does not encrypt your data.** The 32 bytes are a key, not a channel. You still choose an AEAD, manage nonces, and — as with any raw shared secret — derive separate per-purpose keys rather than using those bytes directly for several jobs at once. **It does not authenticate anybody.** Nothing in the exchange proves who generated the encapsulation key. If an attacker can substitute their own encapsulation key in transit, they hold the shared secret and you will never notice. Authenticating the encapsulation key — signing it, pinning it, delivering it over an already-authenticated channel — is your problem, and it is the mistake most likely to sink a homegrown design. **It does not hedge for you.** Using ML-KEM alone stakes everything on a scheme that is young relative to the elliptic-curve constructions it supplements. This is precisely why TLS pairs it with X25519 rather than replacing X25519 with it. If you are building a protocol yourself, do the same: run both agreements and mix both secrets, so a break in either leaves you standing. ## When you would reach for this at all Most services should never touch `crypto/mlkem` directly — they get post-quantum protection from TLS by leaving `tls.Config.CurvePreferences` alone. The direct API earns its place when the confidentiality boundary is not a TLS connection: a payload sealed for a recipient and stored for years, an application-level channel inside an existing transport, a message-passing protocol with its own framing. Those are the cases where store-now-decrypt-later actually bites, because the ciphertext genuinely sits somewhere an adversary can copy it. ## Reviewing someone else's use Four questions cover most of it. Is anything other than the ciphertext being transmitted from the sender — if the shared key is on the wire, the whole exercise is void. Is the encapsulation key authenticated, or could it have been swapped? Is the 32-byte secret being run through a proper derivation before use, or spent directly as an AEAD key for several purposes? And is there a classical agreement mixed in, or is the design betting on one scheme?