feat(Protocols): Key exchange protocols and Diffie-Hellman by ChristianoBraga · Pull Request #473 · leanprover/cslib

ChristianoBraga · 2026-04-06T20:55:46Z

Summary

Add a KeyExchangeProtocol class capturing the structure of key exchange with pub, sharedSecret, and an agreement property ensuring both parties compute the same shared secret.
Add Diffie-Hellman key exchange as an instance in a finite cyclic group of order q with a generator g, carrying hq : Fintype.card G = q and hg : orderOf g = q. Includes helper lemmas pow_mod_q and secret_eq.

Scope

This PR formalises only the correctness (agreement) of the exchange. It does not model the Diffie-Hellman security assumptions (DLP, CDH, DDH) or any adversarial setting — those require a probabilistic framework to be added separately.

Files

Cslib/Systems/Distributed/Protocols/Cryptographic/KeyExchange/Basic.lean — abstract key-exchange typeclass.
Cslib/Systems/Distributed/Protocols/Cryptographic/KeyExchange/DiffieHellman.lean — Diffie-Hellman instance.
references.bib — add BonehShoup entry (online draft).

References

Boneh & Shoup, A Graduate Course in Applied Cryptography, Section 10.4.

Test plan

lake build passes with no errors on both files.
CI workflow succeeds.

AI disclosure

Claude Code (Anthropic) was used as a pair-programming assistant throughout this PR: drafting and iterating on the typeclass design, suggesting Mathlib lemmas (e.g. pow_card_eq_one, Nat.div_add_mod), proposing and refining the module documentation, and helping address reviewer feedback. All algebraic content and Lean proofs were reviewed and accepted by the author; the underlying mathematics follows Boneh & Shoup, Section 10.4.

SamuelSchlesinger · 2026-04-21T17:52:56Z

@@ -0,0 +1,99 @@
+/-


This file doesn't build because Diffie-Hellman.lean isn't a valid module name.

Since my contribution is stand alone, I only compiled the files themselves and not the entire cslib.
I will fix it!

SamuelSchlesinger

Overall, it appears the author did not build this to ensure it worked locally, so there are several issues. I tried to give a thorough review despite this.

SamuelSchlesinger · 2026-04-21T17:59:27Z

+Let G := {gᵃ : a = 0, …, q − 1}, so that G is a subset of ℤₚ* of cardinality q. It is not hard
+to see that G is closed under multiplication and inversion; that is, for all u, v ∈ G,
+we have u·v ∈ G and u⁻¹ ∈ G. Indeed, gᵃ · gᵇ = gᵃ⁺ᵇ = gᶜ with c := (a + b) mod q, and (gᵃ)⁻¹ = gᵈ
+with d := (−a) mod q. In the language of algebra, G is called a subgroup of the group ℤₚ*.


The module documentation describes a specific cryptographic setup with primes p, q, and a subgroup of ℤₚ*, but this instance is for any CommGroup G, any g : G, and any q : ℕ. The documentation should say the formalization only models the agreement equation, not the full DH setup/security assumptions. It should also be as general as the definition.

I will rewrite the whole documentation to make it more consistent.

SamuelSchlesinger · 2026-04-21T18:07:12Z

+  agreement := by
+    intro α β
+    show (g ^ β.val) ^ α.val = (g ^ α.val) ^ β.val
+    rw [← pow_mul, ← pow_mul, mul_comm]


This proves the algebraic agreement equation for exponentiation in a commutative group, but it is
more general and weaker than the Diffie-Hellman setup described in the module documentation. The
instance does not encode that G is a cyclic subgroup of order q, that g has order q, that q is
prime, or that public values live in the subgroup generated by g. If this is intended as a
formalization of Diffie-Hellman, those parameters and invariants should be represented explicitly.
Otherwise, the documentation should describe this as the exponentiation-based key-agreement
skeleton rather than the Diffie-Hellman protocol.

I will tight this up, thank you!

SamuelSchlesinger · 2026-04-21T18:19:24Z

+Reference:
+
+* [D. Boneh and V. Shoup,V., *A Graduate Course in Applied Cryptography*, One-time pad][BonehShoup],
+  Section 10.4.


This is incorrect, referencing the one-time pad not DH.

I will fix it!

SamuelSchlesinger · 2026-04-21T18:19:41Z

+
+Reference:
+
+* [D. Boneh and V. Shoup,V., *A Graduate Course in Applied Cryptography*][BonehShoup],


This citation is missing from the references.bib.

I will fix it!

SamuelSchlesinger · 2026-04-21T18:21:28Z

+  Section 10.4.
+-/
+
+instance DiffieHellmanKE {G : Type u} [CommGroup G] (g : G) (q : ℕ) :


This should not be an instance. The instance is not actually synthesizable after I renamed it on my end. Just make it a struct and a def.

This should also be in a namespace.

Is it conceptually wrong to have DH as an instance of KeyExchangeProtocol?

It is not conceptually wrong, but ergonomically wrong in this case because you're defining it for a free variable G and ZMod q. If you want to do it this way, defining wrappers here is probably the way, or using some singleton tag type. I would personally prefer to use it as a structure myself.

SamuelSchlesinger · 2026-04-21T18:22:17Z

+
+universe u v w
+
+class KeyExchangeProtocol


We should define this in a namespace, not in the root. This is true across the whole file.

Yes!, I will fix it.

SamuelSchlesinger · 2026-04-21T18:23:38Z

+omit [Fact q.Prime] in
+theorem secret_eq (α β : ZMod q) :
+    (g ^ β.val) ^ α.val = g ^ (α * β).val := by
+  rw [← pow_mul, ZMod.val_mul, mul_comm β.val α.val, pow_mod_q hG]


Fact q.Prime appears to be dead code.

chenson2018

Hi @ChristianoBraga, thanks for your interest in contributing! Can I ask that you disclose any AI usage in the PR description? There seem to be some patterns of AI usage based on the review that was just left.

- Rename Diffie-Hellman.lean → DiffieHellman.lean (valid module name). - Align namespaces under ...Cryptographic.KeyExchange; DH lives in ...KeyExchange.DH as a sibling sub-namespace. - Tighten the DiffieHellman class with [Fintype G], hq : Fintype.card G = q, and hg : orderOf g = q, so that g is a generator of a cyclic group of order q (previously under-constrained). - Remove dead Fact q.Prime hypothesis. - Rewrite module docstrings to match the actual generality of the code and add an explicit Scope note: correctness only, not DLP/CDH/DDH. - Upgrade pow_mod_q / secret_eq prose to /-- ... -/ doc-strings. - references.bib: switch BonehShoup entry to the online draft with URL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Add KeyExchangeProtocol class with agreement property and Diffie-Hellman as an instance over commutative groups.

- Rename Diffie-Hellman.lean → DiffieHellman.lean (valid module name). - Align namespaces under ...Cryptographic.KeyExchange; DH lives in ...KeyExchange.DH as a sibling sub-namespace. - Tighten the DiffieHellman class with [Fintype G], hq : Fintype.card G = q, and hg : orderOf g = q, so that g is a generator of a cyclic group of order q (previously under-constrained). - Remove dead Fact q.Prime hypothesis. - Rewrite module docstrings to match the actual generality of the code and add an explicit Scope note: correctness only, not DLP/CDH/DDH. - Upgrade pow_mod_q / secret_eq prose to /-- ... -/ doc-strings. - references.bib: switch BonehShoup entry to the online draft with URL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ChristianoBraga requested review from chenson2018 and fmontesi as code owners April 6, 2026 20:55

SamuelSchlesinger reviewed Apr 21, 2026

View reviewed changes

SamuelSchlesinger suggested changes Apr 21, 2026

View reviewed changes

chenson2018 requested changes Apr 21, 2026

View reviewed changes

ChristianoBraga and others added 2 commits April 22, 2026 23:14

feat(Protocols): Key exchange protocols and Diffie-Hellman

39b2080

Add KeyExchangeProtocol class with agreement property and Diffie-Hellman as an instance over commutative groups.

ChristianoBraga force-pushed the key_exchange_pr branch from fad8e56 to ebbca7f Compare April 22, 2026 21:20


		Reference:

		* [D. Boneh and V. Shoup,V., A Graduate Course in Applied Cryptography][BonehShoup],

Conversation

ChristianoBraga commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Files

References

Test plan

AI disclosure

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChristianoBraga Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SamuelSchlesinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chenson2018 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ChristianoBraga commented Apr 6, 2026 •

edited

Loading

ChristianoBraga Apr 22, 2026 •

edited

Loading