Skip to content
Lesson 5 of 10

Step 1 of 5 · Reading · ~3 min

Read

Cryptography & Handshake

The Key Schedule: HMAC, KDF and the Handshake Chain

After this lesson your program replays the key schedule half of a real WireGuard handshake message: from the responder's public key, the initiator's ephemeral key and one Diffie-Hellman result, it derives the same chaining key, transcript hash and first encryption key as the Linux kernel.

Two running values

A Noise handshake keeps two 32 byte values and updates them after every step:

  • the chaining key C: all secrets mixed so far. Nobody can compute the next C without the previous one and the new secret.
  • the hash H: a digest of every public byte sent so far, the transcript. Both sides must hold the same H or the first authenticated message fails.

The hash function is BLAKE2s with a 32 byte output (RFC 7693; the starter gives you a working one). WireGuard starts both values from public constants:

C0 = HASH("Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s")
   = 60e26daef327efc02ec335e2a025d2d016eb4206f87277f52d38d1988b78cd36
H0 = HASH(C0 || "WireGuard v1 zx2c4 [email protected]")
   = 2211b361081ac566691243db458ad5322d9c6c662293e8b70ee19c65ba079ef3

|| is byte concatenation. Mixing a public value into the transcript is H = HASH(H || value), so a single changed byte anywhere changes every later H.

HMAC and the KDF

HMAC (RFC 2104) turns a hash into a keyed hash. The block size of BLAKE2s is 64 bytes, which is not its 32 byte output size. Pad the key with zero bytes to 64 bytes (hash it first if it is longer than 64), then:

inner = HASH((padded_key XOR 0x36 repeated 64 times) || message)
HMAC  = HASH((padded_key XOR 0x5c repeated 64 times) || inner)

WireGuard's KDF (whitepaper section 5.4) is HKDF in one function. Kdf_n(key, input) returns n 32 byte outputs:

t0 = HMAC(key, input)               the "extract" step, key first, input second
t1 = HMAC(t0, 0x01)
t2 = HMAC(t0, t1 || 0x02)
t3 = HMAC(t0, t2 || 0x03)

and the outputs are t1 up to tn. The counter is one raw byte, not the text "1". With an empty input and n = 2 this is exactly how the two transport keys are derived at the end of a handshake.

The chain for message 1

The initiator already knows the responder's static public key S, makes an ephemeral key pair E, and computes dh = DH(E private, S) (your X25519 from the last lesson). The order is fixed:

StepUpdate
1`H1 = HASH(H0
2C1 = Kdf1(C0, E public) and `H2 = HASH(H1
3(C2, K) = Kdf2(C1, dh): C advances and K, a fresh key, falls out

K is what the next lesson uses to encrypt the initiator's static key. Notice that C moves only through the KDF and H only through the hash.

Common mistakes

  • HMAC block size 32. The pad is 64 bytes. A pad of 32 gives a value that looks fine and never matches.
  • Counter as text. 0x01 is one byte with value 1. The character 1 is 0x31.
  • Swapping key and input. In Kdf and in HMAC the key comes first. Swapped, the extract step silently uses the secret as the message.
  • Forgetting the previous output. From t2 on, the message is the previous output followed by the counter byte.
  • Mixing the wrong value into the wrong chain. The ephemeral public key goes into C through the KDF and into H through the hash, both.

Your exercise

The starter gives you BLAKE2s, hex handling and the command loop. You write HMAC, the KDF and the message 1 chain. The most likely mistake is using 32 instead of 64 as the HMAC block size.

Up nextAEAD Encryption (ChaCha20-Poly1305)Cryptography & Handshake

Discussion

Ask a question, share an insight, or help someone who’s stuck.

Sign in to post a comment or reply.

Loading…