107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
# 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.
|