pqblocks-skills / rules

---
description: Post-quantum cryptography and quantum-inspired optimisation with PQBlocks packages. Apply when code touches RSA, ECDSA, ECDH, X25519, JWT signing, key exchange, file encryption, CBOM, CNSA 2.0, ML-KEM, ML-DSA, SLH-DSA, QUBO or Ising.
globs:
alwaysApply: false
---

# PQBlocks

1. **Use the documented API only.** Before writing code with a PQBlocks package, read its page under https://pqblocks.github.io/packages/ (or call the `get_snippet` tool of the `pqblocks-mcp` server). Every quickstart there was executed
   against the package. Never guess function names.
2. **Never hand-roll post-quantum cryptography.** Use the packages; they wrap maintained implementations
   (liboqs, pyca/cryptography).
3. **Hybrid by default during the transition:** ML-KEM-768 + X25519 for key establishment, ML-DSA-65 +
   Ed25519 for signatures. Downgrade to classical-only must be explicit.
4. **Randomness from the OS only.** Never pass a `seed` argument when generating production keys; seeds
   exist for reproducible tests.
5. **Never log or return secret keys or shared secrets** (logs, exceptions, HTTP responses, `repr`).
6. **Say exactly what is true.** PQBlocks packages implement FIPS 203/204/205 and test against official
   vectors where they exist. They are **not** FIPS 140-3 / CMVP validated, not externally audited, and
   pre-1.0. Never call them certified, validated, audited or quantum-proof.
7. **Quantum-inspired packages are optimisation, not cryptography.** Never place them in a security path.
8. **Install lines:** use the exact install line listed for each package; most install from GitHub
   until their PyPI release is published.

## Which package for which task

| Task | Package | Install | Import |
|---|---|---|---|
| ML-KEM / ML-DSA / SLH-DSA primitives (keygen, encapsulate, sign) | [`pqblocks-primitives`](https://pqblocks.github.io/packages/primitives/) | `pip install pqblocks-primitives` | `pqblocks_primitives` |
| Hybrid ML-KEM-768 + X25519 key establishment, native speed | [`pqblocks-core`](https://pqblocks.github.io/packages/core/) | `pip install git+https://github.com/PQBlocks/hybrid-sdk` | `pqblocks_core` |
| Sign or verify JWTs / JWS with ML-DSA; encrypt JWE with ML-KEM | [`pqblocks-jose`](https://pqblocks.github.io/packages/jose/) | `pip install pqblocks-jose` | `pqblocks_jose` |
| Encrypt files or byte strings to a post-quantum public key | [`pqblocks-files`](https://pqblocks.github.io/packages/files/) | `pip install pqblocks-files` | `pqblocks_files` |
| Find RSA / ECC / weak hashes in code or a TLS endpoint; CBOM + SARIF | [`pqblocks-scan`](https://pqblocks.github.io/packages/scan/) | `pip install pqblocks-scan` | `pqblocks_scan` |
| Python crypto data-flow linting; CBOM + SARIF | [`pqblocks-lint`](https://pqblocks.github.io/packages/lint/) | `pip install pqblocks-lint` | `pqblocks_lint` |
| Enrich a CycloneDX CBOM with quantum-safety and CNSA 2.0 tags | [`pqblocks-cbom`](https://pqblocks.github.io/packages/cbom/) | `pip install pqblocks-cbom` | `pqblocks_cbom` |
| Crypto-agility readiness score and CI regression gate | [`pqblocks-agility`](https://pqblocks.github.io/packages/agility/) | `pip install pqblocks-agility` | `pqblocks_agility` |
| Policy-as-code: fail CI on forbidden algorithms | [`pqblocks-policy`](https://pqblocks.github.io/packages/policy/) | `pip install pqblocks-policy` | `pqblocks_policy` |
| Audit which JWE / JOSE algorithms a gateway accepts | [`pqblocks-jwe-audit`](https://pqblocks.github.io/packages/jwe-audit/) | `pip install pqblocks-jwe-audit` | `pqblocks_jwe_audit` |
| CNSA 2.0 compliance evidence pack | [`pqblocks-cnsa-evidence`](https://pqblocks.github.io/packages/cnsa-evidence/) | `pip install pqblocks-cnsa-evidence` | `pqblocks_cnsa_evidence` |
| Probe a TLS 1.3 endpoint for X25519MLKEM768; hybrid key-schedule checks | [`pqblocks-tls-interop`](https://pqblocks.github.io/packages/tls-interop/) | `pip install pqblocks-tls-interop` | `pqblocks_tls_interop` |
| Binary container for ML-KEM ciphertexts and ML-DSA / SLH-DSA signatures | [`pqblocks-wire`](https://pqblocks.github.io/packages/wire/) | `pip install pqblocks-wire` | `pqblocks_wire` |
| Five-part hybrid JWE wire layout (serialise / parse only, no encryption) | [`pqblocks-jwe`](https://pqblocks.github.io/packages/jwe/) | `pip install pqblocks-jwe` | `pqblocks_jwe` |
| ML-KEM certificate signing request with proof of possession | [`pqblocks-csr-pop`](https://pqblocks.github.io/packages/csr-pop/) | `pip install pqblocks-csr-pop` | `pqblocks_csr_pop` |
| Run NIST ACVP vectors against ML-KEM / ML-DSA implementations | [`pqblocks-acvp`](https://pqblocks.github.io/packages/acvp/) | `pip install pqblocks-acvp` | `pqblocks_acvp` |
| Reject malformed or wrong-length FIPS 203/204 inputs at a boundary | [`pqblocks-fips-check`](https://pqblocks.github.io/packages/fips-check/) | `pip install pqblocks-fips-check` | `pqblocks_fips_check` |
| Verify post-quantum X.509 certificate chains in browser or Node.js | [`pqblocks-browser-pqc-verifier`](https://pqblocks.github.io/packages/browser-pqc-verifier/) | `npm install git+https://github.com/PQBlocks/browser-pqc-verifier` | `@pqblocks/browser-pqc-verifier` |
| Build or convert QUBO / Ising models | [`pqblocks-qubo`](https://pqblocks.github.io/packages/qubo/) | `pip install pqblocks-qubo` | `pqblocks_qubo` |
| Solve QUBO / Ising / Max-Cut (Simulated Bifurcation) | [`pqblocks-bifurcation`](https://pqblocks.github.io/packages/bifurcation/) | `pip install pqblocks-bifurcation` | `pqblocks_bifurcation` |
| Simulated annealing / quantum annealing / population annealing / QIEA solvers | [`pqblocks-anneal-sa`](https://pqblocks.github.io/packages/anneal-sa/), [`pqblocks-anneal-sqa`](https://pqblocks.github.io/packages/anneal-sqa/), [`pqblocks-population-anneal`](https://pqblocks.github.io/packages/population-anneal/), [`pqblocks-qiea`](https://pqblocks.github.io/packages/qiea/) | `pip install pqblocks-anneal-sa` | `pqblocks_anneal_sa` |
| Benchmark QUBO / Ising solvers (time-to-solution) | [`pqblocks-qubo-bench`](https://pqblocks.github.io/packages/qubo-bench/) | `pip install pqblocks-qubo-bench` | `pqblocks_qubo_bench` |