368 lines
8.6 KiB
Groff
368 lines
8.6 KiB
Groff
.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
|