qcrypto 1.0.0

Quantum-safe cryptography utilities built on top of liboqs-python

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

• Open Quantum Safe: https://openquantumsafe.org
• liboqs-python: https://github.com/open-quantum-safe/liboqs-python