quantumguard 0.1.0

High-level post-quantum hybrid encryption (ML-KEM/Kyber768 + AES-256-GCM) with a Fernet-like API

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

• 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("Mensaje secreto post-cuántico")

# 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.

Security Notes

• Memory: Sensitive key material is held in a bytearray and can be wiped with qg.cleanup(). Python does not guarantee that copies do not exist (e.g. interpreter or C extensions). Use secure_wipe for custom buffers when needed.
• 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. No AAD is used in the default API.

References

• NIST FIPS 203 (ML-KEM)
• NIST FIPS 204 (ML-DSA)

License

MIT