.TH ZUPT 1 "2026-05-01" "Zupt 2.2.3" "User Commands"
.SH NAME
zupt \- backup-oriented compression utility with hybrid post-quantum encryption
.SH SYNOPSIS
.B zupt compress
.RI [ OPTIONS ]
.I output.zupt files/dirs...
.br
.B zupt extract
.RI [ OPTIONS ]
.I archive.zupt
.br
.B zupt list
.RI [ OPTIONS ]
.I archive.zupt
.br
.B zupt test
.RI [ OPTIONS ]
.I archive.zupt
.br
.B zupt info
.I archive.zupt
.br
.B zupt bench
.RI [ --compare ]
.I files/dirs...
.br
.B zupt disk
.B backup\fR | \fBrestore
.RI [ OPTIONS ]
.br
.B zupt keygen
.RI [ -o
.IR file ]
.RI [ --pub ]
.RI [ --sdk ]
.RI [ -k
.IR privkey ]
.br
.B zupt version
.br
.B zupt help

.SH DESCRIPTION
.B zupt
is a backup-oriented compression utility with multi-threaded compression,
integrity verification, password-based encryption, and hybrid post-quantum
public-key encryption (ML-KEM-768 + X25519). Two PQ encryption modes are
supported: a legacy combiner kept for backward compatibility, and a
state-of-the-art mode backed by libzuptsdk (HKDF-SHA3 hybrid combiner with
domain separation, key commitment, HPKE binding RFC 9180, anti-fault
decapsulation, and Argon2id RFC 9106 password derivation).

.SH COMMANDS
.TP
.B compress, c
Create a compressed archive from one or more files or directories.
.TP
.B extract, x
Extract files from an archive.
.TP
.B list, l
List archive contents without extracting.
.TP
.B test, t
Verify archive integrity (decompresses without writing files).
.TP
.B info
Show archive metadata; works without password and without keys.
.TP
.B bench
Compare compression levels 1\(en9 on the given input.
.TP
.B disk backup\fR / \fBrestore
Full-disk backup/restore with sparse-region detection, progress
reporting, and proper sync discipline (\fBO_SYNC\fR + \fBfsync\fR + \fBsync\fR).
.TP
.B keygen
Generate or export hybrid PQ keypair. With
.B --sdk
flag, generates a libzuptsdk v2 keypair (private key file plus
.IR file .pub
public key file). Without
.BR --sdk ,
generates a legacy keypair compatible with
.BR --pq .

.SH GLOBAL OPTIONS
.TP
.BR -v ", " --verbose
Verbose per-file output.
.TP
.BR -q ", " --quiet
Suppress non-error output.
.TP
.BR -t ", " --threads " " \fIN\fR
Thread count: 0 = auto, 1 = single, 2\(en64 = explicit.

.SH COMPRESS OPTIONS
.TP
.BR -l ", " --level " " \fI1-9\fR
Compression level. Default 7. 1\(en2 fast/small window;
3\(en5 balanced; 6\(en7 high; 8\(en9 maximum (1MB window, deep search).
.TP
.BR -b ", " --block " " \fISIZE\fR
Block size in bytes. Default 128KB.
.TP
.BR -s ", " --store
Store without compression.
.TP
.BR -f ", " --fast
Use the fast LZ codec (less compression, higher throughput).
.TP
.BR --vv ", " --vaptvupt
Use the VaptVupt codec (LZ77 + tANS entropy, SIMD decode).
.TP
.B --lzhp
Use Zupt-LZHP (LZ77 + Huffman, no SIMD required).
.TP
.BR -p ", " --password " " \fIPW\fR
Encrypt with AES-256. If
.I PW
is empty, prompt the user.
.TP
.BR --pq " " \fIPUBKEY\fR
Encrypt using legacy PQ combiner (XOR + SHA3-512). Kept for
compatibility. New archives should prefer
.BR --pq-sdk .
.TP
.BR --pq-sdk " " \fIPUBKEY\fR
Encrypt using libzuptsdk v2 (recommended): HKDF-SHA3 hybrid combiner
with domain separation, 32-byte key commitment, HPKE binding (RFC 9180),
anti-fault decapsulation, AEAD via XChaCha20-Poly1305, password mode
via Argon2id (RFC 9106). The
.I PUBKEY
file is the
.IR file .pub
produced by
.BR "zupt keygen --sdk" .
.TP
.BR -D ", " --dedup
Block-level deduplication. Identical blocks across files are stored once.
.TP
.B --solid
Solid mode: concatenate files into a single stream before compression.

.SH EXTRACT / LIST / TEST OPTIONS
.TP
.BR -o ", " --output " " \fIDIR\fR
Output directory (extract only). Default: current directory.
.TP
.BR -p ", " --password " " \fIPW\fR
Decryption password.
.TP
.BR --pq " " \fIPRIVKEY\fR
Decrypt a legacy PQ archive.
.TP
.BR --pq-sdk " " \fIPRIVKEY\fR
Decrypt an SDK v2 PQ archive.

.SH KEYGEN OPTIONS
.TP
.BR -o " " \fIFILE\fR
Output keyfile path (required).
.TP
.B --pub
Export public key from an existing private key (used with
.BR -k ).
.TP
.BR -k " " \fIPRIVKEY\fR
Source private keyfile when exporting public key.
.TP
.BR --sdk ", " --pq-sdk
Generate an SDK v2 keypair. Writes
.I FILE
(private key) and
.IR FILE .pub
(public key) in one step. Use these keys with
.BR --pq-sdk .

.SH EXAMPLES
.TP
Compress without encryption:
.B
   zupt c backup.zupt ~/Documents/

.TP
Compress with password:
.B
   zupt c -l 9 -p 'my-pass' secure.zupt data/

.TP
Generate legacy keypair, encrypt, decrypt:
.nf
   zupt keygen -o mykey.key
   zupt keygen --pub -o pub.key -k mykey.key
   zupt c --pq pub.key backup.zupt ~/Documents/
   zupt x --pq mykey.key backup.zupt -o ~/restored/
.fi

.TP
Generate SDK v2 keypair, encrypt, decrypt (recommended):
.nf
   zupt keygen --sdk -o mykey.priv
   # creates mykey.priv (private) and mykey.priv.pub (public)
   zupt c --pq-sdk mykey.priv.pub backup.zupt ~/Documents/
   zupt x --pq-sdk mykey.priv backup.zupt
.fi

.TP
Full-disk backup with PQ encryption:
.nf
   zupt keygen --sdk -o disk.priv
   zupt disk backup --pq-sdk disk.priv.pub /dev/sda backup.img.zupt
.fi

.SH FILES
.TP
.I /usr/bin/zupt
The zupt binary.
.TP
.I /usr/lib/x86_64-linux-gnu/libzuptsdk.so.2
The libzuptsdk shared library (Linux x86_64).
.TP
.I /usr/include/zuptsdk.h
libzuptsdk public C API.
.TP
.I /usr/share/doc/zupt/
Documentation, changelog, audit reports.

.SH ENVIRONMENT
.TP
.B ZUPT_THREADS
Default thread count when
.B -t
is not specified.
.TP
.B ZUPT_TMPDIR
Temporary directory for intermediate files (default:
.IR /tmp ).

.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
General error (invalid arguments, file not found, etc.).
.TP
.B 2
Authentication failure (wrong password, wrong key, tampered ciphertext).
.TP
.B 3
I/O error.
.TP
.B 4
Archive format error (corrupt, unsupported version, malformed header).

.SH SECURITY
.B zupt 2.2+
recommends
.B --pq-sdk
for new archives. The legacy
.B --pq
mode uses an XOR+SHA3-512 hybrid combiner that has been superseded
by HKDF-SHA3 with domain separation in the SDK path. Both modes
remain supported for archive interoperability.

For password-encrypted archives, prefer the SDK path: it uses
Argon2id (RFC 9106) with OWASP-compliant minimum parameters
(64 MiB memory, 3 iterations, 1 thread), versus PBKDF2-SHA256 in
the legacy path.

.B Path traversal protection.
zupt 2.2.3+ rejects archive entries containing
.IR ".." ,
absolute paths
.RI ( /foo
or
.IR C:\\foo ),
or embedded NUL bytes. On POSIX systems, output files are opened with
.B O_NOFOLLOW
so that pre-existing symlinks at the extraction target are not followed
(defense against TOCTOU attacks where an attacker plants a symlink in the
output directory before extraction). On Windows, this defense relies on
directory ACLs.

.B Operational guidance for untrusted archives.
Always extract into an empty dedicated directory, audit symlinks before
extraction, and never run extraction as root.

.SH BUGS
Report at
.UR https://git.securityops.co/cristiancmoises/zupt/issues
.UE
or by email to
.MT zupt@riseup.net
.ME .

.SH AUTHOR
Cristian Cezar Moisés
.MT zupt@riseup.net
.ME

.SH SEE ALSO
.BR zupt-gui (1),
.BR tar (1),
.BR gzip (1).

.SH STANDARDS
Zupt implements algorithms from FIPS 197 (AES), FIPS 202 (Keccak/SHA-3),
FIPS 203 (ML-KEM), and follows RFC 5297 (AES-SIV), RFC 5869 (HKDF),
RFC 7748 (X25519), RFC 8439 (ChaCha20-Poly1305), RFC 9106 (Argon2),
and RFC 9180 (HPKE). Cryptographic primitive selection is aligned
with Brazilian Instrução Normativa ITI nº 35/2026, which incorporated
ML-KEM-768/1024 into the ICP-Brasil framework.

.SH LICENSE
.PP
Zupt itself (CLI, GUI, libzuptsdk, Jasmin source) is licensed under the
.B GNU Affero General Public License version 3 or later
(AGPL-3.0-or-later). The bundled VaptVupt LZ codec
.RB ( src/vv_*.c ", " src/vaptvupt_api.c )
is licensed under the
.B GNU General Public License version 3 or later
(GPL-3.0-or-later). VaptVupt is GPL not AGPL so that, with sufficient
maturity, it can be considered for upstreaming into the Linux or BSD
kernels.
.PP
Commercial licenses (relief from copyleft terms) are available for both
components. Contact
.MT sac@securityops.co
.ME .
.PP
See
.B /usr/share/doc/zupt/LICENSE
and
.B /usr/share/doc/zupt/THIRD-PARTY-NOTICES.md
for the full text and complete attribution.

.SH PROJECT
.PP
Home page:
.UR https://git.securityops.co/cristiancmoises/zupt
.UE
.PP
Related projects (all by Cristian Cezar Moisés, hosted on
git.securityops.co):
.IP \(bu 2
.B zupt-android
\(em
.UR https://git.securityops.co/cristiancmoises/zupt-android
.UE
.IP \(bu 2
.B zupt-web
\(em
.UR https://git.securityops.co/cristiancmoises/zupt-web
.UE
.IP \(bu 2
.B libzuptsdk
\(em
.UR https://git.securityops.co/cristiancmoises/libzuptsdk
.UE
.IP \(bu 2
.B vaptvupt
(standalone GPL codec) \(em
.UR https://git.securityops.co/cristiancmoises/vaptvupt
.UE