nordisk/znippy

Provenance signing — guide

Class: guide · audience: a techie signing an archive and verifying provenance. The what is in signing-design.md; siblings plugins-guide.md · iceberg-guide.md.

f0 — sign on write, verify on read (the whole workflow)

Signing is a detached CMS authenticity layer on top of the per-chunk blake3 integrity. It is off by default; build with the sign feature:

cargo build --features sign

You need a PKCS#8 DER key and its X.509 cert (DER) to sign, and at least one trusted root CA (DER) to verify.

f1 — signing an archive

znippy compress -i <dir> -o out.znippy \
    --sign <pkcs8-key.der> --sign-cert <cert.der> [--sign-alg p256|ed25519]

• --sign-alg is p256 (default) or ed25519.
• The signature is a merkle fold of the chunk hashes already computed — signing adds no content re-read and does not touch blob bytes.
• Omit --sign and the archive is byte-identical to an unsigned build.

CLI entry: znippy-cli/src/lib.rs Commands::Compress --sign / --sign-cert / --sign-alg (:82-91).

f2 — verifying provenance

znippy verify -i out.znippy --signed --root <ca.der> [--root <ca2.der> …]

• --signed turns on signature checking; at least one --root is required.
• verify recomputes every artifact digest + the archive digest from the index and checks the detached CMS against the trusted roots — tamper with any chunk hash or artifact and the archive root no longer matches.

CLI entry: znippy-cli/src/lib.rs Commands::Verify --signed / --root (:142-147).

f3 — signing survives sealing

A signed archive round-trips through seal unchanged in trust: the merkle root is content-derived and stable, so verify the sealed artifact exactly as above:

znippy seal -i sidecar.znippy --warehouse <dir> -o sealed.znippy
znippy verify -i sealed.znippy --signed --root <ca.der>

Round-trip coverage: seal_signed_archive_round_trip, holger_verifies_a_served_artifact.