Metadata-Version: 2.4
Name: qcrypto
Version: 0.4.2
Summary: Quantum-safe cryptography utilities built on top of liboqs-python
Author-email: Victor Postea <victorpostea@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/victorpostea/qcrypto
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: liboqs-python>=0.14.0
Requires-Dist: cryptography>=41.0.0
Dynamic: license-file

# qcrypto

**Version: 0.4.2**

`qcrypto` is a lightweight Python library that provides simple, Pythonic wrappers around post-quantum cryptography (PQC) using the official `liboqs-python` bindings from the Open Quantum Safe project.

The library exposes unified, minimal interfaces for:

* Post-quantum key encapsulation (KEM)
* Post-quantum digital signatures
* A hybrid PQC + AES-GCM authenticated encryption scheme

`qcrypto` is suitable for learning PQC concepts, prototyping, research, and experimentation with quantum-safe primitives.

---

## Features

### Post-Quantum Key Encapsulation (KEM)

* **Kyber** (Kyber512 / Kyber768 / Kyber1024)
* **Classic McEliece** (all parameter sets exposed by liboqs)
* Public/secret key generation
* Encapsulation → shared secret + ciphertext
* Decapsulation → recover the same shared secret

### Digital Signatures

* **Dilithium** (2, 3, 5)
* **Falcon** (Falcon-512, Falcon-1024)
* **SPHINCS+** (SHA2 and SHAKE variants)
* Unified signature interface:

  * `SignatureScheme` for any liboqs signature algorithm
  * Convenience wrappers: `DilithiumSig`, `FalconSig`, `SphincsSig`

### Hybrid PQC + AES-256-GCM Encryption

* Kyber encapsulates a shared secret
* HKDF-SHA256 derives an AES key
* AES-256-GCM encrypts the message
* Compact single-blob ciphertext format:

```
[1 byte]  version  
[1 byte]  algorithm id  
[2 bytes] Kyber ciphertext length  
[N bytes] Kyber ciphertext  
[12 bytes] AES-GCM nonce  
[M bytes] AES-GCM ciphertext+tag
```

High-level API:

```python
from qcrypto import encrypt, decrypt
```

Legacy API retained:

```python
encrypt_for_recipient()
decrypt_from_sender()
```

### Key Serialization

* `save_public_key()`, `save_private_key()`
* `KyberKEM.load_public_key()`, `KyberKEM.load_private_key()`
* Raw or base64 encoding

---

## Installation

Python 3.8+:

```
pip install qcrypto
```

`liboqs-python` installs automatically.

---

## Examples

All examples are located in the `examples/` directory:

* `kyber_example.py`
* `files_example.py`
* `mceliece_example.py`
* `dilithium_example.py`
* `falcon_example.py`
* `sphincs_example.py`
* `signature_scheme_generic_example.py`
* `hybrid_example.py`
* `list_algorithms.py`

Run an example:

```
python examples/kyber_example.py
```

---

## Implementation Notes

* Uses `liboqs-python`, which bundles optimized C implementations of PQC algorithms.
* AES-256-GCM provided by the `cryptography` package.
* Available algorithms depend on how liboqs was compiled on your platform.
* Hybrid encryption uses HKDF-SHA256 and fresh 96-bit GCM nonces.
* Pure Python library using modern `src/` layout.

---

## Changelog

### v0.4.0 — File Encryption & Streaming AES-GCM

New Features
------------

• Added `encrypt_file()` and `decrypt_file()` for real file encryption workflows.
• Introduced streaming AES-256-GCM, allowing encryption/decryption of large files
  without loading the entire file into memory.
• File ciphertext format matches the existing `encrypt()` API for full compatibility.

Ciphertext Format
-----------------

```
[1 byte]    version
[1 byte]    algorithm id
[2 bytes]   Kyber ciphertext length
[N bytes]   Kyber ciphertext
[12 bytes]  AES-GCM nonce
[M bytes]   AES-GCM ciphertext + 16-byte GCM tag
```

Other Improvements
------------------

• Added round-trip file encryption tests.
• Updated `__init__.py` to expose file encryption helpers.
• Internal refactoring to support chunked I/O while preserving the
  standardized hybrid ciphertext structure.

---

### v0.3.0 — Expanded PQC Support

**New Algorithms**

* Falcon signatures (`FalconSig`)
* SPHINCS+ signatures (`SphincsSig`)
* Classic McEliece KEM (`ClassicMcElieceKEM`)

**Unified Signature Interface**

* Added `SignatureScheme` supporting any liboqs signature algorithm.

**Examples**

* Added Falcon, SPHINCS+, McEliece, and generic signature examples.

**Internal Improvements**

* Restructured signatures/KEMs for easier future expansion.

---

### v0.2.0 — Hybrid API Rewrite, Ciphertext Format, Key Serialization

* Added new high-level hybrid `encrypt()` and `decrypt()`
* Introduced standardized single-blob ciphertext format
* Added key serialization helpers
* Improved decapsulation API
* Legacy API preserved for compatibility

---

## Disclaimer

This library is for educational, experimental, and research use.
It has not undergone formal security review and should not be used in production systems.

---

## License

MIT License.

---

## Resources

* Open Quantum Safe: [https://openquantumsafe.org](https://openquantumsafe.org)
* liboqs-python: [https://github.com/open-quantum-safe/liboqs-python](https://github.com/open-quantum-safe/liboqs-python)
