Metadata-Version: 2.4
Name: pqc-hybrid
Version: 1.0.2
Summary: Production-ready Post-Quantum & Classical Hybrid cryptography library for Python
Author-email: pyuscraft <pyuscraft@users.noreply.github.com>
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/pqc-hybrid
Project-URL: Repository, https://github.com/pyuscraft/pqc-hybrid
Project-URL: Bug Tracker, https://github.com/pyuscraft/pqc-hybrid/issues
Keywords: post-quantum,pqc,ml-kem,ml-dsa,slh-dsa,crypto,hybrid,x25519,ed25519,kyber,dilithium,sphincs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Dynamic: license-file

# pqc-hybrid (Open PQC Hybrid)

`pqc-hybrid` is a developer-friendly, production-ready, Python-native library providing Post-Quantum Cryptography (PQC) integrated seamlessly with proven traditional classical algorithms into unified **Hybrid Cryptography** methods.

As NIST FIPS 203, 204, and 205 dictate, the future is Post-Quantum. However, to hedge against theoretical mathematical vulnerabilities in brand-new algorithms, a "Defense-in-Depth" Hybrid Cryptography approach ensures that communication and authenticated data remain secure as long as *at least one* algorithm (either classical or PQC) remains unbroken.

## Features & The "Best Combinations"

Based on extensive industry research focusing on computational latency, memory overhead, and network bandwidth (MTU compatibility), this package standardizes the "Best Combinations":

- **Hybrid Key Exchange (KEM): `X25519 + ML-KEM-768`**
  - **Why?** X25519 is computationally efficient and mathematically completely distinct from lattices. ML-KEM-768 executes in microseconds on modern processors natively, making the performance penalty trivial while providing Category 3 security constraints.
- **Hybrid General Signatures: `Ed25519 + ML-DSA-65`**
  - **Why?** Ed25519 offers ultra-compact signatures. ML-DSA provides rapid verification, acting as the ultimate digital signature replacement. *Warning: Signatures will exceed 3.3 KB, ensure your network MTU parameter configurations do not block large data packets.*
- **Hybrid Offline/Conservative Signatures: `Ed25519 + SLH-DSA-SHA2-128f`**
  - **Why?** SLH-DSA provides conservative, unassailable security based exclusively on hashes (dodging lattice-breaking algorithms entirely). Due to its computational latency (seconds to execute) and 17KB footprints, this method should exclusively be utilized for offline operations like long-lived root CA and document signing architectures.
- **Hybrid AEAD (Authenticated Encryption):** Complete end-to-end wrapper bridging `AES-256-GCM` encryption directly to the `Hybrid Post-Quantum Key Exchange` process securely.

## Installation

```bash
pip install pqc-hybrid
```

## Quick Start
```python
from pqc.kem import generate_hybrid_kem_keypair
from pqc.sig import generate_hybrid_sig_keypair, sign_hybrid, verify_hybrid
from pqc.aead import encrypt_hybrid, decrypt_hybrid

# 1. Authenticated Encryption via Hybrid KEM
def demo_aead():
    # Receiver generates Keys
    key_pair = generate_hybrid_kem_keypair()

    # Sender encapsulates AES key and encrypts
    payload = "Secure Payload via X25519 + ML-KEM-768"
    encrypted_bundle = encrypt_hybrid(payload, key_pair.public_key)

    # Receiver decapsulates symmetric bundle and decrypts
    decrypted_message = decrypt_hybrid(encrypted_bundle, key_pair.private_key)
    print(decrypted_message.decode('utf-8')) # "Secure Payload via X25519 + ML-KEM-768"

demo_aead()

# 2. Hybrid Signatures
def demo_sig():
    # Generate Ed25519 + ML-DSA-65 keys
    sign_keys = generate_hybrid_sig_keypair('ml-dsa-65')
    
    # Sign payload
    signature = sign_hybrid("Banking transaction details", sign_keys.private_key)

    # Verify
    is_valid = verify_hybrid("Banking transaction details", signature, sign_keys.public_key)
    print("Is Payload Genuine?", is_valid) # True

demo_sig()
```

## How to Publish to PyPI (`pip` Registry)

To publish this package to PyPI, follow these steps:

### 1. Prerequisites

1. Create an account on [PyPI](https://pypi.org/).
2. Obtain a PyPI API Token from your account settings (Account settings > API tokens).
3. Ensure you have the required build tools installed on your system:

```bash
pip install build twine
```

### 2. Build the Package

Navigate to the root of the project (where `pyproject.toml` is located) and run:

```bash
python -m build
```

This will create a `dist/` directory containing two files:
- A `.tar.gz` Source Distribution (sdist).
- A `.whl` Wheel file (compiled package).

### 3. Check the Build

Before uploading, verify that the built distributions are valid:

```bash
twine check dist/*
```

### 4. Upload to PyPI (Production)

Upload the package using `twine`:

```bash
twine upload dist/*
```

When prompted, use `__token__` as the username and your PyPI API token as the password. Alternatively, you can configure your `~/.pypirc` file or use environment variables (`TWINE_USERNAME` and `TWINE_PASSWORD`).

### 5. Verify the Upload

Once successful, your package will be immediately available. You can test it by running:

```bash
pip install pqc-hybrid
```

---

*Note: If you want to test publishing without affecting the real PyPI index, test it first against TestPyPI:*

```bash
twine upload --repository testpypi dist/*
# Then install via TestPyPI
pip install --index-url https://test.pypi.org/simple/ --no-deps pqc-hybrid
```

## Development & Maintenance

### Run Tests
```bash
pip install pytest
pytest
```
