# Post-Quantum Hybrid Kyber-1024 + AES-256-CTR File Encryption

Streaming hybrid file encryption combining ML-KEM-1024 (Kyber-1024) for post-quantum key encapsulation with AES-256-CTR for bulk encryption and HMAC-SHA256 for integrity verification.

Handles files larger than available RAM via chunked streaming (64 MB chunks).

<a href="https://notes.juyung.com/gallery/6nIr0qID0vri0DR4Jy7HCbS6/hJv-1N1hIqFxzXIv85KqR9dq"  target="_blank"/><img src='https://notes.juyung.com/uploads/small2x/f9/20/0805d761b05dbbf2046a68268b58.png' style="height: 720px;" /></a>

## Features

- Post-quantum secure key exchange via liboqs Kyber-1024 KEM (~256-bit PQ security)
- AES-256-CTR symmetric encryption with a streaming architecture that handles files larger than RAM (64 MB chunks)
- HMAC-SHA256 authenticity tag to detect tampering or corruption

## Requirements

- `oqs` ([liboqs-python](https://github.com/open-quantum-safe/liboqs-python))
- `cryptography` ([pyca/cryptography](https://github.com/pyca/cryptography))

```bash
python3 -m venv venv && . venv/bin/activate
pip install -r requirements.txt
```

## Usage

1. Generate a Kyber-1024 key pair

```bash
python3 gen_kyber.py
```

Produces:

- `kyber.pub` - public key (1568 bytes)
- `kyber.sec` - secret key (3168 bytes)

2. Encrypt a file

```bash
python3 encrypt.py archive.7z
```

Output: `archive.7z.enc`

The `.enc` file contains:

Section | Description
-|-
Kyber ciphertext|Encapsulated key (ciphertext from KEM)
IV|16-byte AES-CTR nonce
HMAC key|32-byte HMAC key
File ciphertext|AES-256-CTR encrypted chunks
HMAC tag|32-byte SHA-256 MAC of the file ciphertext

3. Decrypt a file

```bash
python3 decrypt.py archive.7z.enc
```

Output: `archive.7z`

The script automatically verifies the HMAC tag. If the file has been tampered with, you'll see:

```
Error: Integrity check failed. File corrupted or tampered
```

and the partial output gets deleted.

## File formats

**Key files (raw binary)**

File|Content|Size (bytes)
-|-|-
`kyber.pub`|Kyber-1024 public key|1568
`kyber.sec`|Kyber-1024 secret key|3168


**Encrypted file structure**

`archive.7z.enc`:
```
┌─────────────────────────┐
│ Kyber CT length (4 B)   │  ← big-endian uint32
├─────────────────────────┤
│ Kyber ciphertext        │  ← 1568 bytes(Kyber-1024)
├─────────────────────────┤
│ IV (16 B)               │  ← AES-CTR nonce
├─────────────────────────┤
│ HMAC key (32 B)         │  ← random per file
├─────────────────────────┤
│ AES-256-CTR ciphertext  │  ← streamed in 64 MB chunks
├─────────────────────────┤
│ HMAC-SHA256 tag (32 B)  │  ← over the AES ciphertext only
└─────────────────────────┘
```

## Security notes

- A new random AES key is generated **per file** via Kyber encapsulation.
- A new random HMAC key is generated **per file**.
- The HMAC tag is computed over the **AES ciphertext** (the encrypted file data), so any tampering is detected before decryption.
- Kyber-1024 is believed to offer security equivalent to ~256-bit classical keys against quantum attackers.
- The secret key file (`kyber.sec`) should be treated like a private SSH key. Store it offline or in a secure vault.