RFC-0013: Signed Releases + Verified Downloads

[kn4oqw-clint]

• Status: proposed
• Author: KN4OQW
• Comment window: 14 days from PR open
• Implements requirements: Signed releases; checksummed hostfile/ID database downloads #12 (signed releases; checksummed hostfile/ID database downloads)
• Depends on: nothing new; the verification primitive here is what the atomic-update lifecycle (Atomic updates with rollback — an update completes or the old version boots #13) will call before switching to a new release

Summary

Two things a hotspot pulls from the network must be tamper-evident: the
software it updates to, and the reference data it downloads (host lists, talkgroup
names, ID databases). Today both are fetched over TLS and used verbatim — TLS
proves transport, not provenance, so a compromised mirror or a malicious
operator-configured URL can feed a node bad data or a bad binary. This RFC adds a
single signature-verification primitive (minisign / Ed25519) and applies it in
both places: release artifacts are signed and verified before they are applied,
and reference-data refreshes verify a checksum or signature before the download
replaces the cache. The failure mode is uniform and loud — a tampered artifact
or database file is rejected with a clear error, which is the requirement's
acceptance.

Motivation

Pi-Star sbin #60 asked, years ago, for MD5 sums on the DMRId / host downloads;
it never shipped, and unsigned rolling updates remain the incumbent norm — a node
trusts whatever a mirror serves. That is two distinct risks:

1. Reference data. A hotspot pulls DMR host lists, talkgroup names, and ID
   databases on a schedule and feeds them to the gateways and the dashboard. A
   poisoned list can misroute traffic or mislabel it; the review of a live node
   already surfaced these downloads (and one where the upstream was simply
   unreachable). Verifying a checksum/signature makes a swapped file a rejection,
   not a silent adoption.
2. The software itself. An update mechanism that applies an unverified binary
   is the highest-value attack on the whole fleet. Before Waypoint ships atomic
   updates (Atomic updates with rollback — an update completes or the old version boots #13), the primitive that verifies a release must exist and be trusted.

minisign (Ed25519, a tiny well-specified format) is the right tool for an
appliance: no PKI, no CA, a 56-byte public key an operator can pin, and a standard
CLI (minisign) for the release side. Sigstore is powerful but its keyless/OIDC
model and transparency-log dependency are disproportionate for a Pi that may be
offline. The primitive is minisign-compatible so releases can be signed with the
stock tool and verified by a few hundred lines of Go with no new heavy dependency
(Ed25519 is stdlib; BLAKE2b is already in x/crypto).

Design

The verification primitive (internal/minisign)

A self-contained minisign verifier:

• Public key. Parses a minisign public key (the base64 line: 2-byte signature
  algorithm + 8-byte key id + 32-byte Ed25519 public key).
• Signature. Parses a .minisig (the untrusted-comment line, the base64
  signature line = algorithm + key id + 64-byte Ed25519 signature, the
  trusted-comment line, and the base64 global signature over signature ‖ trusted comment).
• Verify. Supports both minisign modes: legacy Ed (Ed25519 over the raw file)
  and modern prehashed ED (Ed25519 over BLAKE2b-512 of the file — the variant
  used for large files, and what minisign -S produces by default on recent
  versions). It checks the key id matches the trusted key, verifies the file
  signature, and verifies the global signature over the trusted comment, so a
  trusted comment (e.g. the release version) cannot be forged.
• Verify(pub PublicKey, message []byte, sig Signature) error for in-memory data,
  and VerifyFile(pub, path, sigPath) for a file on disk. Every failure is a
  distinct, wrapped, human-readable error (bad key id, signature mismatch,
  malformed .minisig, …) — never a bare false.

The primitive is pure and has no I/O beyond reading the named files, so it is
exhaustively unit-tested against real minisign vectors (a key + a signed file
generated by the minisign tool, checked into the test as fixtures), and against
tampered variants that must each fail.

Verified reference-data downloads (internal/verifydl)

A thin download helper wraps the refreshers' existing HTTP fetch:

Download(ctx, url, Verify{ SHA256Hex: "…" | SHA256URL: "…", Minisign: {SigURL, PubKey} }) ([]byte, error)

• Checksum mode. Compares the SHA-256 of the body against a pinned hex digest,
  or one fetched from a sidecar URL (<url>.sha256). (sbin Retire per-bridge cross-mode surface; close YSF parity gap G1 #60's MD5 request,
  modernized — MD5 is broken; SHA-256 is the floor.)
• Signature mode. Fetches <url>.minisig and verifies it against a trusted
  minisign public key via internal/minisign.
• On failure, Download returns a typed error and no body, so the caller
  keeps its previous cache — a tampered or corrupt download can never replace good
  data. The error names the URL and the reason.

Verification is opt-in per source, because the community hostfile mirrors do
not publish sums/signatures today: a refresher fetches plain (as now) unless a
checksum/signature source and — for signatures — a trusted key is configured,
in which case verification is mandatory for that source and a failure rejects
the download. This ships the mechanism without breaking today's unsigned upstreams,
and lights up fully the moment Waypoint hosts signed mirrors of the reference data
(the natural home for signed lists, and the fix for the "mirror unreachable" case a
Waypoint mirror also addresses). A -require-signed-hostfiles global switch (off by
default) makes verification mandatory for every source for an operator who runs
only signed mirrors.

The refreshers (dmrhosts, dmrtg, and the reflector lists) gain an optional
verification config threaded through their Fetch/Run; this RFC wires
dmrhosts and dmrtg as the pattern, and the reflector refreshers adopt the same
helper as a mechanical follow-up.

Signed releases

Release artifacts (the waypointd binary per arch, and the eventual image/.deb)
are signed at build time and verified before they are applied:

• Signing happens in CI: the release workflow runs minisign -S over each
  artifact with the Waypoint release key, whose secret half lives only as a CI
  secret (never in the repo), emitting a <artifact>.minisig alongside each file.
  The trusted comment carries the version/commit so it is bound into the signature.
• The trusted public key is committed (docs/waypoint-release.pub) and bundled
  so any client can verify a release offline, and is also settable via
  -release-pubkey for an operator running their own build channel.
• Verification before applying is the atomic-updater's job (Atomic updates with rollback — an update completes or the old version boots #13): it calls
  internal/minisign.VerifyFile(releasePub, artifact, artifact+".minisig") and
  refuses to switch unless it passes — the "updater verifies before applying"
  half of Signed releases; checksummed hostfile/ID database downloads #12. Because the updater lands in Atomic updates with rollback — an update completes or the old version boots #13, this RFC delivers the primitive,
  the signing pipeline, and the trusted key; Atomic updates with rollback — an update completes or the old version boots #13 wires the pre-apply gate onto them.
  Until then the acceptance is demonstrable directly: verifying a signed artifact
  passes and a byte-flipped one is rejected with a clear error (a unit test, and a
  waypointd -verify <file> <sig> maintenance flag operators/scripts can call).

Key management is an operator/maintainer concern, documented in docs/signing.md:
generating the release keypair, storing the secret key as a CI secret, and how a
downstream re-builder swaps in their own key.

The contract (test harness)

Automated (Go):

1. minisign vectors. A real minisign public key + a file signed by the
   minisign tool verify; the same file with one byte flipped, a wrong key id, a
   truncated .minisig, and a forged trusted comment each fail with their distinct
   error. Both Ed (legacy) and ED (prehashed BLAKE2b) modes covered.
2. Verified download — checksum. A body matching the pinned/sidecar SHA-256 is
   returned; a tampered body is rejected with a clear error and no bytes.
3. Verified download — signature. A body with a valid .minisig is returned; a
   tampered body (sig no longer matches) is rejected; a missing sidecar when
   verification is required is rejected.
4. Refresher integration. With verification configured, dmrhosts/dmrtg
Fetch writes the cache only on a verified download and leaves the prior cache
   intact on a verification failure (mirrors the existing failure-safe fetch).
5. Artifact rejection (the acceptance). VerifyFile accepts a correctly-signed
   artifact and rejects a byte-flipped one with a clear, wrapped error — the "a
   tampered artifact … is rejected with a clear error" acceptance, as a test.

Alternatives considered

• Sigstore / cosign. Rejected for an appliance: keyless signing needs OIDC and a
  transparency log at verify time, and a Pi may be offline. minisign's pinned key is
  simpler, offline-verifiable, and standard. (A Sigstore attestation in addition
  is a possible future for the public download surface.)
• TLS is enough. Rejected — it is the incumbent assumption. TLS authenticates
  the server, not the content: a compromised or malicious mirror serves signed-
  looking bytes over a valid cert. Provenance needs a signature over the artifact.
• MD5/SHA-1 checksums (as sbin Retire per-bridge cross-mode surface; close YSF parity gap G1 #60 literally asked). Rejected as the algorithm —
  both are broken for tamper resistance. SHA-256 for checksums, Ed25519 for
  signatures. A checksum alone (no signature) still only detects corruption, not a
  malicious swap where the attacker controls the checksum too; signatures are the
  real protection, checksums the cheap floor for sources that only publish sums.
• Verify-if-present (opportunistic). Rejected as the guarantee — an attacker
  strips the sidecar. Verification is opt-in per source, but once opted in it is
  mandatory (a missing/failing signature is a rejection), and -require-signed- hostfiles makes it fleet-wide.

Open questions

1. Signed reference-data mirror. Verification is opt-in until there is a source
   that signs. Waypoint hosting signed mirrors of the host/TG/ID lists (re-published
   from upstream with a Waypoint signature) both enables mandatory verification and
   fixes the reachability gap a review already found. Scope of that mirror
   (which lists, refresh cadence) is its own small design.
2. DMR ID database (DMRIds.dat). MMDVM-Host consumes a callsign↔ID database
   Waypoint does not yet refresh; adding a verified refresher for it is the direct
   sbin Retire per-bridge cross-mode surface; close YSF parity gap G1 #60 ask and a natural extension of verifydl. Deferred to when the ID DB
   refresher lands.
3. Key rotation / multiple trusted keys. One bundled release key today. Support
   for a small set of trusted keys (rotation, a backup signer) is a config-shape
   question deferred until a rotation is actually needed.
4. Full updater gate. The pre-apply verification is wired by Atomic updates with rollback — an update completes or the old version boots #13's atomic
   updater; this RFC intentionally stops at the primitive + signing + trusted key so
   Atomic updates with rollback — an update completes or the old version boots #13 has a verified foundation to build the switch-or-rollback on.

---

Migrated from docs/rfcs/0013-signed-releases-verified-downloads.md; the drafting history is in the git log.

[kn4oqw-clint]

This has already been implemented.