Skip to main content

qcrypto

Version: 1.0.0

qcrypto is a lightweight Python library that provides simple, Pythonic wrappers around post-quantum cryptography (PQC) using the official liboqs-python bindings from the Open Quantum Safe project.

The library exposes unified, minimal interfaces for:

  • Post-quantum key encapsulation (KEM)
  • Post-quantum digital signatures
  • A hybrid PQC + AES-GCM authenticated encryption scheme
  • A complete command-line interface (CLI)

qcrypto is suitable for learning PQC concepts, prototyping, research, and experimentation with quantum-safe primitives.


Features

Post-Quantum Key Encapsulation (KEM)

  • Kyber (Kyber512 / Kyber768 / Kyber1024)
  • Classic McEliece (all parameter sets exposed by liboqs)
  • Public/secret key generation
  • Encapsulation → shared secret + ciphertext
  • Decapsulation → recover the same shared secret

Digital Signatures

  • Dilithium (2, 3, 5)

  • Falcon (Falcon-512, Falcon-1024)

  • SPHINCS+ (SHA2 and SHAKE variants)

  • Unified signature interface:

    • SignatureScheme for any liboqs signature algorithm
    • Convenience wrappers: DilithiumSig, FalconSig, SphincsSig
  • CLI support for signing and verifying files

Hybrid PQC + AES-256-GCM Encryption

  • Kyber encapsulates a shared secret
  • HKDF-SHA256 derives an AES key
  • AES-256-GCM encrypts the message
  • Compact single-blob ciphertext format with integrity checksum:
[1 byte]  version  
[1 byte]  algorithm id  
[2 bytes] Kyber ciphertext length  
[4 bytes] CRC32 header checksum (v2)
[N bytes] Kyber ciphertext  
[12 bytes] AES-GCM nonce  
[M bytes] AES-GCM ciphertext+tag

High-level API:

from qcrypto import encrypt, decrypt

Legacy API retained:

encrypt_for_recipient()
decrypt_from_sender()

ASCII-Armored Keys and Messages

Human-readable, copy/paste friendly format:

-----BEGIN QCRYPTO PUBLIC KEY-----
(base64 payload)
-----END QCRYPTO PUBLIC KEY-----

Supported for keys, encrypted private keys, signatures, and messages.

Key Fingerprints

Stable key identity derived from SHA256(pubkey)[:16]:

from qcrypto import key_fingerprint
fp = key_fingerprint(public_key)  # 32-char hex string

Key Serialization

  • save_public_key(), save_private_key()
  • KyberKEM.load_public_key(), KyberKEM.load_private_key()
  • Raw, base64, or ASCII-armored encoding
  • Passphrase-protected private keys (PBKDF2 + AES-GCM)

Default Key Paths

Like OpenSSH (~/.ssh/) or GPG (~/.gnupg/), qcrypto uses:

  • ~/.qcrypto/kem/private.key and ~/.qcrypto/kem/public.key for encryption keys
  • ~/.qcrypto/sig/private.key and ~/.qcrypto/sig/public.key for signature keys

The CLI automatically uses these paths when --key/--pub are not specified.


Installation

Python 3.8+:

pip install qcrypto

liboqs-python installs automatically.


CLI Usage

The qcrypto command-line tool provides a complete PQC toolkit:

Key Generation

# Generate Kyber keypair (uses default paths ~/.qcrypto/kem/)
qcrypto gen-key

# Generate with custom paths
qcrypto gen-key --public pub.key --private priv.key

# Generate ASCII-armored keys
qcrypto gen-key --armored

# Generate with passphrase protection
qcrypto gen-key --pass

Encryption / Decryption

# Encrypt a file (uses default public key)
qcrypto encrypt --in document.pdf --out document.pdf.enc

# Decrypt a file (uses default private key)
qcrypto decrypt --in document.pdf.enc --out document.pdf

# With passphrase-protected key
qcrypto decrypt --pass --in document.pdf.enc --out document.pdf

Digital Signatures

# Generate signature keypair (Dilithium, Falcon, or SPHINCS+)
qcrypto sig-gen-key --alg Dilithium3
qcrypto sig-gen-key --alg Falcon-512 --armored

# Sign a file
qcrypto sign --in message.txt --out message.sig

# Verify a signature
qcrypto verify --in message.txt --sig message.sig

Examples

All examples are located in the examples/ directory:

  • kyber_example.py — Kyber KEM key generation and encapsulation
  • hybrid_example.py — High-level hybrid encryption API
  • files_example.py — File encryption workflow
  • dilithium_example.py — Dilithium signatures
  • falcon_example.py — Falcon signatures
  • sphincs_example.py — SPHINCS+ signatures
  • signature_scheme_generic_example.py — Generic signature interface
  • mceliece_example.py — Classic McEliece KEM
  • list_algorithms.py — List all available liboqs algorithms
  • cli_example.txt — CLI command reference

Run an example:

python examples/kyber_example.py

Implementation Notes

  • Uses liboqs-python, which bundles optimized C implementations of PQC algorithms.
  • AES-256-GCM provided by the cryptography package.
  • Available algorithms depend on how liboqs was compiled on your platform.
  • Hybrid encryption uses HKDF-SHA256 and fresh 96-bit GCM nonces.
  • Pure Python library using modern src/ layout.

Changelog

v1.0.0 — Stable Release

This release marks qcrypto as production-ready for experimental and research use.

• All features from v0.5.0 are stable and tested.

• No breaking API changes from v0.5.0.


v0.5.0 — Complete PQC Toolkit

Key Discovery & Default Keypaths

Keys are now automatically discovered at default locations:

  • ~/.qcrypto/kem/private.key and ~/.qcrypto/kem/public.key for encryption
  • ~/.qcrypto/sig/private.key and ~/.qcrypto/sig/public.key for signatures

This follows conventions from OpenSSH (~/.ssh/), age, and GPG.

ASCII-Armored Key Format

Human-readable, copy/paste friendly keys and messages:

-----BEGIN QCRYPTO PRIVATE KEY-----
(base64 payload)
-----END QCRYPTO PRIVATE KEY-----
-----BEGIN QCRYPTO MESSAGE-----
(base64 payload)
-----END QCRYPTO MESSAGE-----

Use --armored flag in CLI or encoding="armor" in Python.

Digital Signatures via CLI

New qcrypto sign and qcrypto verify commands:

qcrypto sign --key priv.key --in message.txt --out message.sig
qcrypto verify --pub pub.key --in message.txt --sig message.sig

Supports Dilithium, Falcon, and SPHINCS+ algorithms.

Key Fingerprints

Stable key identity derived from public key:

from qcrypto import key_fingerprint
fp = key_fingerprint(public_key)  # SHA256(pubkey)[:16] as hex

Fingerprints are displayed in CLI output for verification.

Header Checksums

Ciphertext format v2 includes CRC32 checksum for nicer error messages:

  • Detects corrupted headers
  • Distinguishes wrong algorithm from file corruption
  • Identifies truncated files early

Other Improvements

• Full CLI with gen-key, encrypt, decrypt, sig-gen-key, sign, verify

• Passphrase-protected private keys (PBKDF2-HMAC-SHA256 + AES-GCM)

• Interactive passphrase prompting

• encrypt_message_armored() and decrypt_message_armored() helpers


v0.4.0 — File Encryption & Streaming AES-GCM

New Features

• Added encrypt_file() and decrypt_file() for real file encryption workflows. • Introduced streaming AES-256-GCM, allowing encryption/decryption of large files without loading the entire file into memory. • File ciphertext format matches the existing encrypt() API for full compatibility.

Ciphertext Format

[1 byte]    version
[1 byte]    algorithm id
[2 bytes]   Kyber ciphertext length
[N bytes]   Kyber ciphertext
[12 bytes]  AES-GCM nonce
[M bytes]   AES-GCM ciphertext + 16-byte GCM tag

Other Improvements

• Added round-trip file encryption tests. • Updated __init__.py to expose file encryption helpers. • Internal refactoring to support chunked I/O while preserving the standardized hybrid ciphertext structure.


v0.3.0 — Expanded PQC Support

New Algorithms

  • Falcon signatures (FalconSig)
  • SPHINCS+ signatures (SphincsSig)
  • Classic McEliece KEM (ClassicMcElieceKEM)

Unified Signature Interface

  • Added SignatureScheme supporting any liboqs signature algorithm.

Examples

  • Added Falcon, SPHINCS+, McEliece, and generic signature examples.

Internal Improvements

  • Restructured signatures/KEMs for easier future expansion.

v0.2.0 — Hybrid API Rewrite, Ciphertext Format, Key Serialization

  • Added new high-level hybrid encrypt() and decrypt()
  • Introduced standardized single-blob ciphertext format
  • Added key serialization helpers
  • Improved decapsulation API
  • Legacy API preserved for compatibility

Disclaimer

This library is for educational, experimental, and research use. It has not undergone formal security review and should not be used in production systems.


License

MIT License.


Resources

Metadata

Release files for qcrypto 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qcrypto 1.0.0
File Size Uploaded Provenance Actions
qcrypto-1.0.0.tar.gz 21.3 kB Without provenance Details for qcrypto-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qcrypto 1.0.0
File Interpreter ABI Platform Actions
qcrypto-1.0.0-py3-none-any.whl Python 3 none any Details for qcrypto-1.0.0-py3-none-any.whl

Total release size: 39.8 kB

Release files / qcrypto-1.0.0.tar.gz

Download URL qcrypto-1.0.0.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
48ba47f12d98ecf77488ad28500a661cbecee6dd87af6c0db429f702db2fbdb1
BLAKE2b-256 checksum
How to use checksums
5ec45cf62b490fcfeb6a8d724bfa4dde089a04a0d87cef49e3ecc3ea26bd4c8b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / qcrypto-1.0.0-py3-none-any.whl

Download URL qcrypto-1.0.0-py3-none-any.whl
Size 18.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b5d13ea5d55ef2b3b580e1418aa9684192fcf95f9a95286a748693dad7f7258b
BLAKE2b-256 checksum
How to use checksums
7c2b96768aed2995b6bad2b836d07b8358136fc1fc9597798668d2b528415beb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for qcrypto 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page