cristiancmoises/zupt
Watch
1
0
Fork
You've already forked zupt
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions 3

v4.1.0: source-only build, multithreaded-encryption fix, security hardening

Browse source 
Build from source with no vendored binaries:
- Remove prebuilt libzuptsdk.so / libpqvaptvupt.so (and a stray .pyc). The
  default build needs only a C compiler + make; it links no external library
  and installs no .so. The libzuptsdk-backed modes (Argon2id KDF, --pq-sdk,
  --pq-box) are gated behind an opt-in `make WITH_SDK=1`. The default password
  KDF is PBKDF2-SHA256 and --pq (native ML-KEM-768 + X25519) is the built-in PQ
  mode. openSUSE/RPM/deb/AUR/Homebrew/Nix recipes bumped to 4.1.0; the openSUSE
  spec now builds source-only (%files ships no .so, %build/%install WITH_SDK=0).

Fix: multithreaded encrypted archives were unextractable on the native AEAD
path. The parallel compress/decompress workers skipped the F-09 frame-preface
AAD that the serial path and the archive's AAD_PREFACE flag bind into every
block MAC, so each multithreaded block failed authentication. The workers now
bind the preface via a shared serializer; output is byte-identical across
thread counts and interoperates with single-threaded archives (also fixes
`--kdf pbkdf2 -t N` in any build).

Security hardening (crafted-archive memory safety + crypto):
- LZH raw code-length stack overflow + huff_lut OOB write
- overflow-safe bounds in parse_index and solid-mode extract (heap OOB read)
- SEQ decoder safe-zone heap overflow (litlen+matchlen reserve)
- require the per-block ENCRYPTED flag on encrypted archives (plaintext forgery)
- cap archive-supplied PBKDF2 iteration count (KDF-amplification DoS)
- non-elidable secret wipe in the SDK path; restored disk images created 0600

Docs: remove AUDIT.md / BENCHMARKS.md / ROADMAP.md; trim marketing/AI-styled
text and correct KDF/PQ facts across README, SECURITY, INSTALL, DISTRIBUTION,
THREAT_MODEL, THIRD-PARTY-NOTICES, the man page, and packaging READMEs. Wire
format v1.6 unchanged.
This commit is contained in:
Cristian Cezar Moisés 2026-07-07 19:45:37 -03:00
commit 4874010d0e
39 changed files with 1097 additions and 2770 deletions
Download patch file Download diff file Expand all files Collapse all files

130
DISTRIBUTION.md
View file

@ -1,40 +1,29 @@
# Distributing VaptVupt
This document describes the upstream packaging recipes shipped under
`packaging/` and the path from "local source tree" to "package
installable on every major Linux distribution and macOS."
This document describes the upstream packaging recipes shipped under `packaging/` and the path from a local source tree to an installable package.
Recipes are upstream-maintained but distro-submission-ready. Real
submission to AUR / Debian / Fedora / Homebrew / NixOS is operational
work outside this repository.
Real submission to AUR / Debian / Fedora / Homebrew / NixOS / openSUSE is operational work outside this repository.
## Producing a reproducible source tarball
Every packaging recipe expects an upstream tarball `vaptvupt-VERSION.tar.gz`
produced by the project's `make dist` target. The tarball is
**byte-reproducible**:
Every packaging recipe expects an upstream tarball `vaptvupt-VERSION.tar.gz` produced by the project's `make dist` target. The tarball is byte-reproducible:
```sh
make dist
# → /tmp/vaptvupt-2.4.4.tar.gz
# → sha256: 407d20ef03e5bf857195b99e04843ef3b07357416a4115add1e8aaa2007a769f
# → bytes: 813113
# → /tmp/vaptvupt-4.1.0.tar.gz
```
Re-running `make dist` on the same source tree produces an identical
sha256 (verified by `tests/test_dist_reproducible.sh`, wired into
`make test`). This lets distros pin a stable hash in their recipes.
Re-running `make dist` on the same source tree produces an identical sha256 (verified by `tests/test_dist_reproducible.sh`, wired into `make test`). This lets distros pin a stable hash in their recipes.
The reproducibility properties:
- Files sorted by name (deterministic order across filesystems)
- mtime fixed to `SOURCE_DATE_EPOCH` (default `1747699200`; override
via env)
- mtime fixed to `SOURCE_DATE_EPOCH` (default `1747699200`; override via env)
- uid/gid pinned to root (0/0) via `--owner=0 --group=0 --numeric-owner`
- gzip wrapped with `-9n` (no embedded timestamp or filename)
- Source-only — no `.o`, no built binaries, no `.git/` tree
- Includes the vendored `libzuptsdk.so.2.0.0` real file plus its two
symlinks (`libzuptsdk.so`, `libzuptsdk.so.2`)
The tree is source-only. The default `make` build needs only a C compiler, make, libm, and pthread — no external crypto library, and it installs no `.so`. The optional SDK-backed modes (`--pq-sdk`, `--pq-box`) and the Argon2id KDF are built only with `make WITH_SDK=1` against the separately distributed `libzuptsdk` / `libpqvaptvupt` libraries.
To force a specific epoch (for distro release-day pinning):
@ -48,20 +37,17 @@ SOURCE_DATE_EPOCH=1727740800 make dist # 2024-10-01 UTC
|-------------------|---------------------------------|----------------|
| Arch Linux | `packaging/aur/PKGBUILD` | AUR PKGBUILD |
| Debian / Ubuntu | `packaging/debian/` | Source package (`3.0 (quilt)`) |
| Fedora / RHEL | `packaging/rpm/vaptvupt.spec` | RPM .spec |
| macOS | `packaging/homebrew/vaptvupt.rb` | Homebrew formula |
| Fedora / RHEL | `packaging/rpm/vaptvupt.spec` | RPM .spec |
| openSUSE | `packaging/opensuse/` | RPM .spec (OBS) |
| macOS | `packaging/homebrew/vaptvupt.rb`| Homebrew formula |
| NixOS / Nix flake | `packaging/nix/flake.nix` | Nix flake |
All recipes:
- Install the binary to `$PREFIX/bin/vaptvupt` (default `/usr/bin/vaptvupt`)
- Install the vendored `libzuptsdk.so*` triple to `$PREFIX/lib/vaptvupt/`
(the binary uses relative `rpath` so users don't need `LD_LIBRARY_PATH`)
- Install manpage to `$PREFIX/share/man/man1/vaptvupt.1.gz`
- Install docs (README, SECURITY, CHANGELOG, AUDIT) to
`$PREFIX/share/doc/vaptvupt/`
- Run the full upstream regression suite (`make test`) during build
when the distro's package guidelines allow check-phase execution
- Install docs (README, SECURITY, CHANGELOG) to `$PREFIX/share/doc/vaptvupt/`
- Run the full upstream regression suite (`make test`) during build when the distro's package guidelines allow check-phase execution
## Arch Linux (AUR)
@ -70,13 +56,13 @@ Maintainer flow:
```sh
# 1. Produce the upstream tarball
make dist
# → /tmp/vaptvupt-2.4.4.tar.gz
# → /tmp/vaptvupt-4.1.0.tar.gz
# 2. Upload to a stable URL (e.g. git.securityops.co releases)
# 3. Update packaging/aur/PKGBUILD:
# - Set pkgver=2.4.4
# - Set sha256sums=("$(sha256sum /tmp/vaptvupt-2.4.4.tar.gz | awk '{print $1}')")
# - Set pkgver=4.1.0
# - Set sha256sums=("$(sha256sum /tmp/vaptvupt-4.1.0.tar.gz | awk '{print $1}')")
# 4. Generate .SRCINFO
cd packaging/aur && makepkg --printsrcinfo > .SRCINFO
@ -87,7 +73,7 @@ makepkg -s
# 6. Push to AUR
git clone ssh://aur@aur.archlinux.org/vaptvupt.git aur-vaptvupt
cp packaging/aur/PKGBUILD packaging/aur/.SRCINFO aur-vaptvupt/
cd aur-vaptvupt && git add -A && git commit -m "v2.4.4" && git push
cd aur-vaptvupt && git add -A && git commit -m "v4.1.0" && git push
```
User install:
@ -96,10 +82,9 @@ User install:
yay -S vaptvupt # or paru, pikaur, etc.
```
## Shell completions (v2.4.7+)
## Shell completions
`make install` automatically installs Bash, zsh, and fish completion
files alongside the binary and manpage:
`make install` automatically installs Bash, zsh, and fish completion files alongside the binary and manpage:
| Shell | Path |
|---|---|
@ -107,10 +92,7 @@ files alongside the binary and manpage:
| zsh | `$PREFIX/share/zsh/site-functions/_vaptvupt` |
| fish | `$PREFIX/share/fish/vendor_completions.d/vaptvupt.fish` |
The source files live under `completions/` in the project tree.
Distros that prefer a different install location should override
the relevant paths in their `make install` invocation; the
underlying recipe is straightforward.
The source files live under `completions/` in the project tree. Distros that prefer a different install location should override the relevant paths in their `make install` invocation.
For per-user installation without root:
@ -125,24 +107,20 @@ cp completions/_vaptvupt ~/.zsh/completion/_vaptvupt
cp completions/vaptvupt.fish ~/.config/fish/completions/vaptvupt.fish
```
Completions cover every CLI flag the binary actually parses
(`--kdf`, `--comment`, `--comment-file`, `--pq-sdk`, `--dedup`,
etc.) and are validated on every CI run via
`tests/test_completions_manpage.sh`.
Completions cover every CLI flag the binary actually parses (`--kdf`, `--comment`, `--comment-file`, `--pq`, `--dedup`, etc.) and are validated on every CI run via `tests/test_completions_manpage.sh`.
## Debian / Ubuntu
The `packaging/debian/` tree is a Debian source-package layout.
Maintainer flow:
The `packaging/debian/` tree is a Debian source-package layout. Maintainer flow:
```sh
# 1. Produce the upstream tarball with the standard Debian
# orig.tar.gz naming convention:
make dist
cp /tmp/vaptvupt-2.4.4.tar.gz /tmp/vaptvupt_2.4.4.orig.tar.gz
cp /tmp/vaptvupt-4.1.0.tar.gz /tmp/vaptvupt_4.1.0.orig.tar.gz
# 2. Unpack and overlay the debian/ tree:
cd /tmp && tar xzf vaptvupt_2.4.4.orig.tar.gz && cd vaptvupt-2.4.4
cd /tmp && tar xzf vaptvupt_4.1.0.orig.tar.gz && cd vaptvupt-4.1.0
cp -a /path/to/vaptvupt/packaging/debian ./debian
# 3. Build the source package:
@ -150,7 +128,7 @@ dpkg-buildpackage -S -us -uc # source-only
dpkg-buildpackage -b -us -uc # binary
# 4. Lint:
lintian vaptvupt_2.4.4-1_*.deb
lintian vaptvupt_4.1.0-1_*.deb
# 5. Submit via the standard Debian mentors process:
# https://mentors.debian.net/intro-maintainers/
@ -167,7 +145,7 @@ sudo apt install vaptvupt
```sh
# 1. Produce the tarball
make dist
cp /tmp/vaptvupt-2.4.4.tar.gz ~/rpmbuild/SOURCES/
cp /tmp/vaptvupt-4.1.0.tar.gz ~/rpmbuild/SOURCES/
# 2. Drop the .spec into the SPECS directory:
cp packaging/rpm/vaptvupt.spec ~/rpmbuild/SPECS/
@ -176,7 +154,7 @@ cp packaging/rpm/vaptvupt.spec ~/rpmbuild/SPECS/
cd ~/rpmbuild && rpmbuild -ba SPECS/vaptvupt.spec
# 4. Lint:
rpmlint RPMS/x86_64/vaptvupt-2.4.4-1.fc*.rpm
rpmlint RPMS/x86_64/vaptvupt-4.1.0-1.fc*.rpm
# 5. Submit via the Fedora new-package review process:
# https://docs.fedoraproject.org/en-US/package-maintainers/Package_Review_Process/
@ -190,6 +168,31 @@ sudo dnf install vaptvupt # Fedora
sudo dnf install epel-release vaptvupt # RHEL/CentOS via EPEL
```
## openSUSE
The `packaging/opensuse/` tree carries an RPM `.spec` suited to the Open Build Service (OBS).
```sh
# 1. Produce the tarball
make dist
# 2. In an OBS package checkout (osc), stage the sources and spec:
cp /tmp/vaptvupt-4.1.0.tar.gz .
cp /path/to/vaptvupt/packaging/opensuse/vaptvupt.spec .
# 3. Build locally against a target repository:
osc build openSUSE_Tumbleweed x86_64
# 4. Commit to OBS once the build and check phase pass:
osc addremove && osc commit
```
User install (after the package lands in a distribution or OBS repository):
```sh
sudo zypper install vaptvupt
```
## macOS (Homebrew)
```sh
@ -227,12 +230,12 @@ nix build github:cristiancmoises/vaptvupt#vaptvupt
nix run github:cristiancmoises/vaptvupt#vaptvupt -- version
# 2. To consume from another flake:
# inputs.zupt.url = "github:cristiancmoises/vaptvupt?ref=v2.4.4";
# packages.x86_64-linux.default = inputs.zupt.packages.x86_64-linux.zupt;
# inputs.vaptvupt.url = "github:cristiancmoises/vaptvupt?ref=v4.1.0";
# packages.x86_64-linux.default = inputs.vaptvupt.packages.x86_64-linux.vaptvupt;
# 3. To submit to nixpkgs (https://github.com/NixOS/nixpkgs):
# - Adapt packaging/nix/flake.nix's `vaptvupt` derivation into a
# pkgs/by-name/zu/vaptvupt/package.nix using fetchurl and a hash.
# pkgs/by-name/va/vaptvupt/package.nix using fetchurl and a hash.
# - Follow the nixpkgs contribution guide:
# https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md
```
@ -241,28 +244,15 @@ nix run github:cristiancmoises/vaptvupt#vaptvupt -- version
Before pushing any recipe to a distro repository:
- [ ] `make dist` produces a reproducible tarball (verified by
`tests/test_dist_reproducible.sh` on every `make test`)
- [ ] `make dist` produces a reproducible tarball (verified by `tests/test_dist_reproducible.sh` on every `make test`)
- [ ] The tarball is uploaded to a stable, immutable URL
- [ ] The recipe's checksum field is updated to match
`sha256sum /tmp/vaptvupt-VERSION.tar.gz`
- [ ] The recipe's checksum field is updated to match `sha256sum /tmp/vaptvupt-VERSION.tar.gz`
- [ ] The recipe builds and tests pass in a clean chroot/container
- [ ] The CHANGELOG mentions distro-relevant changes since the last release
- [ ] The license metadata is correct (AGPL-3.0-or-later for VaptVupt core;
GPL-3.0-or-later for the vendored VaptVupt codec)
- [ ] The license metadata is correct (AGPL-3.0-or-later for VaptVupt core; GPL-3.0-or-later for the vendored VaptVupt codec)
## Security posture for downstream
Every packaging recipe runs `make test` during build (`check()` for AUR,
`override_dh_auto_test` for Debian, `%check` for RPM, `checkPhase` for
Nix, `test` block for Homebrew). The suite includes:
Every packaging recipe runs `make test` during build (`check()` for AUR, `override_dh_auto_test` for Debian, `%check` for RPM and openSUSE, `checkPhase` for Nix, `test` block for Homebrew). The test suite runs in each recipe's check phase, including the tamper/integrity regressions and the `make dist` byte-identical reproducibility check.
- **F-06**: 2 000 HMAC tamper trials, 0 silent accepts required
- **F-08**: top-MAC header/footer integrity-trailer regression
- **F-09**: 1 827-position exhaustive byte sweep on PQ-SDK archive,
0 silent accepts required
- **F-10..F-12**: KDF default, auth-fail message, encrypted comments
- **dist reproducibility**: `make dist` byte-identical across two runs
A build that doesn't pass `make test` will fail at distro check time —
the recipes don't paper over regressions.
A build that doesn't pass `make test` will fail at distro check time — the recipes don't paper over regressions.