PQBlocks

Verified building blocks for the post-quantum transition.

PQBlocks is an open-source engineering organisation for the post-quantum (PQ) era. It builds the pieces a real migration needs: NIST-standard cryptography in hybrid modes, tools that find and score the cryptography you already run, formats and protocol checks that carry post-quantum data, conformance against official vectors, and quantum-inspired optimisation. Each package lives in its own repository, ships its tests and evidence, and says what it does not do.

Package catalog Recipes GitHub

Built on FIPS 203 · FIPS 204 · FIPS 205 · RFC 7748 · RFC 5869 · CycloneDX 1.6 · NIST ACVP

Separate blocks, one machine. Point at a block, then at the core.

What is the post-quantum transition?

A cryptographically relevant quantum computer (CRQC) running Shor's algorithm would break RSA, Diffie–Hellman and elliptic-curve cryptography: the public-key algorithms behind TLS, code signing, tokens and encrypted archives. Data recorded today can be decrypted once such a machine exists, which is why the threat is called harvest now, decrypt later. In August 2024 NIST published the replacements as final standards: ML-KEM (FIPS 203) for key establishment, ML-DSA (FIPS 204) and SLH-DSA (FIPS 205) for signatures. NIST's transition guidance (NIST IR 8547, draft) deprecates today's 112-bit public-key algorithms after 2030 and disallows them after 2035, and the NSA's CNSA 2.0 sets similar deadlines for national security systems. Changing the algorithm is the small part. The work is finding every use, migrating safely, carrying larger keys through real protocols and proving the result.

Areas

Area	What it covers	Packages
PQ cryptography	ML-KEM, ML-DSA and SLH-DSA through maintained implementations, hybrid key establishment and signatures, and safe defaults for files and tokens.	4
Migration & readiness	Find cryptography in code and on the wire, emit CBOMs, score readiness, gate CI with policy-as-code and assemble compliance evidence.	7
Interoperability	Wire formats, JOSE, X.509/CSR and TLS hybrid groups that carry larger post-quantum keys, ciphertexts and signatures through real protocols.	4
Conformance	Official NIST ACVP vectors and strict FIPS 203/204 boundary checks that prove an implementation and a migration are correct.	2
Quantum-inspired	Classical solvers modelled on quantum dynamics for Ising and QUBO problems. Kept separate from security: no cryptographic claims.	9
	All packages · catalog	26

Coding assistants can use the same catalog through the MCP server, Claude skill and Cursor rules.

Why lattices?

ML-KEM and ML-DSA, the two main NIST post-quantum standards, are built on lattices: regular grids of points generated by a few basis vectors. Their security rests on problems such as Module Learning With Errors, which amount to finding a lattice point close to a given target when the lattice has hundreds of dimensions and the basis is deliberately awkward. In two dimensions, as in the figure, rounding in the basis finds the answer at once. In the dimensions the standards use, no known classical or quantum algorithm does it efficiently, and that gap is what protects the keys.

PQ cryptography packages Glossary: ML-KEM, ML-DSA

Point anywhere on the plane: the closest lattice point answers, reached in whole basis steps.

Crypto agility: replace one block at a time

The post-quantum migration will not be the last. Algorithms will be retired again, parameters will change and new standards such as FN-DSA and HQC will arrive. Systems that can change an algorithm through configuration, without a redesign, are crypto-agile, and they make every future change cheap. PQBlocks packages are built that way: each one does one job, a policy pins the algorithms in use, and downgrades to classical-only cryptography are refused unless you allow them explicitly.

Score your crypto agility Policy-as-code

Start in a minute

Each tab is the package's own quickstart, executed against the package source before this site was published.

Post-quantum KEMEncrypt a fileFind RSA and ECCSolve an Ising problem

ML-KEM-768 with pqblocks-primitives

from pqblocks_primitives import kem_keygen, kem_encaps, kem_decaps

# Generate ML-KEM-768 keypair
pk, sk = kem_keygen("768")

# Encapsulate shared secret
ct, shared_secret_sender = kem_encaps(pk, "768")

# Decapsulate shared secret
shared_secret_receiver = kem_decaps(sk, ct, "768")

assert shared_secret_sender == shared_secret_receiver

Hybrid X25519 + ML-KEM recipe · pqblocks-primitives

ML-KEM-768 + X25519 file encryption with pqblocks-files

from pqblocks_files.encrypt import encrypt, decrypt
from pqblocks_files.keys import keygen

keypair = keygen()                                    # ML-KEM-768 + X25519
blob = encrypt(b"quarterly numbers", [keypair.public])  # fresh random file key every call
assert decrypt(blob, keypair) == b"quarterly numbers"   # refuses classical-only files by default

Full recipe with key files · pqblocks-files

Crypto inventory with pqblocks-scan

from pqblocks_scan.discovery import Discovery
from pqblocks_scan.scorer import CARSScorer
from pqblocks_scan.cbom import CBOMGenerator

src = "import hashlib\nh = hashlib.sha1(b'x').hexdigest()\nfrom pqcrypto.kem import ml_kem_768\n"
assets = Discovery().discover_source(src, "app.py").assets
print([(a.algorithm, a.line_number, a.is_quantum_vulnerable) for a in assets])
# [('ML-KEM-768', 3, False), ('SHA-1', 2, True)]
grade = CARSScorer.evaluate(assets)
print(grade.score, grade.letter)                      # 55.5 C
print(CBOMGenerator.generate(assets)["specVersion"])  # 1.6

Audit recipe · pqblocks-scan

Simulated Bifurcation with pqblocks-bifurcation

import numpy as np
from pqblocks_bifurcation.solver import SimulatedBifurcationSampler

sampler = SimulatedBifurcationSampler(seed=42, mode="dSB")
J = np.array([[0.0, -1.0], [-1.0, 0.0]])   # couplings
h = np.array([0.5, -0.5])                   # local fields
spins, energy = sampler.sample_ising(J, h)
print(spins, energy)                        # [1 1] -1.0

Max-Cut recipe · pqblocks-bifurcation

A package for every step of the migration

The transition map walks through each step, the deadlines behind it and the package that does the work.

How PQBlocks earns trust

• Standards, not inventions. Only standardised or peer-reviewed algorithms. Post-quantum primitives come from maintained implementations such as liboqs.
• Evidence in every repository. TESTING, BENCHMARKS, EVIDENCE, SECURITY_NOTES and a VERIFICATION_REPORT, with benchmarks that include the cases where a package loses. See how we verify.
• Limits stated up front. Packages are pre-1.0. None is FIPS 140-3 or CMVP validated or externally audited, and none claims to be. See security posture.
• Executed documentation. Every quickstart and recipe on this site is run against the package source before it is published.

Frequently asked questions

What is PQBlocks?

PQBlocks is an open-source engineering organisation that builds the components of a post-quantum migration as independent packages: post-quantum cryptography (ML-KEM, ML-DSA, SLH-DSA and hybrid modes), migration tooling (crypto inventory, CBOMs, readiness scoring, policy gates, CNSA 2.0 evidence), interoperability (TLS, JOSE, wire formats, certificate requests), conformance testing against NIST ACVP vectors, and quantum-inspired optimisation. Each package lives in its own repository under github.com/PQBlocks, is licensed Apache-2.0, and ships its tests, benchmarks, primary sources and a verification report. PQBlocks is a QubitRock project.

Which PQBlocks package should I start with?

Start by finding the cryptography you already run. pqblocks-scan inventories RSA, elliptic curves, weak hashes and post-quantum algorithms in source code and TLS endpoints, and writes a CycloneDX 1.6 CBOM and a SARIF report. For new code, use pqblocks-primitives for ML-KEM, ML-DSA and SLH-DSA, pqblocks-jose for post-quantum JWS and JWE tokens, and pqblocks-files for file encryption. The recipes are complete, tested programs for the common tasks.

Are PQBlocks packages FIPS validated?

No. PQBlocks packages implement or wire to the NIST standards FIPS 203, 204 and 205 and test against official vectors where those exist, but none of them is a FIPS 140-3 / CMVP validated cryptographic module, and none claims to be. If you need a validated module, use one, and treat PQBlocks components as the integration, inventory and verification layer around it.

What is post-quantum cryptography?

Post-quantum cryptography (PQC) is public-key cryptography designed to stay secure against an attacker with a large quantum computer. It runs on today's ordinary computers. NIST standardised the first algorithms in August 2024: ML-KEM (FIPS 203) for key establishment, and ML-DSA (FIPS 204) and SLH-DSA (FIPS 205) for digital signatures. They replace RSA, Diffie–Hellman and elliptic-curve cryptography, which Shor's algorithm would break.

When do we need to migrate to post-quantum cryptography?

Now, for planning and inventory. NIST's transition guidance (NIST IR 8547, draft) deprecates 112-bit quantum-vulnerable algorithms such as RSA-2048 and P-256 after 2030 and disallows all quantum-vulnerable public-key algorithms after 2035. The NSA's CNSA 2.0 asks national security systems to prefer post-quantum algorithms from 2025 for software signing and web services and to use them exclusively between 2030 and 2033 depending on the system type. See the transition map for the dates and sources.

Should I use hybrid or pure post-quantum cryptography?

During the transition, hybrid is the safer default: combine ML-KEM with X25519 for key establishment and pair ML-DSA with Ed25519 for signatures. An attacker then has to break both the lattice scheme and the classical one, which protects you if either has an implementation flaw or an unexpected cryptanalytic result. TLS 1.3 already uses the hybrid group X25519MLKEM768. Requirements such as CNSA 2.0 eventually call for post-quantum algorithms on their own, so prefer designs where a policy setting moves you from hybrid to pure.

How do AI coding assistants use PQBlocks?

Add the pqblocks-mcp server to Claude Code, Cursor or any MCP client. It recommends a package for a task, returns its install line and a quickstart executed against the real package, and flags quantum-vulnerable algorithms in pasted code. The Claude skill and Cursor rules give the same guidance without a server, and llms.txt and llms-full.txt give agents the whole catalog in one file.

All questions