QuantumGuard

High-level post-quantum hybrid encryption library for Python. Uses ML-KEM (Kyber768, NIST FIPS 203) for key encapsulation and AES-256-GCM for symmetric encryption, with a simple API similar to cryptography.fernet.

Requirements

• Compatibility: Python 3.9+
• pypqc (PQClean bindings, Kyber768)
• cryptography (AES-GCM)

Installation

pip install quantumguard

Quick Start

from quantumguard import QuantumGuard

# Generate key pair
public_key, private_key = QuantumGuard.generate_keypair()

# Encrypt with public key
qg = QuantumGuard(public_key)
ciphertext = qg.encrypt("Post-quantum secret message")

# Decrypt with private key
qg_private = QuantumGuard(private_key)
decrypted_text = qg_private.decrypt(ciphertext)  # bytes
print(decrypted_text.decode("utf-8"))

Key Persistence (PEM / Base64)

Keys can be exported and imported in PEM or Base64 for storage in .key files:

# Export to PEM
pem_private = QuantumGuard.key_to_pem(private_key, "private")
pem_public = QuantumGuard.key_to_pem(public_key, "public")

# Save to file
with open("private.key", "w") as f:
    f.write(pem_private)

# Load from PEM
with open("private.key") as f:
    key_bytes, kind = QuantumGuard.key_from_pem(f.read())
qg = QuantumGuard(key_bytes)  # or pass the PEM string directly: QuantumGuard(f.read())

Base64 with optional type prefix (qg.pub. / qg.priv.) is also supported via key_to_base64 and key_from_base64.

Serialization Format

• Binary (default): Magic + version, KEM ciphertext length, KEM ciphertext, 12-byte nonce, 16-byte tag, AES ciphertext. Compact and deterministic.
• JSON: Optional output_format="json" in encrypt() for debugging or interoperability. Payload is UTF-8 JSON with base64-encoded fields (v, k, n, t, c).

Decryption accepts both formats automatically.

API Summary

• QuantumGuard(key) — Initialize with public or private key (bytes, PEM, or Base64).
• generate_keypair() — Returns (public_key, private_key) as bytes.
• encrypt(plaintext, output_format="binary"|"json") — Encrypt; returns serialized bytes.
• decrypt(ciphertext) — Decrypt; returns plaintext bytes.
• cleanup() — Wipe key material; do not use the instance afterward.
• key_to_pem(key, kind), key_from_pem(pem) — PEM export/import.
• key_to_base64(key, kind), key_from_base64(b64) — Base64 export/import.
• secure_wipe(buffer) — Zero a bytearray (best-effort).
• SecureBytes(length) — Context manager or .burn() for short-lived secrets.
• __version__ (package version string), NONCE_BYTES, TAG_BYTES, MAX_KEM_CT_BYTES (max KEM ciphertext length), VERSION (serialization format version, integer), RECOMMENDED_MAX_PLAINTEXT_BYTES (recommended max plaintext size for apps to enforce; library does not enforce it) — constants for integrations.

See docstrings for full details. For a generated API Reference, build the Sphinx docs (see Contributing); output is in docs/build/html/.

Security Notes

• Message size: The library does not impose a maximum plaintext length. Applications should enforce a maximum plaintext size per message (e.g. 1 MiB; see RECOMMENDED_MAX_PLAINTEXT_BYTES) to mitigate DoS from excessively large payloads. Practical limits are also system memory and the AES-GCM specification; use streaming or chunking for very large data if needed.
• AAD (Additional Authenticated Data): AAD is not used in this API. For binding ciphertext to context (e.g. session id, nonce), applications must enforce that at a higher layer.
• Memory: Sensitive key material is held in a bytearray and can be wiped with qg.cleanup(). Do not use the instance for encrypt() or decrypt() after calling cleanup(); those methods will raise InvalidKeyError. Python does not guarantee that copies do not exist (e.g. interpreter or C extensions). For custom buffers use secure_wipe(); for short-lived secrets consider SecureBytes (context manager or .burn()).
• Dependencies: Requires pypqc >= 0.0.6.1 (KyberSlash fix). Do not use older versions.
• Algorithms: ML-KEM-768 (FIPS 203) for KEM; AES-256-GCM for encryption.

References

• NIST FIPS 203 (ML-KEM) — Standard used by QuantumGuard for the KEM.
• NIST FIPS 204 (ML-DSA) — For post-quantum signatures (not used by this library).

License

MIT