You will learn#
- what is signed and attested in a release;
- the commands that verify the archive and the image;
- what a failure means.
The idea#
Every release is built by one workflow, release.yml, on GitHub. It signs checksums.txt with cosign (keyless, through Sigstore), attaches a build provenance attestation, and signs and attests the digests of the container image on both registries. You verify that the file you hold is the one that workflow built from a tag, without trusting the download.
Install cosign, the GitHub CLI gh and, for the image, docker.
Quick start#
Set the version, then download and verify the archive of your platform:
VERSION=vX.Y.Z
V="${VERSION#v}"
REPO=AlexGalhardo/vukem-video
ARCHIVE="vukem-video_${V}_linux_amd64.tar.gz"
IDENTITY="^https://github[.]com/$REPO/[.]github/workflows/release[.]yml@refs/tags/v"
ISSUER=https://token.actions.githubusercontent.com
gh release download "$VERSION" -R "$REPO" -p checksums.txt -p checksums.txt.sigstore.json \
-p "$ARCHIVE" -p "$ARCHIVE.sbom.json"
cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
sha256sum --ignore-missing -c checksums.txt
gh attestation verify "$ARCHIVE" -R "$REPO"On macOS use shasum -a 256 -c for the check of the checksums. The release also attaches the provenance bundle, vukem-video.intoto.jsonl, and a software bill of materials (SBOM) for each archive.
Verify the container image on both registries. The two digests printed must be equal, because one build is pushed to both:
for image in ghcr.io/alexgalhardo/vukem-video alexgalhardo/vukem-video; do
digest="$(docker buildx imagetools inspect "$image:$V" --format "{{.Manifest.Digest}}")"
cosign verify "$image@$digest" \
--certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
echo "$image $digest"
done
docker run --rm "ghcr.io/alexgalhardo/vukem-video:$V" versionThe last command prints vukem-video vX.Y.Z. The Windows and macOS installers are not signed with a paid code-signing certificate; the signed checksums.txt is how you verify them.
The BETA installers are not signed#
The BETA has no paid code signing: no Apple Developer ID or notarization, and no Windows code-signing certificate. This covers the installers of the local server and the installers of the desktop application (vukem-video-desktop_X.Y.Z_windows_amd64_setup.exe, ..._darwin_arm64.dmg, ..._darwin_amd64.dmg and ..._linux_amd64.deb). Paid signing is decided again before 1.0. Until then the proof that a file is the one the project built is the signature of checksums.txt and the attestation of the file, and your system warns before it runs the file:
- Windows SmartScreen shows "Windows protected your PC". Choose More info, then Run anyway. The publisher shows as unknown because there is no certificate.
- macOS Gatekeeper says the app or package cannot be opened because Apple cannot check it. Control-click (right-click) it, choose Open, then Open again; or run
xattr -d com.apple.quarantine <path of the file or app>.
A warning is not a verdict, and a missing warning is not proof. Verify the file first; the checks below do not depend on what the system says.
Download the installer and run, with the version and the file name of your system:
FILE="vukem-video-desktop_${V}_windows_amd64_setup.exe"
gh release download "$VERSION" -R "$REPO" -p "$FILE"
bash scripts/desktop-verify.sh "$VERSION" "$FILE"scripts/desktop-verify.sh is in the repository (clone it, or download it from the tag). It downloads checksums.txt and its signature, verifies the signature with cosign, checks that the SHA-256 of your file equals its line of checksums.txt, and runs gh attestation verify on the file. It uses neither codesign nor signtool, because there is no code signature to check. Without the script, do the same by hand with the commands of the quick start, using $FILE where they use $ARCHIVE.
The update feed#
The desktop application can look for a newer version, but only when you turn it on: the setting update.check is off by default and the application then opens no connection. It reads one signed file, feed.json, from the GitHub Pages site of the project (<site>/updates/feed.json), and the installers it lists come from the same address. The feed and each installer are signed with an Ed25519 key whose public half is built into the application; a file that does not match its signature or its digest is refused. The release also attaches feed.json, and bash scripts/release-verify.sh vX.Y.Z checks that every digest in it equals checksums.txt.
Common mistakes#
- Skipping
cosign verify-bloband running onlysha256sum: a checksum file you did not verify proves nothing. - Changing the identity regexp to accept any workflow. Keep it exact: the identity is the proof of who built the file.
- A recovery run signed from a branch instead of a tag has the identity
@refs/heads/<branch>; the regexp above rejects it on purpose. Use the next tagged release.