quantum-safe-py

Post-quantum cryptography for Python: hybrid key exchange, hybrid signatures, encrypted envelopes, a migration toolkit and a CI-ready audit scanner in one library.

What you get

• Hybrid by default: X25519+ML-KEM-768 key exchange and Ed25519+ML-DSA-65 signatures, with pure ML-KEM, ML-DSA, SLH-DSA (all 12 sets) and X-Wing available.
• Envelopes: KEM + AES-256-GCM in one self-describing, CBOR-encoded message, plus a streaming format for large files.
• Standards formats: RFC 9964 JOSE/JWT and COSE_Sign1 for ML-DSA, FIPS 204 native-context signatures.
• Migration: scan code for classical crypto, upgrade existing keys to hybrid, track progress per key.
• Audit: SARIF and JSON reports, a CycloneDX Cryptographic Bill of Materials, CNSA 2.0 parameter reporting and enforcement.
• Same bytes as TypeScript: keys, ciphertexts and signatures are byte-compatible with quantum-safe-ts.
• Tested against NIST vectors: 638 of 638 runnable ACVP known-answer cases pass.

Install

pip install quantum-safe-py                  # classical primitives, formats, scanner, audit
pip install 'quantum-safe-py[liboqs]'        # ML-KEM, ML-DSA, SLH-DSA through liboqs
pip install 'quantum-safe-py[pyca]'          # ML-KEM and ML-DSA through cryptography>=48 (no compiler)

Python 3.10 or later. Prebuilt wheels carry liboqs; the other extras (lms, rustcrypto) are in Installation.

Quick start

from quantum_safe import HybridKEM, HybridSign
from quantum_safe.protocols import Envelope

# Key exchange: hybrid X25519 + ML-KEM-768
kem = HybridKEM()
kp = kem.generate_keypair()
ct, shared_secret = kem.encapsulate(kp.public)
assert shared_secret == kem.decapsulate(kp.secret, ct)

# Encrypt to a public key: KEM + AES-256-GCM, and state the AAD you expect on open
sealed = Envelope.seal(b"plaintext", kp.public, aad=b"record-42")
plain = Envelope.open(sealed, kp.secret, expected_aad=b"record-42")

# Sign: hybrid Ed25519 + ML-DSA-65, and state the context you expect on verify
signer = HybridSign()
sk = signer.generate_keypair()
sm = signer.sign(b"important document", sk.secret, context=b"myapp-v1")
signer.verify(sm, sk.public, context=b"myapp-v1")  # raises VerificationError if invalid

Scan, then migrate

qs-audit scan ./src                                      # find classical crypto, with fix hints
qs-audit scan ./src --format sarif --output audit.sarif  # GitHub Code Scanning
qs-audit cbom ./src --output cbom.json                   # CycloneDX Cryptographic Bill of Materials
qs-audit cnsa2                                           # CNSA 2.0 parameter-set report
qs-migrate status                                        # migration progress per key

Documentation

Everything else is on the documentation site: quantum-safe-py.readthedocs.io.

Cite this work

@article{shaw2026quantumsafe,
  title     = {quantum-safe: Bridging the Post-Quantum Production Gap with a
               Hybrid-by-Default Python Cryptography Library},
  author    = {Shaw, Animesh},
  journal   = {arXiv preprint arXiv:2605.17061},
  year      = {2026},
  note      = {v2},
  url       = {https://arxiv.org/abs/2605.17061}
}

To cite the software itself, use the Zenodo concept DOI 10.5281/zenodo.23008259, which resolves to the latest release. A machine-readable CITATION.cff is included for GitHub's "Cite this repository" button.

Contributing and license

See CONTRIBUTING.md. Apache 2.0, see LICENSE.

Built on Open Quantum Safe / liboqs, PyCA cryptography and the NIST PQC standards (FIPS 203, 204, 205).