Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

ML-KEM key exchange with OpenSSL

After this lesson: I can make an ML-KEM key pair and use it to share a secret with OpenSSL.

65 min lesson12 commandsPost-quantum cryptography lab: ML-KEM, ML-DSA, hybrid TLS and post-quantum SSH with OpenSSL 3.5 and OpenSSH 10

What ML-KEM is and why it matters

ML-KEM is the post-quantum key encapsulation mechanism standardised in 2024. Browsers, servers and SSH already use it to agree session keys, so it is the first post-quantum algorithm most systems meet.

Lesson 1 said what a KEM does. Here you run its three steps yourself with OpenSSL 3.5, and you measure what it costs in bytes.

By the end of this lesson

Note

I can make an ML-KEM key pair and use it to share a secret with OpenSSL.

Key words

WordWhat it meansExample
ML-KEMthe standard post-quantum KEM, built on lattices
Encapsulation keythe public key a sender uses
Decapsulation keythe private key that recovers the secret
Ciphertextwhat encapsulation sends back to the key's owner
Shared secretthe 32 bytes both sides end with
Parameter setone size of an algorithmML-KEM-768

The cells students fill in are left blank in this preview.

Three sizes of ML-KEM

ML-KEM comes in three parameter sets: ML-KEM-512, ML-KEM-768 and ML-KEM-1024. A bigger number means more security and more bytes. ML-KEM-768 is the usual choice and the one in hybrid TLS and SSH.

Every set gives the same 32-byte secret. What grows is the public key and the ciphertext, which cross the network in every handshake.

Worked example: bytes on the wire

AlgorithmPublic keyCiphertextSecretSecurity level
X25519 (classical)3232 (a second public key)32Broken by Shor
ML-KEM-512800768321
ML-KEM-76811841088323
ML-KEM-102415681568325

The cells students fill in are left blank in this preview.

The three steps in OpenSSL

genpkey makes the key pair, and pkey -pubout copies out the public part to give away. pkeyutl -encap takes that public key and writes a ciphertext and a secret. pkeyutl -decap takes the private key and the ciphertext and writes the secret again.

Every Run reaches the workstation with docker exec pq, in its folder /lab.

List the KEMs OpenSSL knows

Command
docker exec pq sh -c "openssl list -kem-algorithms | grep -i ml-kem"

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Make an ML-KEM-768 key pair

Command
docker exec pq openssl genpkey -algorithm ML-KEM-768 -out kem.pem

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Copy out the public key

Command
docker exec pq openssl pkey -in kem.pem -pubout -out kem.pub

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

See the parts of the private key

Command
docker exec pq sh -c "openssl pkey -in kem.pem -text -noout | grep -v '^ '"

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Encapsulate: the sender's step

Command
docker exec pq openssl pkeyutl -encap -inkey kem.pub -pubin -out ct.bin -secret sent.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Decapsulate: the owner's step

Command
docker exec pq openssl pkeyutl -decap -inkey kem.pem -in ct.bin -secret got.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Are the two secrets the same?

Command
docker exec pq diff -qs sent.bin got.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Measure the ciphertext and secrets

Command
docker exec pq wc -c ct.bin sent.bin got.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Measure the public key in DER

Command
docker exec pq sh -c "openssl pkey -pubin -in kem.pub -outform DER | wc -c"

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

What the Runs print

RunWhat it prints
list -kem-algorithmsThree lines, ML-KEM-512, ML-KEM-768 and ML-KEM-1024, each with its number and short name
pkey -textML-KEM-768 Private-Key:, then seed:, dk: and ek:
diff -qsFiles sent.bin and got.bin are identical
wc -c1088 ct.bin, 32 sent.bin, 32 got.bin, 1152 total
DER size1206: the 1184-byte key plus a 22-byte label naming the algorithm

The cells students fill in are left blank in this preview.

A wrong key gives a wrong secret

What if someone decapsulates with the wrong private key? ML-KEM does not stop with an error. It gives back a secret that looks random and matches nothing.

This is called implicit rejection. An error message would tell an attacker something, so ML-KEM gives nothing away. The mismatch shows up later, when the two sides cannot decrypt each other.

A stranger makes a key pair

Command
docker exec pq openssl genpkey -algorithm ML-KEM-768 -out stranger.pem

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

The stranger decapsulates the ciphertext

Command
docker exec pq openssl pkeyutl -decap -inkey stranger.pem -in ct.bin -secret wrong.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Compare with the real secret

Command
docker exec pq diff -qs sent.bin wrong.bin

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think decapsulating with the wrong key fails with an error. In ML-KEM it succeeds and prints nothing, and diff then says Files sent.bin and wrong.bin differ. So never treat a quiet decapsulation as proof the key was right: check the session that follows.

About this lab and its source: Post-quantum cryptography lab: ML-KEM, ML-DSA, hybrid TLS and post-quantum SSH with OpenSSL 3.5 and OpenSSH 10

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.