docs: which key signs each layer artifact, after decision 0055 #151

Open

marcos-mendez wants to merge 1 commit from docs/signing-roles-0055 into main

marcos-mendez commented

2026-10-14 15:03:00 -03:00

(Migrated from github.com)

Step 5 of the work for handbook decision 0055. Do not merge. This is for review.

What I found

Artifact	Signer today	Code	Verifier today
layer `<tarball>.hash`	nobody	`apt lib/release.sh` `release_build_env` clears `BT_GPGKEY`; a release publishes `.sha256`, not `.hash`	`keel verify` reports "not verified"
release `MANIFEST.asc`	main, subkey `03041024F4B2C0C2F42DDDEA04906EAB77513310`	`release_finish_manifest`, `release_sign`, key from `release_signing_subkey` (the `SignWith` of `trixie`)	no keel command; `keel-release` checks its own signature with the signing key
template `.sha512.asc`	main	`release_sign_one`	no verifier; keel-pve checks the sha512 from the signed index
`pve/aplinfo.dat.asc`	main	`release_sign_one`	keel-pve, `sqv --keyring keel-archive-keyring.gpg`; `keel-release` before it merges onto the live index (main, plus images after Keel-Linux/apt#28)
channel pointers	channel key = staging key `33516A960EC47DC1DB403ECC9DA966DE8C77FDE9`	`apt lib/channel.sh`, `KEEL_CHANNEL_KEY`	`keel pull --channel`, `KEYRING_DEFAULT` = `keel-channel-keyring.gpg`

The design call

keel pull verifies only the channel pointer. Decision 0055 section 8 keeps the channel key as the staging key. So the channel keyring does not get the images key. keel verify verifies no signature. So no keel command verifies an images-role artifact, and this pull request changes no code. It records the state in docs/layers.md. This is the least-power option: a new verification path for files that nobody signs or publishes would verify nothing.

The verifiers of images-role artifacts are outside keel: keel-pve (Keel-Linux/keel-pve#4) and the live index check of keel-release (Keel-Linux/apt#28). Both now also accept the images key.

The switch plan (not done)

Publish keel-archive-keyring 0.3.0 (Keel-Linux/keel-keys, merged). It installs keel-images-keyring.gpg.
Merge and publish keel-pve 0.1.2 (Keel-Linux/keel-pve#4).
Make keel-release sign MANIFEST, the .sha512 files and aplinfo.dat with main and images, in 1 .asc each. release_signature_current must then accept 2 signatures. sqv 1.3.0 with the main keyring alone accepts such a file (measured in keel-pve#4). Measure on a real Proxmox host before the release.
When every Proxmox host has keyring 0.3.0 and keel-pve 0.1.2, remove main from those signatures.
If .hash files are signed or a MANIFEST verifier is added, it must accept main and images, each from its own keyring file.

Step 5 of the work for handbook decision 0055. **Do not merge. This is for review.** ## What I found | Artifact | Signer today | Code | Verifier today | |---|---|---|---| | layer `<tarball>.hash` | nobody | `apt lib/release.sh` `release_build_env` clears `BT_GPGKEY`; a release publishes `.sha256`, not `.hash` | `keel verify` reports "not verified" | | release `MANIFEST.asc` | main, subkey `03041024F4B2C0C2F42DDDEA04906EAB77513310` | `release_finish_manifest`, `release_sign`, key from `release_signing_subkey` (the `SignWith` of `trixie`) | no keel command; `keel-release` checks its own signature with the signing key | | template `.sha512.asc` | main | `release_sign_one` | no verifier; keel-pve checks the sha512 from the signed index | | `pve/aplinfo.dat.asc` | main | `release_sign_one` | keel-pve, `sqv --keyring keel-archive-keyring.gpg`; `keel-release` before it merges onto the live index (main, plus images after Keel-Linux/apt#28) | | channel pointers | channel key = staging key `33516A960EC47DC1DB403ECC9DA966DE8C77FDE9` | `apt lib/channel.sh`, `KEEL_CHANNEL_KEY` | `keel pull --channel`, `KEYRING_DEFAULT` = `keel-channel-keyring.gpg` | ## The design call `keel pull` verifies only the channel pointer. Decision 0055 section 8 keeps the channel key as the staging key. So the channel keyring does **not** get the images key. `keel verify` verifies no signature. So no keel command verifies an images-role artifact, and this pull request changes no code. It records the state in `docs/layers.md`. This is the least-power option: a new verification path for files that nobody signs or publishes would verify nothing. The verifiers of images-role artifacts are outside keel: keel-pve (Keel-Linux/keel-pve#4) and the live index check of `keel-release` (Keel-Linux/apt#28). Both now also accept the images key. ## The switch plan (not done) 1. Publish `keel-archive-keyring` 0.3.0 (Keel-Linux/keel-keys, merged). It installs `keel-images-keyring.gpg`. 2. Merge and publish keel-pve 0.1.2 (Keel-Linux/keel-pve#4). 3. Make `keel-release` sign `MANIFEST`, the `.sha512` files and `aplinfo.dat` with main **and** images, in 1 `.asc` each. `release_signature_current` must then accept 2 signatures. sqv 1.3.0 with the main keyring alone accepts such a file (measured in keel-pve#4). Measure on a real Proxmox host before the release. 4. When every Proxmox host has keyring 0.3.0 and keel-pve 0.1.2, remove main from those signatures. 5. If `.hash` files are signed or a `MANIFEST` verifier is added, it must accept main and images, each from its own keyring file.