The time has come to settle the course's oldest debt. Since 02-01, every time we used AES-GCM or HMAC we parked the same question: how did the secret key get to both sides without anyone intercepting it? In 04-01, asymmetric cryptography gave a partial answer (encrypting toward a public key), but there was another idea, earlier and more elegant, published by Diffie and Hellman in 1976: two people who have never met can agree on a shared secret talking over a public channel where everyone listens, and the eavesdropper still learns nothing about the secret. It sounds like magic; it's arithmetic. In this lesson you'll see the intuition (mixing colors), a toy Diffie-Hellman with small integers, its modern version with X25519, how to turn the shared secret into a real AES key with HKDF, and what ephemerality and forward secrecy are. And you'll discover the fatal flaw that this whole thing carries — an attack with a name of its own — which only the signatures from 04-03 and module 5's certificates will be able to close.

1. The problem, stated precisely
2. The intuition: mixing colors
3. Toy Diffie-Hellman with small integers
4. Modern ECDH: X25519 in pyca/cryptography
5. From shared secret to key: HKDF
6. Full demonstration: MediNube ↔ Clínica Sol
7. Ephemeral keys and forward secrecy
8. The fatal flaw: man-in-the-middle
9. How the hole gets closed (and where)

Let's pin down the challenge precisely, because its solution is counterintuitive. Two parties — MediNube and Clínica Sol — want to agree on a common secret key to then encrypt with AES-256-GCM (module 2). The conditions:

• They've never shared anything before: there's no prior secret to start from.
• The only channel is public: an attacker, whom we'll always call by her role, can read everything that's transmitted.
• In the end, both must have the same secret, and the attacker — who has watched every byte go by — must not be able to compute it.

That this is possible seems to defy common sense: if the spy sees everything that's said, how can she not repeat the calculation? The answer lies in the one-way functions you already know: data is exchanged that lets each party finish the calculation using their own private secret, but that leaves the spy, who has no private secret, locked out at the door.

The classic analogy, and the best one. Imagine mixing paints is easy, but separating a mix back into its original colors is practically impossible (that's the "one-way function"):

1. MediNube and Clínica Sol agree in public on a base color, say yellow. The attacker sees it: doesn't matter.
2. Each party privately picks a color of their own and tells no one. MediNube picks red; the clinic picks blue.
3. Each party mixes their secret with the public yellow and sends the mix over the channel. MediNube sends orange (yellow+red); the clinic sends green (yellow+blue). The attacker watches the orange and the green fly across the network.
4. Each party adds their own secret to the mix they received. MediNube takes the green and adds its red; the clinic takes the orange and adds its blue. Both arrive at the same final color (yellow+red+blue): a shared brown.

The attacker has the yellow, the orange, and the green. To get to brown she'd need the red or the blue, and those never traveled: to extract them she'd have to "separate" a mix, which is exactly what's infeasible. The private secrets (red, blue) never leave their owners; only the mixes travel. Swap "mixing paints" for a mathematical one-way operation and you have Diffie-Hellman.

Toy-example warning (golden rule 1). Ridiculously small numbers, without any of the checks a real DH requires. It's here to show the mechanism, nothing more. In production, X25519 from pyca/cryptography.

The one-way operation of classic DH is modular exponentiation: pow(g, x, p) is easy; recovering x from the result (the discrete logarithm, a relative of the elliptic one from 04-02) is infeasible with a large p. The "yellow" is two public numbers: a prime p and a base g.

The heart of it is an equality of powers: (g^b)^a = g^(b·a) = g^(a·b) = (g^a)^b (mod p). Each party reaches g^(a·b) mod p by a different route, using their own secret exponent. The attacker sees p, g, A=8, and B=19, but to compute g^(a·b) she'd need a or b, and extracting them from A or B is the discrete logarithm — infeasible with large parameters.

That loop, which breaks the toy example in microseconds, is exactly what becomes impossible as p grows. Classic DH is still alive (in its elliptic-curve variant), but with enormous numbers and checks we've skipped here. That's why we move on to the modern version.

ECDH (Elliptic Curve Diffie-Hellman) is the same protocol over the curve arithmetic from 04-02: the secrets are scalars, the public keys are points, and the "combination" is scalar multiplication. With X25519 (the curve MediNube chose in 04-02 for exchange), the API hides all the arithmetic behind a single method, exchange():

Map each line against the toy example and against the colors: generate() is picking the secret (red/blue) plus publishing the mix (orange/green); exchange(other_party_public) is the final combining step. Nothing about the private key ever leaves the object. And since generating an X25519 pair is practically free (04-02), there's no problem creating a new one for every exchange — the foundation of section 7's forward secrecy.

Fatal temptation: use secret_mn (those 32 bytes) directly as an AES-256 key. Don't. The secret from a DH/ECDH exchange isn't a uniform key: it's a mathematical element of the curve with possible structure and bias, not a uniformly random bit string. Feeding it straight into AES violates the principle that keys must be uniform.

The right tool you already know from 02-04: HKDF (HMAC-based Key Derivation Function). HKDF "condenses" that secret into a cryptographically uniform key of whatever size you want, and along the way lets you bind the key to a context with the info parameter — just like we did with b"medinube:historiales:v1":

The info with its versioned tag (:v1) is the same pattern from the course: a key derived for the "canal-clinica" purpose never collides with one derived for, say, b"medinube:backup:v1", even though both start from the same secret. Crypto-agility (golden rule 8) baked into the name.

Let's put the three pieces together — ECDH + HKDF + AES-GCM — for what we've been promising since 02-01: sending a fragment of a Clínica Sol record to MediNube, establishing the key on the fly, with no prior secret. We reuse module 2's v1 format (version(0x01)||nonce(12)||ciphertext+tag) and its per-patient AAD:

We've done it: two parties with no prior secret, a channel where everything is visible, and yet a record encrypted with a key that never traveled. Every primitive from the course finds its place: X25519 agrees, HKDF condenses, AES-GCM protects, the AAD binds the ciphertext to the patient. API note: public_bytes_raw() / from_public_bytes() are X25519's compact form (32 raw bytes); you can also use PEM (SubjectPublicKeyInfo) as in 04-01/04-02 if you prefer a self-describing format.

Notice that in the demo, each X25519 pair was generated with generate() on the spot and never saved anywhere. That's an ephemeral key: used for one exchange and discarded. The alternative would be static keys (fixed, reused on every connection). The difference has a name and enormous consequences: forward secrecy (also perfect forward secrecy, PFS).

Imagine the attacker records today all the encrypted traffic between Clínica Sol and MediNube — she can't read it, but she archives it. And tomorrow, through carelessness, a theft, or a court order, she gets one party's private key. Can she now decrypt what she recorded?

The key to forward secrecy: since ephemeral private keys are destroyed after each exchange, compromising a party's long-term key doesn't reveal already-negotiated session secrets — those secrets no longer exist anywhere. Each conversation stays protected "going forward" against future compromises. This is where 04-02's promise pays off: generating an EC pair is so cheap that doing it per connection costs nothing, and that's why forward secrecy is today's standard (the final "E" in ECDHE in TLS means exactly ephemeral).

And now the bad news, the same shadow that has been following the whole module. Go back to the demonstration and ask yourself 04-01's and 04-03's question: when MediNube receives pub_cs_bytes, how does it know those 32 bytes really are Clínica Sol's public key? It doesn't. They're bytes that arrived over a public channel. And that's where the attack slips in.

Enter MalloryClinic, an attacker sitting in the middle of the channel (a compromised router, a hostile wifi, a poisoned DNS). Instead of just listening (which DH is immune to), she intercepts and substitutes the public keys: she performs two exchanges, one with each party, impersonating the other in each one.

The result is devastating and silent: Clínica Sol establishes an encrypted channel with Mallory believing she's talking to MediNube; MediNube establishes another with Mallory believing it's talking to the clinic. Mallory decrypts each message with one key, reads it (ana.perez's record, in the clear, right before her eyes), re-encrypts it with the other, and forwards it. Both ends see a channel that "works": messages arrive, decrypt, everything looks correct. Diffie-Hellman's mathematics is perfect; the broken link is, once again, the authenticity of the public keys.

Diffie-Hellman, by itself, guarantees confidentiality against a passive eavesdropper, but not against an active attacker who can modify traffic. Unauthenticated DH is a house with no lock: gorgeous inside, open to whoever pushes the door.

The cure is to authenticate the exchange's public keys: let each party prove that the key it's sending is truly theirs. And to "prove authorship" you already have the tool from the previous lesson: digital signatures. If Clínica Sol signs its ephemeral public key with its long-term Ed25519 key, MalloryClinic won't be able to substitute it — she doesn't know how to forge the clinic's signature. This combination (ephemeral DH for the secret + long-term signature for authentication) is exactly what modern TLS uses, and it has a name: authenticated ephemeral DH.

But notice that this only shifts the problem: to verify Clínica Sol's signature, MediNube needs its authentic Ed25519 public key... and how does it know that one belongs to the clinic? It's the uncomfortable question from 04-01 and 04-03, now unavoidable: you need someone trustworthy to certify which public key belongs to whom. That infrastructure — X.509 certificates and certificate authorities — is module 5, and TLS (which combines ECDHE + certificates + AES-GCM exactly as done here, and which you'll see in 05-02) is its flagship application. We leave it, one last time, explicitly open: we now have almost every piece; what's missing is the one that gives trust to public keys.

Before we go there, one lesson remains that ties together this module's two threads — encrypting toward someone (04-01) and agreeing on a key (this one) — into the pattern the real world uses to actually encrypt: hybrid encryption, in 04-05.

• Using the raw ECDH secret as a key. Mistake number one. exchange() doesn't return a ready-to-use key: it returns material that must go through HKDF. Skipping the KDF is a real security failure, not a technicality.
• Believing Diffie-Hellman authenticates. It doesn't: it gives confidentiality against a passive eavesdropper and nothing against an active man-in-the-middle. DH agrees on a secret with whoever is on the other end, no matter who that is. Authenticating the keys is a separate step (signatures + certificates).
• Reusing static DH keys when you could use ephemeral ones. You give up forward secrecy: a future compromise of the key decrypts all recorded past traffic. With X25519, generating a pair per session is nearly free — do it.
• Confusing X25519 with Ed25519 (again). X25519 is only for exchange (exchange); Ed25519 is only for signing (sign). They don't share an API and aren't interchangeable. Each purpose, its own pair.
• Reusing the AES-GCM nonce between channel messages. The key coming from a DH exchange doesn't exempt you from module 2's rule: a fresh nonce per message. A session key doesn't authorize repeating nonces.
• Implementing classic DH by hand with pow. The toy example skips validating parameters, checking that received keys are in the right group, and defending against small subgroups. X25519 was designed so none of that can blow up on you: use it.
• Forgetting HKDF's info or reusing it across different purposes. The b"medinube:canal-clinica:v1" label is what cryptographically separates this key from any other derived from the same secret. A clear, versioned label per use.

1. Toy example by hand. With p = 23, g = 5, MediNube's secret a = 4, and the clinic's secret b = 3: compute A, B, and check that both parties arrive at the same secret. Then put yourself in the attacker's shoes: recover a by brute force from A. Explain in one sentence why that brute force becomes impossible with a 2048-bit p.

2. Full channel with forward secrecy. Write open_channel() that returns the channel's AES-256 key, derived by both parties with ephemeral X25519 + HKDF (info=b"medinube:canal-clinica:v1"), and use that key so MediNube can send Clínica Sol the v1 envelope of a short message with AAD paciente=ana.perez;formato=v1. Then generate a second channel with open_channel() and check that its key differs from the first. What security property have you just demonstrated, and why does it protect already-recorded traffic?

3. The attack in code. Simulate MalloryClinic without any encryption, just the keys: generate ephemeral pairs for the clinic, for MediNube, and two for Mallory. Compute (a) the secret the clinic would believe it shares (its private key × the public key it received, which is Mallory's) and (b) the one MediNube would believe it shares. Check that the clinic and MediNube don't share a secret with each other, but that Mallory shares one with each of them. Explain what would have prevented the attack.

That brute force — trying every exponent until A is reproduced — is the discrete logarithm. With a 2048-bit p, the number of possible exponents is astronomical and no efficient shortcut exists, so the attack that takes microseconds here would take longer than the age of the universe.

You've demonstrated forward secrecy: since each session uses an ephemeral pair that gets discarded, the keys of two sessions are unrelated. If tomorrow the attacker steals a long-term private key, she can't reconstruct a past session's key — that ephemeral private key no longer exists — so yesterday's recorded traffic stays unreadable.

The clinic and MediNube believe they have a shared channel, but each of them has it with Mallory, who reads and forwards in the middle. What would have prevented it: authenticating the public keys — if the clinic signed its ephemeral public key with its long-term Ed25519 key (04-03), Mallory couldn't substitute it without forging that signature. And to verify that signature, you need to know the clinic's authentic Ed25519 key — the trust problem from module 5.

02-01's debt is settled. Diffie-Hellman lets two parties with no prior secret agree on a common key over a public channel: each one picks a private secret, publishes a "mix" (pow(g, a, p) in the classic version; a point in ECDH), and combines the other party's mix with its own secret to arrive at the same result — while the eavesdropper, who has seen everything, is locked out by the discrete logarithm. In practice you use X25519 with exchange(), its raw secret is never used directly but instead goes through HKDF (info=b"medinube:canal-clinica:v1") to get the AES-256-GCM key, and keys are generated ephemeral to gain forward secrecy: stealing the long-term key doesn't decrypt the past. You put it all together — X25519 + HKDF + AES-GCM — to send a record from Clínica Sol to MediNube. But DH has an Achilles' heel that isn't mathematical but one of identity: without authenticating the public keys, MalloryClinic sits in the middle and reads everything without anyone noticing. Authentication begins with 04-03's signatures and is completed with module 5's certificates — and TLS (05-02) does exactly what you've done here, ECDHE included. Before that, one last piece of the module: joining "encrypting toward someone" and "agreeing on a key" into the pattern the real world uses to actually encrypt. It's hybrid encryption, in 04-05. See you there.