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

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

Usage

1. Generate an ML-KEM-1024 key pair

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

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 for the layout.

3. Decrypt a file

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