Sign the app update feed with Ed25519 and verify it in the app

Each installation generates a private Ed25519 key once (0600, under
~/.config/pipelines), signs version.json with a detached version.json.sig
when publishing APK and desktop builds, and embeds its own and listed
trusted public keys in app builds. The app verifies the feed signature
before trusting the artifact sha256, refuses unsigned or foreign feeds when
it has keys, and requires the sha256 and Android signer in signed feeds.
This commit is contained in:
2026-11-10 00:51:16 +00:00
parent a706739088
commit 9f38e38f6a
17 changed files with 1010 additions and 26 deletions
+121
View File
@@ -0,0 +1,121 @@
# Network defaults and update-feed signing
## Update feed signing
Before this change the app trusted whatever `/updates/` served: the Linux
self-update installed and relaunched an archive whose sha256 came from the same
`version.json`, Android skipped its signer check when the feed omitted the
field, and the macOS zip had no check beyond that sha256. A server (or anyone
able to write its update directory, or answer for its address) could hand every
client another build.
### What is signed
- Publishing (`./install --apk`, `./install --linux|--macos --publish`) writes
`version.json` and, beside it, a detached `version.json.sig`:
`{"algorithm":"ed25519","publicKey":"<base64 32 bytes>","signature":"<base64 64 bytes>"}`.
The signature covers the exact bytes of `version.json`, which carry the
artifact `sha256` (and, for Android, `signingCertificateSha256`). The
signature is written first, then the feed, both atomically; a check racing a
publish fails once and succeeds on the next check.
- Code: `scripts/update_signing.py` (keys, signing, `publish_feed`),
`scripts/app_build.py` (`build_apk`, web and desktop defines),
`scripts/app_desktop_build.py` (`publish_desktop(..., signer=...)`).
### Key management
- Each installation has one Ed25519 key in
`~/.config/pipelines/update-signing-key.pem` (mode 0600, directory 0700),
generated once on the first `./install` or app build/publish and never
replaced. `PIPELINES_UPDATE_SIGNING_KEY` names another path. A key file that
is a symlink or readable by others is refused. It is never in the repository.
`scripts/uninstall.py` (full reset) removes `~/.config/pipelines`, and so
the key; see "Lost or replaced key" below.
- Cryptography is the OpenSSL 3 command line (`genpkey`, `pkey`,
`pkeyutl -sign -rawin`). The installer's Python has no `cryptography`
package, and macOS's `/usr/bin/openssl` is LibreSSL 3.3.6, which has no
Ed25519 (`unable to load Private Key`). The tool is chosen as
`PIPELINES_OPENSSL`, then `/opt/homebrew/opt/openssl@3/bin/openssl`,
`/usr/local/opt/openssl@3/bin/openssl`, then `openssl` on PATH, taking the
first that can generate an Ed25519 key. Without one the install stops with
`Update signing needs OpenSSL 3 with Ed25519 ...` (`brew install openssl@3`).
On this Mac `openssl` on PATH is Homebrew OpenSSL 3.6.4.
- Print this installation's public key:
`python3 scripts/update_signing.py`.
### Trust model
- Every app build embeds the keys it trusts as
`--dart-define=PIPELINES_UPDATE_PUBLIC_KEY=<key>[,<key>...]` (apk, linux,
macos and web builds; the define is part of the build cache key, so a key
change rebuilds). The list is this installation's own key first, then each
base64 key in `~/.config/pipelines/update-trusted-keys` (one per line, `#`
comments allowed; a malformed line stops the build).
- Each server signs its own feed with its own key. A client accepts a feed
only when `version.json.sig` names an embedded key and the signature over
the served bytes verifies with it; the client checks the signature before it
believes anything in the feed. So an app built on the Mac updates from tank
only if tank's key was listed in the Mac's `update-trusted-keys` when that
app was built (and vice versa). There is no trust-on-first-use pinning:
trust comes only from the build, which keeps the model to one rule.
- With keys embedded, the app refuses: an unsigned feed (no `.sig`), an
unreadable signature, a key it does not embed, a bad signature, a feed
without `sha256`, and an Android feed without `signingCertificateSha256`
(or when the installed signature is unknown). The Android certificate must
still match the installed app's, as before.
- A build with no embedded key (a developer `flutter run`/`flutter build`
outside the installer) keeps the previous unsigned behaviour. Installer
builds always embed a key.
- Verification in the app is pure Dart (`app/lib/features/updates/ed25519.dart`,
RFC 8032 verify only, BigInt arithmetic, checked against RFC 8032 test
vectors 1-3; no new package) and
`app/lib/features/updates/update_feed_signature.dart`; the reader is
`fetchLatestScoped` in `app_updates_io.dart`. The web Settings "Android
download" link is a browser download the operator installs by hand and is
unchanged.
### Migration (the live Mac install and tank)
Not done by this change; nothing was deployed. In order, on each machine:
1. `./install` (or the next `./install --apk` / desktop publish) generates
`~/.config/pipelines/update-signing-key.pem`. Check:
`ls -l ~/.config/pipelines/update-signing-key.pem` shows `-rw-------`.
2. To let one machine's apps update from the other, exchange keys before
building: on tank run `python3 scripts/update_signing.py` and append the
line to the Mac's `~/.config/pipelines/update-trusted-keys`; do the
reverse on tank. Skip this if each machine's apps only update from it.
3. Rebuild and publish: `./install --apk`, `./install --macos --publish
--flutter <flutter>`, `./install --linux --publish`. Each feed directory
then holds `version.json.sig`.
4. Installed apps from before this change do not check signatures; they take
the next signed release normally (the `.sig` is ignored), and from then on
they refuse unsigned or foreign feeds. Phones whose feed came from the other
machine need step 2 before step 3.
5. Lost or replaced key (for example after a full uninstall): apps built with
the old key refuse the new feeds. Install the new build once by hand (APK
download from Settings in the browser, or the desktop archive), or restore
the old key file from backup.
### Verification output
- `cd scripts && python3 -m unittest test_update_signing test_app_build
test_app_desktop_build test_setup_native`: `Ran 81 tests ... OK`. Covers key
generation once at 0600 in a scratch HOME, refusal of readable/symlinked
keys, LibreSSL-style tools skipped, signatures checked independently with
`openssl pkeyutl -verify` (and a tampered message refused), feed plus `.sig`
publication, trusted-key list parsing, APK publication signed with the
generated key, desktop publication passing the exact feed bytes to the
signer, and the committed Dart fixture being a valid OpenSSL signature.
- `cd app && tool/memwatch/full.sh 'test/features/updates test/features/settings'`:
`memwatch: PASS: 187 passed, 0 failed, 0 skipped`. New:
`test/features/updates/ed25519_test.dart` (RFC 8032 vectors; changed
message, signature, key; short inputs; S >= L; non-canonical key) and
`test/features/updates/update_feed_signature_test.dart` (the
Python-signed fixture `test/features/updates/fixtures/signed_feed/`
verifies; tampered feed and signature refused; missing signature refused
with keys, accepted without; untrusted and swapped keys refused; signed
feeds require sha256 and the Android signer; and the HTTP reader
`fetchLatestScoped` against a loopback server refuses an unsigned and a
tampered feed and lets the genuine one past the signature check).
`test/core/session`: `PASS: 18 passed`. `tool/analyze.sh`: `analyze: clean`.