Quantum-Resistant Encryption Toolkit

Educational local-first toolkit for exploring post-quantum cryptography concepts in Python.

This repository is currently at MVP-10: Documentation and Migration Guide. It includes:

• liboqs algorithm discovery.
• ML-KEM wrappers for key encapsulation.
• ML-DSA wrappers for signatures.
• Classical comparison helpers for X25519, Ed25519, RSA, AES-GCM, and HKDF.
• Hybrid ML-KEM + X25519 key agreement.
• AES-256-GCM encrypted file containers with authenticated metadata.
• Detached and embedded ML-DSA signatures.
• A Typer CLI for key generation, encryption, decryption, signing, verification, and benchmarks.
• Benchmark JSON and Markdown reports.
• Security model, threat model, limitations, glossary, migration guide, and example walkthrough.

Contents

• Educational-Only Status
• Documentation Map
• Key Concepts
• Requirements
• Install For Development
• CLI Commands
• Quick Start
• Benchmarks
• File And Key Handling
• Repository Layout
• Development Checks

Educational-Only Status

This project is for education, experimentation, and research only.

It is not audited. It is not FIPS-validated. It is not production-ready. Do not use it to protect real sensitive data. No cryptographic implementation should be trusted without expert review. Post-quantum does not mean unbreakable. Benchmark results do not prove security.

Documentation Map

• Disclaimer: short safety statement.
• Implementation Plan: original milestone plan used to build the project.
• Security Model: scope, algorithm roles, metadata, and validation boundaries.
• Threat Model: assets, attacker assumptions, trust assumptions, and residual risk.
• Limitations: what the project intentionally does not do.
• Migration Guide: high-level organizational migration concepts.
• Glossary: definitions for common project terms.
• Example Walkthrough: runnable local CLI example.
• Benchmarks: benchmark layout and report guidance.

Key Concepts

ML-KEM and AES do different jobs. ML-KEM establishes shared key material for a recipient. AES-256-GCM encrypts and authenticates file bytes.

ML-DSA and encryption do different jobs. ML-DSA signs data so a verifier can check authenticity and integrity. It does not hide the data.

Classical and post-quantum algorithms have different security goals. RSA, X25519, and Ed25519 are included for comparison and hybrid demonstrations, but classical public-key algorithms are not considered quantum-resistant against a sufficiently capable quantum computer.

Hybrid migration and production assurance are different. Combining ML-KEM with X25519 is useful for studying transition-period designs. It does not make this project audited, certified, or production-ready.

Requirements

• Python 3.11 or newer.
• cryptography, typer, and rich.
• Loadable native liboqs build for real ML-KEM and ML-DSA operations.

On Windows, liboqs typically needs Visual Studio Build Tools and an accessible native oqs.dll, usually through OQS_INSTALL_PATH or PATH.

Install For Development

python -m pip install -e ".[dev,pqc]"

If you only want to run tests that use fake post-quantum backends, the pqc extra is not required. Real CLI cryptographic operations need liboqs.

CLI Commands

After installation:

pqc-tool --help

From the repository root during development:

python -m pqc_toolkit.cli --help

Commands:

pqc-tool algorithms
pqc-tool keys generate-recipient
pqc-tool keys generate-signer
pqc-tool encrypt
pqc-tool decrypt
pqc-tool sign
pqc-tool verify
pqc-tool benchmark

Normal CLI output reports paths and algorithm names. It does not print private keys, shared secrets, derived keys, plaintext contents, or decrypted data.

Quick Start

Run these commands from the repository root. Use only non-sensitive files.

python -m pqc_toolkit.cli keys generate-recipient \
  --public-key examples/sample_files/recipient.pub.json \
  --private-key examples/sample_files/recipient.sec.json

python -m pqc_toolkit.cli keys generate-signer \
  --public-key examples/sample_files/signer.pub.json \
  --private-key examples/sample_files/signer.sec.json

python -m pqc_toolkit.cli encrypt examples/sample_files/message.txt \
  --recipient-public-key examples/sample_files/recipient.pub.json \
  --signing-private-key examples/sample_files/signer.sec.json \
  --output examples/sample_files/message.pqce

python -m pqc_toolkit.cli verify examples/sample_files/message.pqce \
  --signer-public-key examples/sample_files/signer.pub.json

python -m pqc_toolkit.cli decrypt examples/sample_files/message.pqce \
  --recipient-private-key examples/sample_files/recipient.sec.json \
  --signer-public-key examples/sample_files/signer.pub.json \
  --output examples/sample_files/message.restored.txt

For the full walkthrough, see examples/README.md.

Benchmarks

pqc-tool benchmark --iterations 5 --output-dir benchmarks/results

The benchmark command writes:

benchmarks/results/latest.json
benchmarks/results/latest.md

Reports include timing and size comparisons for ML-KEM, ML-DSA, X25519, Ed25519, RSA-PSS, hybrid key derivation, and encrypted file metadata overhead. They also include limitations and environment details.

Faster does not mean more secure. Smaller does not mean more secure. Results vary by CPU, OS, library version, backend build, and parameter set.

File And Key Handling

Encrypted .pqce containers include canonical JSON metadata and binary AES-GCM ciphertext. AES-GCM authenticates the metadata as associated data, so metadata tampering fails decryption.

CLI key files are simple versioned JSON records. Public and private key files are separate, but private key files are not encrypted at rest. The project applies best-effort restrictive file permissions where the platform supports them.

Output files are not overwritten unless the relevant command receives --overwrite.

Repository Layout

src/pqc_toolkit/
  benchmarks/    Benchmark runner and report rendering.
  classical/     X25519, Ed25519, RSA, AES-GCM helpers.
  filecrypto/    Encrypted container, file encryption, signing, verification.
  hybrid/        Hybrid ML-KEM + X25519 key agreement.
  keys/          Versioned CLI key-file serialization.
  pqc/           liboqs-backed ML-KEM and ML-DSA wrappers.
  utils/         Small shared utilities.

tests/
  unit/          Unit tests for wrappers, containers, CLI, benchmarks, docs.

examples/
  sample_files/  Harmless plaintext sample for the CLI walkthrough.

benchmarks/
  README.md      Benchmark folder guide.
  results/       Local reports and safe pytest report snapshots.
  tests/         Notes on benchmark-related pytest artifacts.

Development Checks

pytest
ruff check .
mypy src tests