qcrypto 1.0.0
Quantum-safe cryptography utilities built on top of liboqs-python
License: MIT
Requires Python: >=3.8

# qcrypto

**Version: 1.0.0**

`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
* A complete command-line interface (CLI)

`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`
* CLI support for signing and verifying files

### 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 with integrity checksum:

```
[1 byte]  version  
[1 byte]  algorithm id  
[2 bytes] Kyber ciphertext length  
[4 bytes] CRC32 header checksum (v2)
[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()
```

### ASCII-Armored Keys and Messages

Human-readable, copy/paste friendly format:

```
-----BEGIN QCRYPTO PUBLIC KEY-----
(base64 payload)
-----END QCRYPTO PUBLIC KEY-----
```

Supported for keys, encrypted private keys, signatures, and messages.

### Key Fingerprints

Stable key identity derived from `SHA256(pubkey)[:16]`:

```python
from qcrypto import key_fingerprint
fp = key_fingerprint(public_key)  # 32-char hex string
```

### Key Serialization

* `save_public_key()`, `save_private_key()`
* `KyberKEM.load_public_key()`, `KyberKEM.load_private_key()`
* Raw, base64, or ASCII-armored encoding
* Passphrase-protected private keys (PBKDF2 + AES-GCM)

### Default Key Paths

Like OpenSSH (`~/.ssh/`) or GPG (`~/.gnupg/`), qcrypto uses:

* `~/.qcrypto/kem/private.key` and `~/.qcrypto/kem/public.key` for encryption keys
* `~/.qcrypto/sig/private.key` and `~/.qcrypto/sig/public.key` for signature keys

The CLI automatically uses these paths when `--key`/`--pub` are not specified.

---

## Installation

Python 3.8+:

```
pip install qcrypto
```

`liboqs-python` installs automatically.

---

## CLI Usage

The `qcrypto` command-line tool provides a complete PQC toolkit:

### Key Generation

```bash
# Generate Kyber keypair (uses default paths ~/.qcrypto/kem/)
qcrypto gen-key

# Generate with custom paths
qcrypto gen-key --public pub.key --private priv.key

# Generate ASCII-armored keys
qcrypto gen-key --armored

# Generate with passphrase protection
qcrypto gen-key --pass
```

### Encryption / Decryption

```bash
# Encrypt a file (uses default public key)
qcrypto encrypt --in document.pdf --out document.pdf.enc

# Decrypt a file (uses default private key)
qcrypto decrypt --in document.pdf.enc --out document.pdf

# With passphrase-protected key
qcrypto decrypt --pass --in document.pdf.enc --out document.pdf
```

### Digital Signatures

```bash
# Generate signature keypair (Dilithium, Falcon, or SPHINCS+)
qcrypto sig-gen-key --alg Dilithium3
qcrypto sig-gen-key --alg Falcon-512 --armored

# Sign a file
qcrypto sign --in message.txt --out message.sig

# Verify a signature
qcrypto verify --in message.txt --sig message.sig
```

---

## Examples

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

* `kyber_example.py` — Kyber KEM key generation and encapsulation
* `hybrid_example.py` — High-level hybrid encryption API
* `files_example.py` — File encryption workflow
* `dilithium_example.py` — Dilithium signatures
* `falcon_example.py` — Falcon signatures
* `sphincs_example.py` — SPHINCS+ signatures
* `signature_scheme_generic_example.py` — Generic signature interface
* `mceliece_example.py` — Classic McEliece KEM
* `list_algorithms.py` — List all available liboqs algorithms
* `cli_example.txt` — CLI command reference

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

### v1.0.0 — Stable Release

This release marks qcrypto as production-ready for experimental and research use.

• All features from v0.5.0 are stable and tested.

• No breaking API changes from v0.5.0.

---

### v0.5.0 — Complete PQC Toolkit

**Key Discovery & Default Keypaths**

Keys are now automatically discovered at default locations:

- `~/.qcrypto/kem/private.key` and `~/.qcrypto/kem/public.key` for encryption
- `~/.qcrypto/sig/private.key` and `~/.qcrypto/sig/public.key` for signatures

This follows conventions from OpenSSH (`~/.ssh/`), age, and GPG.

**ASCII-Armored Key Format**

Human-readable, copy/paste friendly keys and messages:

```
-----BEGIN QCRYPTO PRIVATE KEY-----
(base64 payload)
-----END QCRYPTO PRIVATE KEY-----
```

```
-----BEGIN QCRYPTO MESSAGE-----
(base64 payload)
-----END QCRYPTO MESSAGE-----
```

Use `--armored` flag in CLI or `encoding="armor"` in Python.

**Digital Signatures via CLI**

New `qcrypto sign` and `qcrypto verify` commands:

```bash
qcrypto sign --key priv.key --in message.txt --out message.sig
qcrypto verify --pub pub.key --in message.txt --sig message.sig
```

Supports Dilithium, Falcon, and SPHINCS+ algorithms.

**Key Fingerprints**

Stable key identity derived from public key:

```python
from qcrypto import key_fingerprint
fp = key_fingerprint(public_key)  # SHA256(pubkey)[:16] as hex
```

Fingerprints are displayed in CLI output for verification.

**Header Checksums**

Ciphertext format v2 includes CRC32 checksum for nicer error messages:

- Detects corrupted headers
- Distinguishes wrong algorithm from file corruption
- Identifies truncated files early

**Other Improvements**

• Full CLI with `gen-key`, `encrypt`, `decrypt`, `sig-gen-key`, `sign`, `verify`

• Passphrase-protected private keys (PBKDF2-HMAC-SHA256 + AES-GCM)

• Interactive passphrase prompting

• `encrypt_message_armored()` and `decrypt_message_armored()` helpers

---

### 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)