Verify a downloaded release

Checking the checksum, the build-provenance attestation, and the platform signature before you install.

Written By Dustin

Last updated About 5 hours ago

Verify every download before running it. For a tool that will hold your signing and encryption keys, this is not ceremony.

What each release publishes

Artifact	What comes with it
Every archive and package	A `.sha256` sidecar next to it, holding `<digest> *<filename>` — one file per artifact, not a single combined manifest.
Archives (`.tar.gz`, `.zip`)	A Sigstore build-provenance attestation, and a second attestation carrying an SPDX SBOM for the same artifact.
`.deb` and `.rpm`	A Sigstore build-provenance attestation. (The SBOM attestation is published against the archives, not these.)
`.rpm`	Additionally GPG-signed, with the public key published as `RPM-GPG-KEY-tovio`.
macOS `.pkg`	An Apple Developer ID installer signature, and notarization.
Windows `.msi`	An Authenticode signature.

The order that matters

Verify the build-provenance attestation for the artifact you downloaded. This is the step that proves the bytes came out of the project's own release build, and it binds to the artifact's digest — so a substituted file cannot satisfy it.
Then check the file against its .sha256 sidecar. On its own a checksum only proves the file matches a number published beside it; it is a transfer-integrity check, not a provenance check.
Then let the platform signature do its job — rpm --checksig with the imported GPG key, Gatekeeper on the .pkg, Authenticode on the .msi.

Doing step 2 alone is the common mistake. A checksum file sitting beside a substituted artifact can be substituted just as easily.

Checking a checksum

sha256sum -c tovio-1.0.0-linux-x86_64.tar.gz.sha256

On macOS use shasum -a 256 -c; in PowerShell compare Get-FileHash -Algorithm SHA256 against the digest in the sidecar.

Checking the attestation

The provenance and SBOM attestations are Sigstore bundles produced by the release workflow and published with the release. Verify them with the GitHub CLI's gh attestation verify, pointed at the downloaded file and naming the owning repository. A verified attestation tells you which workflow, at which commit, produced those exact bytes.

If verification fails

Do not install it. Re-download once in case of a truncated transfer. If it fails again, report it to security@tovio.dev rather than on a public board — a genuine signature or attestation failure on a published artifact is a security matter, and the disclosure policy asks that it never start life as a public issue.