93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# Post-Quantum Hybrid ML-KEM-1024 + AES-256-GCM File Encryption
|
|
|
|
kyb encrypts files using post-quantum cryptography (ML-KEM-1024) and AES-256-GCM authenticated encryption. The file signature is `KYB`, and the file extension is `.kyb`.
|
|
|
|
```
|
|
ENCRYPTION DECRYPTION
|
|
═════════════════════════════════════════════════════════════════
|
|
|
|
Input File Input File (.kyb)
|
|
│ │
|
|
▼ ▼
|
|
Generate IV (12B) Read Header + ML-KEM CT + IV
|
|
│ │
|
|
▼ ▼
|
|
ML-KEM Encapsulation ML-KEM Decapsulation
|
|
(Public Key .pub) (Private Key .sec)
|
|
│ │
|
|
└─→ Shared Secret (32B) └─→ Shared Secret (32B)
|
|
│ │
|
|
├─→ HKDF-SHA256 ├─→ HKDF-SHA256
|
|
│ └─ Salt: IV │ └─ Salt: IV
|
|
│ │
|
|
▼ ▼
|
|
AES-256 Key (32B) AES-256 Key (32B)
|
|
│ │
|
|
▼ ▼
|
|
Encrypt File Decrypt File
|
|
│ │
|
|
▼ ▼
|
|
Write Auth Tag Verify Auth Tag
|
|
│ │
|
|
▼ ▼
|
|
Output File (.kyb) Output File
|
|
|
|
```
|
|
|
|
## Features
|
|
|
|
- Compromising one file doesn't expose others. A fresh 32-byte shared secret is generated for each file and transformed into the AES-256 key via HKDF-SHA256.
|
|
- An attacker cannot modify files undetectably. Any tampering with the ciphertext, header, or nonce causes authentication to fail before plaintext is written to disk.
|
|
- Every encrypted file includes a header with detailed metadata, so you can rebuild a decryptor from scratch should the original source code ever be lost
|
|
|
|
## Requirements
|
|
|
|
```bash
|
|
python3 -m venv venv && . venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Generate an ML-KEM-1024 key pair
|
|
|
|
```bash
|
|
python3 gen_keys.py
|
|
```
|
|
|
|
Produces:
|
|
|
|
- `mlkem1024.pub` - ML-KEM-1024 public key (1568 bytes). Used to encrypt files. You use it to encrypt files for yourself locally. You can share it with anyone to encrypt files for you.
|
|
- `mlkem1024.sec` - ML-KEM-1024 secret key (3168 bytes). Required to decrypt any file encrypted with your public key. Keep it secure and never share it. If lost, you permanently lose access to all encrypted files. If compromised, all encrypted files are exposed.
|
|
|
|
2. Encrypt a file
|
|
|
|
```bash
|
|
python3 encrypt.py archive.tar
|
|
```
|
|
|
|
Output: `archive.tar.kyb`
|
|
|
|
The `.kyb` file is self-contained: a compact CBOR header at the start describes the exact format, algorithms, and lengths. See [File Structure](#file-structure) for the layout.
|
|
|
|
3. Decrypt a file
|
|
|
|
```bash
|
|
python3 decrypt.py archive.tar.kyb
|
|
```
|
|
|
|
Output: `archive.tar`
|
|
|
|
If the file has been tampered with, you'll see: `Error: Integrity check failed. File corrupted or tampered` and the temp file is discarded.
|
|
|
|
## File Structure
|
|
|
|
`archive.tar.kyb`:
|
|
|
|
Section | Size | Description
|
|
-|-|-
|
|
CBOR header|91 bytes (v1)|Signature `KYB` (3 B) + version (1 B) + CBOR map (87 B): `{"KEM": "MLKEM1024", "CIPHER": "AES256GCM", "MLKEMCT": 1568, "IV": 12, "TAG": 16, "KDF": "HKDF-SHA256", "INFO": "mlkem-aes-key"}` |
|
|
ML-KEM ciphertext|1568 bytes|Encrypted shared secret. Your secret key (`mlkem1024.sec`) decrypts it to derive the AES-256 key that unlocks your file
|
|
IV (nonce)|12 bytes|12-byte nonce for AES-256-GCM, reused as salt for HKDF-SHA256 key derivation
|
|
File ciphertext|same as plaintext|AES-256-GCM encrypted chunks
|
|
GCM auth tag|16 bytes|16-byte authentication code that proves the file hasn't been tampered with. If any byte is modified, decryption fails
|