From bd467c3e68a143fb8802bd7f353f3969757641d5 Mon Sep 17 00:00:00 2001 From: ffranr Date: Wed, 8 Nov 2023 14:23:49 +0000 Subject: [PATCH] docs: add reproducible release build guide --- docs/release.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/release.md diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 000000000..d45a78f10 --- /dev/null +++ b/docs/release.md @@ -0,0 +1,125 @@ +# `taproot-assets`'s Reproducible Build System + +This package contains the build script that the `taproot-assets` 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 `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 `go1.13.2`. + +## Building a New Release + +### MacOS + +The first requirement is to have [`docker`](https://www.docker.com/) +installed locally and running. The second requirement is to have `make` +installed. Everything else (including `golang`) is included in the release +helper image. + +To build a release, run the following commands: + +```shell +$ git clone https://github.com/lightninglabs/taproot-assets.git +$ cd taproot-assets +$ git checkout # is the name of the next release/tag +$ make docker-release tag= +``` + +Where `` is the name of the next release of `taproot-assets`. + +### 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 release +binaries at the moment is by using the Windows Subsystem Linux. One can build +the release binaries following these steps: + +```shell +$ git clone https://github.com/lightninglabs/taproot-assets.git +$ cd taproot-assets +$ git checkout # is the name of the next release/tag +$ make release tag= +``` + +This will then create a directory of the form `taproot-assets-` 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 `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-.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 `, + 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 `taproot-assets`'s source code with `git clone + https://github.com/lightninglabs/taproot-assets` and checkout the source code of the + release with `git checkout `. +7. Proceed to verify the tag with `git verify-tag ` and compile the + binaries from source for the intended operating system and architecture with + `make release sys=OS-ARCH tag=`. +8. Extract the archive found in the `taproot-assets-` directory created by + the release script and recompute the `SHA256` hash of the release binaries + (`tapd` and `tapcli`) with `shasum -a 256 `. These should match + __exactly__ as the ones noted above. + +## Verifying Docker Images + +To verify the `tapd` and `tapcli` binaries inside the +[official provided docker images](https://hub.docker.com/r/lightninglabs/taproot-assets) +against the signed, reproducible release binaries, there is a verification +script in the image that can be called (before starting the container for +example): + +```shell +$ docker run --rm --entrypoint="" lightninglabs/taproot-assets:v0.3.0 /verify-install.sh v0.3.0 +$ OK=$? +$ if [ "$OK" -ne "0" ]; then echo "Verification failed!"; exit 1; done +$ docker run lightninglabs/taproot-assets [command-line options] +``` + +# Signing an Existing Manifest File + +If you're a developer of `taproot-assets` and are interested in attaching your +signature to the final release archive, the manifest MUST be signed in a manner +that allows your signature to be verified by our verify script +`scripts/verify-install.sh`. + +Assuming you've done a local build for _all_ release targets, then you should +have a file called `manifest-TAG.txt` where `TAG` is the actual release tag +description being signed. The release script expects a particular file name for +each included signature, so we'll need to modify the name of our output +signature during signing. + +Assuming `USERNAME` is your current nick as a developer, then the following +command will generate a proper signature: +```shell +$ gpg --detach-sig --output manifest-USERNAME-TAG.sig manifest-TAG.txt +```