Verifying a release

A release carries checksums and a signature so you can tell that what you downloaded is what the maintainers published. Check before you run anything, especially the hub executable and the agent, which run with access to your machines.

What a release contains#

File	What it is
`yarrix-hub-<os>-<arch>`, `yarrix-<os>-<arch>`, `yarrix-windows-x64.zip`, `yarrix-agent-setup-windows-x64.exe`	The programs (install.md lists them)
`<file>.sha256`	The SHA-256 of one file, in `sha256sum` format
`SHA256SUMS`	The SHA-256 of every file above, in one list
`SHA256SUMS.minisig`	A minisign signature over `SHA256SUMS`
`MANIFEST.json`, `MANIFEST.json.minisig`	What agents check before updating themselves: the version, and the SHA-256 and size of every agent file, signed
`yarrix-sbom.spdx.json`	SBOM (SPDX) of the sources
`LICENSE`, `NOTICE`, `THIRD_PARTY_NOTICES.md`	The licence terms (also inside the Windows zip and the images' `/licenses`)

A checksum alone only tells you the file was not damaged in transit. The signature is what ties the checksums to the project's key, so check both.

1. Get the public key#

The project's release key is minisign.pub at the root of this repository. Take it from the repository at the tag you are installing, not from a copy next to the files you are checking:

untrusted comment: minisign public key FF62C46C18FCB125
RWQlsfwYbMRi/7BseGfH90R4IBDXMy0cdbAVTwR9SUvxINnDLBJIlAPU

Save the two lines as minisign.pub. The key ID in the first line is FF62C46C18FCB125; a signature made by a different key does not verify against this file.

2. Verify the signature, then the checksums#

Install minisign (brew install minisign, apt install minisign, or from the project page) and download SHA256SUMS, SHA256SUMS.minisig and the files you want into one folder.

minisign -Vm SHA256SUMS -p minisign.pub

It prints Signature and comment signature verified when the signature is good, and exits non-zero otherwise. Do not use the files if it fails. Then check the files against the signed list:

# Linux
sha256sum -c SHA256SUMS --ignore-missing
# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

Each file you downloaded must print OK. --ignore-missing skips the files you did not download. On Windows, Get-FileHash -Algorithm SHA256 .\yarrix-windows-x64.zip prints the hash to compare with the line in SHA256SUMS.

A hub that serves agent files gives you the same pair for each agent file (<file> and <file>.sha256, see install.md); that checks the hub's copy, and the signed SHA256SUMS from the release is the stronger check.

What agents verify for themselves#

When a hub moves an agent to a new release, the agent does its own check and does not rely on the hub: it accepts a new build only if MANIFEST.json carries a minisign signature from a key compiled into the agent (or listed in that machine's own agent.yaml), the version is newer, and the file's size and SHA-256 match the signed manifest. Details: Updating the agent and security.md.

Building from source or running a fork#

Official builds trust the project key in minisign.pub. If you build the agent or hub yourself and sign your own releases, put your public key line in YARRIX_RELEASE_PUBKEYS when you build (scripts/release/pubkey.sh <file> prints the line), or list it under update.trusted_keys in an agent's agent.yaml. A hub that should offer your releases needs the same line in its own YARRIX_RELEASE_PUBKEYS, because it checks against the built-in key unless that variable replaces it. Builds without a key trusted for your signatures will not self-update. Signing is done by a maintainer offline with scripts/release/sign-release.sh; the secret key is never part of the build.

Not signed yet#

The Windows installer and yarrix.exe are not Authenticode-signed, and the macOS binaries are not notarized. That is separate from the minisign signature above: minisign proves the files came from the project, but Windows SmartScreen and macOS Gatekeeper look for platform signatures. What to expect is in the Windows page and the macOS page.