Verified updates
What a TAPPaaS site checks before it runs new code, how to see the result, and what to do when an update is refused. How releases are signed, and how to sign a repository of your own, is in SIGNING.md.
What the site checks
| What | When | What is checked |
|---|---|---|
Each repository the site tracks (site-manager repository list) on a staging or stable branch |
every update, after the fetch and before the checkout moves | the new tip is a release tag signed by a key the last release this site verified lists — or a key a later release enrolled, signed in turn by a trusted key — the files match the hash in the tag, and it is not older than what the site runs |
| The TAPPaaS install | when the mothership is installed | the release cloned is signed by one of the published release keys (Appendix E) |
| VM images (NixOS template, OPNsense) | before a downloaded image is imported | its SHA-256 matches the one in the release, which the release signers signed |
| Proxmox install media | when the install USB is made | the ISO against Proxmox's published SHA-256 list |
| NixOS guest systems | every guest update | the system is signed by the mothership's own Nix key, or comes from cache.nixos.org |
| Debian, Proxmox and OPNsense packages | every update | the distributions' own signed repositories, as before |
A repository on main, or on any branch its channels.json does not list for staging or
production, is not checked: it is the development line.
When a check fails, that repository is not updated: the site stays on the last release it verified, the update reports the repository as not synced, and says why. Nothing from the refused release has run.
Reading the result
After every repository update the site records what each repository runs:
health-manager validate # the signature-status line, with a row for anything to look at
site-manager site show # each repository with its status, e.g. TAPPaaS@stable [verified v2.4]
cat ~/config/sbom/signatures.json
| Status | Meaning | validate |
|---|---|---|
verified |
runs exactly a signed release (named, with its signer) | pass |
unsigned-unstable |
on main or another development branch |
not counted |
unsigned-declared |
the repository signs no releases | WARN — FAIL with requireSigned |
ahead-of-release |
runs commits past its last verified release, or has uncommitted changes | WARN |
failed |
on staging/stable, but what it runs is not a verified release |
FAIL |
| key expiring | a signing key the repository lists expires within 60 days | WARN |
The site owner is mailed when a repository's status changes — not on every update.
~/config/sbom/signatures.json is the record to show an auditor: for each repository its branch,
the release it runs, who signed it, and when it was checked. The last verified release of each
repository is kept in ~/config/.trust/<repository>.json.
Requiring signed releases
By default a repository that signs nothing still updates, and is shown as unsigned. A site that must show that everything it runs comes from signed releases turns that into a refusal:
site-manager site modify --requireSigned true
A repository that does list signing keys is always checked, whatever this says. Development branches are never affected.
Adding a repository
On a staging or stable branch, site-manager repository add needs the fingerprints of the keys
the repository's owners sign with — from them, by mail, their website or in person, never from the
repository itself. Give each one with --signer:
site-manager repository add <url> --branch stable --signer SHA256:<fingerprint> --signer SHA256:<fingerprint>
The branch's current release must be signed by one of them; no version number is needed. It shows
the fingerprints, checks the clone, refuses on a mismatch, and records them in site.json. A
repository that signs nothing is added with --unsigned:
site-manager repository add <url> --branch stable --unsigned
On main neither is needed; fingerprints given there must be among the keys the repository lists.
When an update is refused
The update log names the repository and the reason, for example:
TAPPaaS: REFUSED — 3f2a91c on 'stable' (production) is not a verified release
v2.5: Signature verification failed: ... No principal matched
| Reason | What it means | What to do |
|---|---|---|
is not a release tag |
the branch tip is not exactly a release | wait for the release; the branch was moved without one |
No principal matched / no valid signature |
signed by a key the last release does not list, lists as expired today, or has revoked | do not override; ask the repository's owners — this is the case the check exists for |
tree-sha256 mismatch |
the files do not match what was signed | do not override; report it |
does not descend from the last verified release |
the branch was moved back to an older release | ask the repository's owners; an update never goes back on its own — going back is a deliberate operator act, not a fetch result |
the site requires signed releases |
requireSigned is on and the repository signs nothing |
ask its owner to sign, or accept it knowingly with --requireSigned false |
The site keeps running the last verified release meanwhile.
Confirming or renewing a repository's signers
To check that the keys a site trusts for a repository are its owners' keys — or, after the owners have replaced their keys, to start from the new ones — give the fingerprints the owners publish:
site-manager repository introduce <name> --signer SHA256:<fingerprint> --signer SHA256:<fingerprint>
The current release must be signed by one of them. They are then written to site.json, and the
release is recorded as the one the next update starts from. Without --signer the command checks
the checkout against the fingerprints already in site.json.
Sites that predate signing
A site already on staging or stable before a repository starts signing keeps updating with
nothing to do. The release that adds the repository's first keys arrives like any unsigned update;
from the release after it, every update must be signed by a key it lists. Those keys arrived the
way every update did before signing, so run repository introduce with the published fingerprints
once to confirm them.
Checking a download by hand
ssh-keygen -Y verify -f .tappaas/allowed_signers -I lars@tappaas.org -n tappaas-image \
-s SHA256SUMS.sig < SHA256SUMS && sha256sum -c SHA256SUMS
.tappaas/allowed_signers comes from a TAPPaaS checkout; compare its fingerprints with
Appendix E and tappaas.org.