Merge pull request lightningnetwork#3588 from wpaulino/verify-release…

…-guide

build: expand reproducible build system with build and verification steps

build/release/README.md

@@ -1,34 +1,71 @@
-# lnd's Reproducible Build System
+# `lnd`'s Reproducible Build System
 
-This package contains the buidl script that the `lnd` project uses in order to
-build binaries for each new release. As of Go 1.13, with some new build flags,
+This package contains the build script that the `lnd` project uses in order to
+build binaries for each new release. As of `go1.13`, with some new build flags,
 binaries are now reproducible, allowing developers to build the binary on
-distinct machines, and end up with a byte-for-byte identical binary.  However,
-this wasn't _fully_ solved in Go 1.13, as the build system still includes the
+distinct machines, and end up with a byte-for-byte identical binary. However,
+this wasn't _fully_ solved in `go1.13`, as the build system still includes the
 directory the binary is built into the binary itself. As a result, our scripts
-utilize a work around needed until Go 1.13.2.  
+utilize a work around needed until `go1.13.2`.  
 
 ## Building a New Release
 
-### MacOS/Linux/Windows (WSL)
+### macOS/Linux/Windows (WSL)
 
-No prior set up is needed on Linux or MacOS is required in order to build the
-release binaries.  However, on Windows, the only way to build the binaries atm
-is using the Windows Subsystem Linux. One can build the release binaries from
-one's `lnd` directory, no matter where it's located.  One can download `lnd` to
+No prior set up is needed on Linux or macOS is required in order to build the
+release binaries. However, on Windows, the only way to build the release
+binaries at the moment is by using the Windows Subsystem Linux. One can build
+the release binaries following these steps:
 
-```
-git clone https://github.com/lightningnetwork/lnd.git
-```
+1. `git clone https://github.com/lightningnetwork/lnd.git`
+2. `cd lnd`
+3. `./build/release/release.sh <TAG> # <TAG> is the name of the next
+   release/tag`
 
-Afterwards, the release manager/verifier simply needs to run:
-`./build/release/release.sh <TAG>` (from the top-level `lnd` directory) , where
-`<TAG>` is the name of the next release/tag.
+This will then create a directory of the form `lnd-<TAG>` containing archives
+of the release binaries for each supported operating system and architecture,
+and a manifest file containing the hash of each archive.
 
 ## Verifying a Release
 
-With Go 1.13, it's now possible for third parties to verify a release binary.
-Before this release, one had to trust that release manager to build the proper
-binary. With this new system, third parties can now _independently_ run the
-release process, and verify that all the hashes in the final `manifest.txt`
-match up.
+With `go1.13`, it's now possible for third parties to verify release binaries.
+Before this version of `go`, one had to trust the release manager(s) to build the
+proper binary. With this new system, third parties can now _independently_ run
+the release process, and verify that all the hashes of the release binaries
+match exactly that of the release binaries produced by said third parties.
+
+To verify a release, one must obtain the following tools (many of these come
+installed by default in most Unix systems): `gpg`/`gpg2`, `shashum`, and
+`tar`/`unzip`.
+
+Once done, verifiers can proceed with the following steps:
+
+1. Acquire the archive containing the release binaries for one's specific
+   operating system and architecture, and the manifest file along with its
+   signature.
+2. Verify the signature of the manifest file with `gpg --verify
+   manifest-<TAG>.txt.sig`. This will require obtaining the PGP keys which
+   signed the manifest file, which are included in the release notes.
+3. Recompute the `SHA256` hash of the archive with `shasum -a 256 <filename>`,
+   locate the corresponding one in the manifest file, and ensure they match
+   __exactly__.
+
+At this point, verifiers can use the release binaries acquired if they trust
+the integrity of the release manager(s). Otherwise, one can proceed with the
+guide to verify the release binaries were built properly by obtaining `shasum`
+and `go` (matching the same version used in the release):
+
+4. Extract the release binaries contained within the archive, compute their
+   hashes as done above, and note them down.
+5. Ensure `go` is installed, matching the same version as noted in the release
+   notes. 
+6. Obtain a copy of `lnd`'s source code with `git clone
+   https://github.com/lightningnetwork/lnd` and checkout the source code of the
+   release with `git checkout <TAG>`.
+7. Proceed to verify the tag with `git verify-tag <TAG>` and compile the
+   binaries from source for the intended operating system and architecture with
+   `LNDBUILDSYS=OS-ARCH ./build/release/release.sh <TAG>`.
+8. Extract the archive found in the `lnd-<TAG>` directory created by the
+   release script and recompute the `SHA256` hash of the release binaries (lnd
+   and lncli) with `shasum -a 256 <filename>`. These should match __exactly__
+   as the ones noted above.