quantumguard 0.1.1
High-level post-quantum hybrid encryption (ML-KEM/Kyber768 + AES-256-GCM) with a Fernet-like API
License: MIT
Requires Python: >=3.9
Keywords: post-quantum, cryptography, ML-KEM, Kyber, NIST, PQC, hybrid encryption, AES-GCM

# QuantumGuard

[![CI](https://github.com/quantumguard/quantumguard/actions/workflows/ci.yml/badge.svg)](https://github.com/quantumguard/quantumguard/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/badge/coverage-95%25-green)](https://github.com/quantumguard/quantumguard/actions)

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

```bash
pip install quantumguard
```

## Quick Start

```python
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:

```python
# 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](CONTRIBUTING.md#building-the-api-docs)); 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)](https://csrc.nist.gov/pubs/fips/203/final) — Standard used by QuantumGuard for the KEM.
- [NIST FIPS 204 (ML-DSA)](https://csrc.nist.gov/pubs/fips/204/final) — For post-quantum signatures (not used by this library).

## License

MIT