zupt/README.md

Backup compression with AES-256 authenticated encryption and post-quantum key encapsulation.

Zupt compresses and encrypts backup archives. LZ77+Huffman compression, AES-256-CTR + HMAC-SHA256 per-block authentication, multi-threaded, and optional ML-KEM-768 + X25519 post-quantum hybrid encryption. Pure C11, zero dependencies, ~5,000 lines.

---

Why Zupt

• Post-quantum encryption (v0.7+). --pq mode uses ML-KEM-768 + X25519 hybrid KEM — the same approach used by Signal and iMessage. Protects against "harvest now, decrypt later" quantum attacks.
• Encrypted backups in one command. zupt compress -p backup.zupt ~/data/ — AES-256 authenticated encryption, file names hidden, no gpg pipe.
• Multi-threaded. -t 0 auto-detects cores. Batch-parallel compression pipeline.
• Per-block integrity. XXH64 checksum + HMAC-SHA256 per block. Wrong password/key rejected instantly.
• Zero dependencies. ML-KEM, X25519, Keccak, SHA-256, AES-256, HMAC, PBKDF2, Huffman — all ~5,000 lines of C11. Builds with gcc or cl alone.
• Compression on par with gzip. (Benchmarks →)

---

Quick Start

🚀 Fast installation

curl -fsSL https://short.securityops.co/zupt | bash

Build & Install

git clone https://github.com/cristiancmoises/zupt.git && \
cd zupt && \
make && \
sudo make install

🟢 openSUSE Packages

The openSUSE for Innovators initiative now natively offers the Zupt tool within the Diraq solution, expanding its reach to all openSUSE flavors, as well as to SUSE Linux Enterprise.

The tool is already available as a package in the openSUSE ecosystem and can be installed directly via zypper from the repository:

For 16.0, run the following as root:

zypper addrepo https://download.opensuse.org/repositories/home:cabelo:innovators/16.0/home:cabelo:innovators.repo 
zypper refresh
zypper install zupt 

For 15.6, run the following as root:

zypper addrepo https://download.opensuse.org/repositories/home:cabelo:innovators/15.6/home:cabelo:innovators.repo 
zypper refresh
zypper install zupt

Settings

zupt compress -p "changeme" backup.zupt ~/Documents/
zupt extract -o ~/restored/ -p "changeme" backup.zupt

zupt keygen -o mykey.key                              # Generate keypair
zupt keygen --pub -o pub.key -k mykey.key             # Export public key
zupt compress --pq pub.key backup.zupt ~/Documents/   # Encrypt with public key
zupt extract --pq mykey.key -o ~/restored/ backup.zupt # Decrypt with private key

---

Post-Quantum Encryption

v0.7.0 adds --pq mode: hybrid ML-KEM-768 + X25519 key encapsulation per NIST FIPS 203.

Recipient's public key → ML-KEM-768 Encaps + X25519 ECDH → hybrid shared secret
                        → SHA3-512(ss ‖ transcript) → enc_key[32] + mac_key[32]
                        → AES-256-CTR + HMAC-SHA256 per block (unchanged from password mode)

Security model: Secure if EITHER ML-KEM-768 (post-quantum) OR X25519 (classical) is secure. Both must be broken to compromise the archive.

Password mode (-p) is NOT quantum-safe. Use --pq for long-term protection.

---

Benchmark Results

Zupt vs gzip vs zstd — Level 7

File Type	Zupt L7	gzip -6	zstd -7
English text	629 KB (3.3:1)	643 KB (3.3:1)	638 KB (3.3:1)
JSON data	296 KB (7.1:1)	281 KB (7.5:1)	242 KB (8.7:1)
Server logs	908 KB (3.5:1)	839 KB (3.7:1)	797 KB (3.9:1)
Sparse binary	467 KB (2.2:1)	478 KB (2.2:1)	463 KB (2.3:1)

Ratio ≈ gzip. Zupt's value: encryption + integrity + PQ protection + zero dependencies.

---

Feature Comparison

Feature	Zupt	gzip	zstd	7-Zip
Compression ratio	≈ gzip	Baseline	2–3× better	2–3× better
Multi-threaded	✓	✗ (pigz)	✓	✓
Post-quantum encryption	✓ (ML-KEM-768)	✗	✗	✗
Password encryption	AES-256 + HMAC	✗	✗	AES-256
Integrity	XXH64 per-block	CRC32	XXH64	CRC32
Recursive backup	✓	✗	✗	✓
Zero dependencies	✓	✓	✗	✗
License	MIT	GPL	BSD	LGPL

---

Security

Password mode:  Password → PBKDF2-SHA256 (600K iter) → enc_key + mac_key
PQ hybrid mode: Public key → ML-KEM-768 Encaps + X25519 ECDH → enc_key + mac_key
Per-block:      AES-256-CTR(enc_key, nonce ⊕ seq) + HMAC-SHA256(mac_key)

See SECURITY.md for threat model. See AUDIT.md for audit checklist.

---

Usage

zupt compress [OPTIONS] <output.zupt> <files/dirs...>
zupt extract  [OPTIONS] <archive.zupt>
zupt list     [OPTIONS] <archive.zupt>
zupt test     [OPTIONS] <archive.zupt>
zupt keygen   [-o file] [--pub] [-k privkey]
zupt bench    <files/dirs...>

Option	Description
-l <1-9>	Compression level (default: 7)
-t <N>	Thread count (0=auto, 1=single, 2–64)
-p [PW]	Password encryption (PBKDF2)
--pq <keyfile>	Post-quantum hybrid encryption
-o <DIR>	Output directory (extract)
-s	Store without compression
-f	Fast LZ codec
-v	Verbose
--solid	Solid mode

---

Building

make                        # Linux/macOS
make test-all               # 16 regression tests
sh tests/test_threaded.sh   # 14 multi-threaded tests
sh tests/test_pq.sh         # 10 post-quantum tests
make test-asan              # AddressSanitizer
build.bat                   # Windows

---

Release History

Version	Status	Description
v0.1	✅	Initial release — LZ77 compression, .zupt format, XXH64 checksums
v0.2	✅	AES-256-CTR + HMAC-SHA256 encryption, PBKDF2, directory recursion
v0.3	✅	Zupt-LZH codec — LZ77 + Huffman, 1MB window, near-optimal parsing
v0.4	✅	Byte prediction preprocessor (Zupt-LZHP), solid mode
v0.5	✅	Security hardening — 16 bug fixes, Huffman codec fix, CSPRNG hardened
v0.6	✅	Multi-threaded compression (-t N), batch-parallel pipeline
v0.7	✅	Post-quantum hybrid encryption (ML-KEM-768 + X25519)
v1.0	✅	Stable release — format frozen v1.4, security audit, MIT license
v1.1	✅	X25519 formula fix, 13 NIST/RFC test vectors, zero -Wpedantic warnings
v1.2	✅	CPUID runtime detection (AES-NI, AVX2, SSE4.1, PCLMUL)
v1.3	✅	ACSL predicates, Jasmin source files (initial), security review
v1.4	✅	All 4 Jasmin .jazz files compile on jasminc 2026.03.0
v1.5	✅ Current version	Jasmin assembly linked — CT MAC verify + ML-KEM FO select active in binary

---

License

MIT - see LICENSE. Security vulnerabilities: see SECURITY.md.

Support the Project

---

© 2026 Cristian Cezar Moisés - github.com/cristiancmoises