Skip to content

VERIFYING_RELEASES.md

Latest commit

 

History

History
164 lines (104 loc) · 3.34 KB

VERIFYING_RELEASES.md

File metadata and controls

164 lines (104 loc) · 3.34 KB

Verifying Releases

This document explains how to verify the integrity and authenticity of the binaries published in GitHub Releases.

These steps are designed to match exactly how releases are produced by the current release.yml workflow.

What is provided in each release

For every tagged release (vX.Y.Z), the GitHub Release contains:

  • seedctl-<VERSION>-linux-x86_64 — Linux binary
  • seedctl-<VERSION>-windows-x86_64.exe — Windows binary
  • SHA256SUMS — SHA-256 checksums for all binaries
  • SHA256SUMS.asc — GPG signature of SHA256SUMS

The tag name is derived from Cargo.toml:

v<version-from-Cargo.toml>

Threat model

This verification protects against:

  • Accidental corruption during download
  • Malicious modification of binaries
  • Compromised GitHub account or CI artifacts

It does not protect against:

  • A compromised signing key
  • A malicious maintainer

For stronger guarantees, combine this with reproducible builds (see REPRODUCIBILITY.md).

Step 1 — Download release files

From the GitHub Releases page, download all the following into the same directory:

  • seedctl-<VERSION>-linux-x86_64
  • seedctl-<VERSION>-windows-x86_64.exe
  • seedctl-<VERSION>-linux-x86_64.AppImage
  • SHA256SUMS
  • SHA256SUMS.asc

Example:

ls
seedctl-<VERSION>-linux-x86_64
seedctl-<VERSION>-windows-x86_64.exe
seedctl-<VERSION>-linux-x86_64.AppImage
SHA256SUMS
SHA256SUMS.asc

Step 2 — Import the release signing key

Import the maintainer's public GPG key:

gpg --import seedctl-release.pub

Verify the key fingerprint matches the one published in the repository README:

gpg --fingerprint

⚠️ Always verify the fingerprint via an independent channel (website, multiple repositories, or trusted contacts).

Step 3 — Verify authenticity (GPG)

Verify that SHA256SUMS was signed by the release key:

gpg --verify SHA256SUMS.asc SHA256SUMS

Expected output:

gpg: Good signature from "<Release Signing Key>"

If this step fails, do not trust the binaries.

Step 4 — Verify integrity (SHA-256)

Verify that the binaries match the published checksums:

sha256sum -c SHA256SUMS

Expected output:

seedctl-<VERSION>-linux-x86_64: OK
seedctl-<VERSION>-windows-x86_64.exe: OK

If any file fails verification, discard it immediately.

Notes on how releases are generated

The release artifacts are built by GitHub Actions using the following guarantees:

  • Builds run on:

    • ubuntu-latest
    • windows-latest

  • Rust toolchain: stable

  • Build command:

cargo build --release
  • Version is extracted directly from Cargo.toml
  • The Git tag is created as:
v<version>
  • SHA256SUMS is generated from the final binaries
  • SHA256SUMS.asc is created by signing SHA256SUMS with GPG inside CI

Reproducible builds

To independently verify that the binaries correspond to the source code, see:

  • REPRODUCIBILITY.md

Reproducibility + cryptographic signatures together provide the strongest guarantees.

Summary

✔ GPG verifies who produced the release ✔ SHA-256 verifies what you downloaded ✔ Reproducible builds verify how it was built

Always verify before using this software and prefer an offline, air‑gapped environment when possible.