Metadata-Version: 2.4
Name: quantumguard
Version: 0.1.0
Summary: High-level post-quantum hybrid encryption (ML-KEM/Kyber768 + AES-256-GCM) with a Fernet-like API
Author: QuantumGuard Contributors
License: MIT
Project-URL: Homepage, https://github.com/quantumguard/quantumguard
Project-URL: Documentation, https://github.com/quantumguard/quantumguard#readme
Project-URL: Repository, https://github.com/quantumguard/quantumguard
Keywords: post-quantum,cryptography,ML-KEM,Kyber,NIST,PQC,hybrid encryption,AES-GCM
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pypqc>=0.0.6.1
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Dynamic: license-file

# 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

```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("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:

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

## 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)](https://csrc.nist.gov/pubs/fips/203/final)
- [NIST FIPS 204 (ML-DSA)](https://csrc.nist.gov/pubs/fips/204/final)

## License

MIT
