Skip to content

Commit eba481e

Browse files
committed
docs: add instructions how to sign a LND release.
1 parent f5f52a6 commit eba481e

File tree

1 file changed

+70
-0
lines changed

1 file changed

+70
-0
lines changed

docs/signing_release_candidate.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Signing a LND Release
2+
3+
When a new version of LND is released, binaries for the lnd and lncli programs
4+
are provided for various platforms and CPU architectures. The hashes of all
5+
these binaries are written into a file known as the "Manifest". This Manifest is
6+
then signed by a quorum of trusted LND contributors (see [verify-install.sh](/scripts/verify-install.sh)
7+
script for more details), ensuring that users can trust the binaries they
8+
download, knowing they haven't been modified during the automated build process.
9+
10+
To verify a release binary, users have two options:
11+
12+
* Manual Verification: Users can manually download the signature files and
13+
Manifest from GitHub LND release page, then verify the PGP signatures and
14+
hashes.
15+
16+
* Automated Verification: The LND repository provides a script,
17+
[verify-install.sh](/scripts/verify-install.sh), that automates the verification process. This script uses a
18+
set of trusted developer keys (located in the repo under [scripts/keys/](/scripts/keys)) and
19+
downloads the necessary data from the GitHub server to verify the integrity of
20+
the local lnd/lncli binaries.
21+
22+
Running [verify-install.sh](/scripts/verify-install.sh) validates that trusted developers attest to the authenticity between the lnd release binaries hosted on Github and the developer's local builds.
23+
24+
## Adding a new developer as a signer
25+
26+
When another developer is added to the trusted group of people which are
27+
allowed to sign the lnd/lncli releases, their public PGP key needs to be added to
28+
the LND repo. These keys are added in a PR in which 2 reviewers ensure the developer
29+
is in possession of the PGP key which will be added to the LND repo.
30+
(See https://github.com/lightningnetwork/lnd/pull/8788 as an example).
31+
It is important that the name of the PGP key equals the name in the
32+
[verify-install.sh](/scripts/verify-install.sh) script. See also [scripts/keys/README.md](/scripts/keys/README.md) for more information.
33+
34+
## Signing a release binary package
35+
36+
If the new developer's PGP key has been successfully added to the LND repository,
37+
through the aforementioned PR example, they are now able to provide their
38+
signature for the new release's "Manifest" file. To do so, the developer must
39+
follow these steps:
40+
41+
* Follow the build instructions at https://github.com/lightningnetwork/lnd/blob/masterdocs/release.md#building-a-new-release.
42+
43+
* After a successful build, all binaries and Manifest files, will be placed
44+
in a directory, named after the tag, created within the directory in which the build occurred. For
45+
instance, in the case mentioned above, the folder will be named
46+
`lnd-v0.18.3-beta`.
47+
Ensure that the SHA-256 hashes, in your locally-generated Manifest file, match
48+
those in the Manifest file of the official release on the LND GitHub repository.
49+
Tip: Download the official release Manifest file to your local maschine and do:
50+
`diff lnd-v0.18.3-beta/manifest-v0.18.3-beta.txt ~/Downloads/manifest-v0.18.3-beta.txt`
51+
(example command for a release candidate called `v0.18.3-beta`)
52+
Only if all hashes are identical, should you sign the release. If the digests
53+
match, see the example signing comand, assuming your PGP signing key is
54+
available on your local device:
55+
`gpg --local-user $KEYID --detach-sig --output manifest-$USERNAME-v0.18.3-beta.sig manifest-v0.18.3-beta.txt`.
56+
`USERNAME` being the name in the `[verify-install.sh](../scripts/verify-install.sh)`
57+
script and also the name of your PGP key file. The whole argument `--local-user $KEYID`
58+
is only needed if there's more than one signing key on your local machine. Be
59+
sure to substitute the TAG value `v0.18.3-beta` with the version you are
60+
currently signing.
61+
62+
* Finally, upload the signature file
63+
(e.g. manifest-USERNAME-v0.18.3-beta.sig) to the GitHub release page.
64+
Github write permissions are required to upload signatures to the LND release
65+
page. To avoid interfering with other signers who may be updating the GitHub
66+
release page, LND developers use a `KeyBase` communication channel to signal
67+
when an edit is in progress. Once your signature file is successfully uploaded
68+
and the release page is unlocked, the signing process is complete.
69+
70+
Congratulations signing the LND release 🎉.

0 commit comments

Comments
 (0)