Cheatsheet for PQC stuff. Note that the maintainer is not an expert in applied mathematics or quantum computing. This repository is intended as a practical cheatsheet for a programmer who uses Rust TLS libraries in a world that may or may not soon have useful quantum computers. See contribution guidelines at the bottom if you want to clarify something.

---

Post-Quantum Cryptography: TLS

TLS makes use of many mathematical ideas that may no longer be useful for their intended purpose in a future where a quantum computer might exist that can execute e.g. Shor's or Grover's algorithms reliably at a meaningful scale. As of early 2026, such a quantum computer doesn't seem to exist, but there is enough speculation about the field's progression speed for some institutions to have set deadlines for transitioning to solutions prepared for a future where one does exist.

In this repository, some effort has been made to demonstrate WHAT, WHY and HOW should something be changed in a TLS client and server written in Rust, using libraries that are commonly used for that purpose at the time of writing: the rustls ecosystem which I consider to cover crates like rustls, rcgen and aws-lc-rs.

Demo: Run server first; it'll write a cert (to be trusted by the client) to disk:

$ cargo run --bin tls-server
$ cargo run --bin tls-client

What Happens in a TLS Connection?

• Asymmetric Signing and Verification

  The server presents a certificate chain (a Certificate Authority certificate and an End Entity certificate signed by it). The client verifies that the End Entity certificate was signed by a CA it trusts. This establishes that the server is who it claims to be. In this repository, ML-DSA-87 is used for both the signing (server side) and the verification (client side).

• Key Exchange and Encapsulation

  Before any application data is sent, the client and server negotiate a shared session key without ever transmitting it directly. In this repository, X25519MLKEM768 is used: a hybrid scheme that combines classical X25519 with ML-KEM-768 so that the session key is secure as long as either of the two components is unbroken.

• Symmetric Encryption

  All application data is encrypted with a symmetric cipher using the session key. In this repository, AES-256-GCM is used (via the default rustls cipher suite selection). The 256-bit key length is important for quantum resilience; see Grover's Algorithm below.

How Might a Quantum Computer Change TLS Landscape?

• Shor's Algorithm

  Some asymmetric cryptography parts of TLS often make use of RSA or Elliptic Curve algorithms. These are broken by Shor's Algorithms.

  RSA relies on the fact that factoring a product of two large prime numbers back into its factors is computationally hard. One of Shor's algorithms solves this factorization problem on a quantum computer efficiently enough to make RSA no longer useful for its intended purpose.

  Elliptic Curve algorithms rely on Discrete Logarithm Problem, which is also easy to solve one way but hard to reverse, similar to the factoring problem.

  A different family of mathematical problems is considered hard for quantum and classical computers alike: problems involving concepts called modules and lattices. A lattice is a grid of points in very high-dimensional space. The hard problem is finding the shortest vector in such a lattice, or a close approximation to it - something that presumably remains hard even given Shor's algorithms. Algorithms named with the "ML" prefix are built on these problems:

  • ML-KEM (Module-Lattice-Based Key-Encapsulation Mechanism) is used for session key exchange. In this repository the X25519MLKEM768 hybrid group is used, combining classical X25519 with ML-KEM-768.

  • ML-DSA (Module-Lattice-Based Digital Signature Algorithm) is used for certificate signing and verification. In this repository ML-DSA-87 is used.

  Learning material:

  • The Story of Shor's Algorithm, Straight From the Source | Peter Shor by Qiskit on YouTube: https://youtu.be/6qD9XElTpCE (accessed 2026-03-08).

  • Lattice-based cryptography: The tricky math of dots by Chalk Talk on YouTube: https://youtu.be/QDdOoYdb748 (accessed 2026-03-08).

• Grover's Algorithm

  TLS makes use of symmetric cryptography too, which is weakened by Grover's Algorithm.

  Unstructured search problems, such as brute-forcing symmetric encryption keys, can be solved on a quantum computer using Grover's algorithm much faster than on a classical computer. The speedup is quadratic. In practice this means a key weakens to be only as strong as a key half its length was. For example, a 128-bit AES key is only as strong against a quantum computer as a 64-bit AES key is against a classical computer.

  To mitigate this, symmetric keys should be at least twice as long as whatever is considered a minimum secure length in classical computing. AES-256 is therefore the appropriate choice.

  Learning material:

  • But what is quantum computing? (Grover's Algorithm) by 3Blue1Brown on YouTube: https://youtu.be/RQWpF2Gb-gU (accessed 2026-03-08).

  Update 2026-04-21: I've seen mixed claims with regards to symmetric keys's sizes. Here's an article claiming that "no symmetric key sizes have to change as part of the post-quantum transition" and that having to double the key length is a "common misconception": https://words.filippo.io/128-bits/ (accessed 2026-04-21). Just pointing this out based on trending in Hacker News. I don't know what's the truth. Anyway, bigger keys are probably not worse from security perspective at least.

Contributing

If you notice a problem in this repository and want to do something about it, feel free to submit a patch and a maintainer might merge it if they have time and if they can understand what your patch is trying to convey. Please try to be very clear and illustrative in your delivery, as the subject is not the simplest one out there and the reviewer might not have the necessary knowledge beforehand. Keep in mind that any submitted patch is not automatically entitled to a maintainer's time.

Coding Style and Implementation Scope

Below are some notes on how the maintainers like to write code, for your information in case you wish to contribute.

• Dependencies

  All features must be explicitly listed. No implicit default features are used. Versions are tightly locked.

• Namespace Pollution

  Every statement is fully qualified. Every statement fully conveys what libraries it makes use of, without requiring knowledge of how the containing namespace might have been polluted. The practical motivation for this is to make refactoring easy by keeping every block of code self-contained.

• Inference

  Every type is explicitly declared if possible unless it makes the code too hard to read. The practical motivation for this is to make every assignment understandable without knowledge of function signatures.

• Scope

  In scope: Modern Debian Linux on x86-64 architecture. Out of scope: Any cross-platform concerns. The practical motivation is that servers typically run on ordinary Linux boxes; more esoteric targets are not interesting for this project.

  In scope: Rust as it is typically written. Out of scope: Niche Rust libraries and any language other than Rust. The practical motivation is that this repository should not have unnecessary bloat, to make it maximally useful for programmers who work with Rust.

• Comments

  Comments explain code structure with regard to key concepts of the problem domain. Self-explanatory code is still preferred over comments.