pqc-hybrid 1.0.2

Production-ready Post-Quantum & Classical Hybrid cryptography library for Python

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

pip install pqc-hybrid

Quick Start

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

pip install build twine

2. Build the Package

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

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:

twine check dist/*

4. Upload to PyPI (Production)

Upload the package using twine:

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:

pip install pqc-hybrid

---

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

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

pip install pytest
pytest