upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/docs/release-verification.md
diff options
context:
space:
mode:
authorBitflash <admin@bitflash.network>2026-08-06 10:46:26 -0300
committerBitflash <admin@bitflash.network>2026-08-06 10:46:26 -0300
commitc3f6b68f907b03865d2c417ee39fe9526787196f (patch)
tree98a7c58fdf511d3cf98aae0811913afa51cd0c24 /docs/release-verification.md
parentb3a5a858e536acf65e6c6761293626628f2227bf (diff)
release: sign SHA256SUMS with a pinned key, verify against it
verify-release.sh embeds the Bitflash release signing key and now requires that the checksum signature validate against that exact key, not merely against some key in the caller's keyring (#138). It also fetches releases from releases.bitflash.network instead of the retired GitHub host, resolving 'latest' from latest.txt. Release signing key fingerprint: 910A 2B4C CA87 9E81 FB4B 2AEA 1D4A 53D3 B78A A4B8
Diffstat (limited to 'docs/release-verification.md')
-rw-r--r--docs/release-verification.md78
1 files changed, 50 insertions, 28 deletions
diff --git a/docs/release-verification.md b/docs/release-verification.md
index ecacd5f..32de74f 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -3,60 +3,82 @@
3Bitflash releases publish binaries and a `SHA256SUMS` file. The checksum file 3Bitflash releases publish binaries and a `SHA256SUMS` file. The checksum file
4proves that the file you downloaded matches the file the release page names. 4proves that the file you downloaded matches the file the release page names.
5A detached signature, `SHA256SUMS.asc`, proves that the checksum file itself was 5A detached signature, `SHA256SUMS.asc`, proves that the checksum file itself was
6signed by a trusted release key. 6signed by the Bitflash release key.
7 7
8That gives users two separate checks: 8That gives users two separate checks:
9 9
101. `gpg --verify SHA256SUMS.asc SHA256SUMS` checks who signed the checksums. 101. `gpg --verify SHA256SUMS.asc SHA256SUMS` — who signed the checksums.
112. `sha256sum -c SHA256SUMS` checks the binaries against those checksums. 112. `sha256sum -c SHA256SUMS` — the binaries against those checksums.
12 12
13## User Check 13But the first check is only worth something if you require a **specific** key.
14A good signature by *some* key proves nothing; anyone can make one.
14 15
15From a shell with `curl` or `wget` and `sha256sum`: 16## The release signing key
16 17
17```bash 18```text
18scripts/verify-release.sh latest 19fingerprint 910A 2B4C CA87 9E81 FB4B 2AEA 1D4A 53D3 B78A A4B8
20uid Bitflash Releases (bitflash.network release signing)
21 <releases@bitflash.network>
19``` 22```
20 23
21For a specific release: 24The public key is published at
25`https://releases.bitflash.network/bitflash-release-key.asc` and embedded in
26`scripts/verify-release.sh`, so the tool's trust anchor lives in this
27repository rather than on the server it verifies.
28
29## User check
30
31From a shell with `curl` or `wget`, `sha256sum` and `gpg`:
22 32
23```bash 33```bash
24scripts/verify-release.sh v1.2.13 34scripts/verify-release.sh latest
25``` 35```
26 36
27For release audits, require the signature: 37For a specific release:
28 38
29```bash 39```bash
30scripts/verify-release.sh v1.2.13 --require-signature 40scripts/verify-release.sh v1.2.15
31``` 41```
32 42
33Older releases may not have `SHA256SUMS.asc`. In that case the script warns and 43The script downloads the release, imports the pinned key into a throwaway
34still checks file integrity. New release audits should use `--require-signature`. 44keyring, and **refuses anything that is not a valid signature by the key above**
35 45before checking the hashes. Releases from before signing was introduced ship
36## Maintainer Flow 46only `SHA256SUMS`; without `--require-signature` those are checked for integrity
47and reported as unsigned.
37 48
38After building release assets in the repository root: 49By hand, if you would rather not run the script:
39 50
40```bash 51```bash
41scripts/make-release-checksums.sh --sign --local-user RELEASE_KEY_ID 52curl -O https://releases.bitflash.network/bitflash-release-key.asc
53gpg --import bitflash-release-key.asc
54gpg --verify SHA256SUMS.asc SHA256SUMS # must name the fingerprint above
55sha256sum -c SHA256SUMS
42``` 56```
43 57
44Upload all built assets plus: 58## Maintainer flow
45 59
46```text 60The signing key lives on a dedicated location, not in the build tree. After
47SHA256SUMS 61building the release assets in the repository root, write and sign the
48SHA256SUMS.asc 62checksums:
63
64```bash
65sha256sum Bitflash-*.zip Bitflash-*.AppImage bitflash-node-* > SHA256SUMS
66gpg --armor --detach-sign --output SHA256SUMS.asc SHA256SUMS
49``` 67```
50 68
51Keep the private signing key offline or on a dedicated release machine. Publish 69Publish, alongside the assets, `SHA256SUMS` and `SHA256SUMS.asc`, and update
52the public key fingerprint in the release notes and keep using the same key for 70`latest.txt` on the releases host to the new tag. Keep using the same key; if it
53future releases unless there is a clearly announced rotation. 71is ever rotated, announce the new fingerprint clearly and update the embedded
72key in `verify-release.sh`.
54 73
55## Why This Matters 74## Why this matters
56 75
57`SHA256SUMS` alone protects against a broken download, but not against someone 76`SHA256SUMS` alone protects against a broken download, but not against someone
58replacing both a binary and the checksum file. Signing `SHA256SUMS` means an 77replacing both a binary and the checksum file. Signing `SHA256SUMS`, and
59attacker must also have the release signing key to make the replacement verify. 78requiring a pinned key, means an attacker must also hold the release signing key
79to make the replacement verify. Serving from bitflash.network makes this the
80guarantee that matters: without a pinned key, "trust the site" is the only
81thing standing behind a download.
60 82
61This is not reproducible builds yet. It is the smaller, immediate step that 83This is not reproducible builds yet. It is the smaller, immediate step that
62makes every release asset auditable by users before they run it. 84makes every release asset auditable before anyone runs it.