Merge #803: Update binary verification instructions for multiple signers

ca85967 Don't duplicate builder GPG key in bin verify (James O'Beirne)
41ec90e Clean up obtain_release_key and add keys.txt link (James O'Beirne)
cdbe711 Add note about importance of binary verification (James O'Beirne)
ca4c331 Remove single release key (James O'Beirne)
5c57c61 Update binary verification instructions for multiple signers (James O'Beirne)

Pull request description:

  Fixes #793.

  This updates the binary verification instructions to account for the new process, which uses multiple builder signatures on the `SHA256SUMS` file. See bitcoin/bitcoin#22634 for more details.

  ![image](https://user-images.githubusercontent.com/73197/133864620-c6046d0e-34eb-448c-8769-2e22beb4563e.png)

  ### Possible follow-ups

  - [ ] include instructions on how to elevate GPG trust of imported public keys.
  - [ ] include a reference to bitcoin/bitcoin#23020, pending its merge.

ACKs for top commit:
  harding:
    Mostly tested ACK  ca85967 .  Built a preview, carefully read the instructions for all three platforms, and ran the Linux instructions.  Windows and MacOS instructions not tested, but the only real difference from the instructions I wrote and had reviewed originally is the filenames, so I'm confident in them.

Tree-SHA512: 7396660b7b70a91bf023b4fb6b1a0dec73da98081aa149fddea6ba79e450639e840144a8cf861264dbcf22ca39ee3e5253649fe8324e0bd34db5d6a3e16fdabe

Author: harding

_includes/templates/download.html

@@ -8,8 +8,23 @@
 {% assign magnet = VERSION_SORTED_RELEASES[0].optional_magnetlink %}
 {% capture PATH_PREFIX %}/bin/bitcoin-core-{{CURRENT_RELEASE}}{% endcapture %}
 {% capture FILE_PREFIX %}bitcoin-{{CURRENT_RELEASE}}{% endcapture %}
-{% assign SIGNING_KEY_FINGERPRINT = "01EA5486DE18A882D4C2684590C8019E36C2E964" %}
-{% capture SIGNING_KEY_FINGERPRINT_EXPLODED %}{% include fingerprint-split.html hex=SIGNING_KEY_FINGERPRINT %}{% endcapture %}
+{% assign builder_line_arr = page.example_builders_line | split: ' ' %}
+{% assign example_builder_key = builder_line_arr[0] %}
+{% capture SIGNING_KEY_FINGERPRINT_EXPLODED %}
+  {% include fingerprint-split.html hex=example_builder_key %}
+{% endcapture %}
+{% capture SHORT_BUILDER_KEY %}
+  {{example_builder_key | slice: 0, 4}}  {{ example_builder_key | slice: 4, 4 }}..
+.{% endcapture %}
+{% capture BUILDER_KEYS_TXT_URL %}{{page.builder_keys_url}}/keys.txt{% endcapture %}
+
+{% capture OBTAIN_RELEASE_KEY %}
+  {{page.obtain_release_key | 
+    replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url | 
+    replace: '$(EXAMPLE_BUILDERS_LINE)', page.example_builders_line | 
+    replace: '$(BUILDER_KEYS_TXT_URL)', BUILDER_KEYS_TXT_URL}}
+{% endcapture %}
+
 {% assign GPG_DOWNLOAD_URL = "https://www.gnupg.org/download/index.en.html#binary" %}
 {% assign GPG_MACOS_DOWNLOAD_URL = "https://gpgtools.org/" %}
 {% assign GPG_WINDOWS_DOWNLOAD_URL = "https://gpg4win.org/download.html" %}
@@ -69,15 +84,14 @@ <h2>{{ page.latestversion }} {{CURRENT_RELEASE}} <a type="application/rss+xml" h
       </div>
     </div>
     <p class="downloadmore">
-      <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc" class="dl">{{ page.downloadsig }}</a><br>
+      <a href="{{ PATH_PREFIX }}/SHA256SUMS" class="dl">{{ page.download_sha }}</a><br>
+      <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc" class="dl">{{ page.download_sig }}</a><br>
       <a href="{{ PATH_PREFIX }}/{{ FILE_PREFIX }}.torrent" class="dl">{{ page.downloadtorrent }}</a>
         {% if magnet %} <a href="{{ magnet | replace: '&', '\&amp;'}}" class="magnetlink" data-proofer-ignore></a>{% endif %}<br>
       <a href="{{ PATH_PREFIX }}/{{ FILE_PREFIX}}.tar.gz" class="dl">{{ page.source }}</a><br>
       <a href="/en/releases">{{ page.versionhistory }}</a>
     </p>
     <p class="downloadkeys">
-      <span>{{ page.releasekeys }}</span>
-      v0.11.0+ <code title="{{page.pgp_key_fingerprint}}">{{SIGNING_KEY_FINGERPRINT}}</code><br>
       {% if page.version > 2 %}<i>{{page.key_refresh}}</i><br><code>gpg{{site.strings.gpg_keyserver}} --refresh-keys</code>{% endif %}
     </p>
   </div>
@@ -87,6 +101,10 @@ <h2>{{ page.latestversion }} {{CURRENT_RELEASE}} <a type="application/rss+xml" h
   <h2 style="text-align: center">{{ page.patient }}</h2>
   <p>{{ page.notesync | replace: '$(DATADIR_SIZE)', site.data.stats.datadir_gb | replace: '$(PRUNED_SIZE)', site.data.stats.pruned_gb | replace: '$(MONTHLY_RANGE_GB)', site.data.stats.monthly_storage_increase_range_gb }} {{ page.full_node_guide }}</p>
 
+
+  <h2 style="text-align: center">{{ page.verify_title }}</h2>
+  <p>{{ page.verify_steps }}</p>
+
 {% if page.version > 4 %}
   <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.verify_download}}</h2>
   <p>{{page.verification_recommended}}</p>
@@ -96,7 +114,9 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
     <ol>
       <li><p>{{page.download_release}}</p></li>
 
-      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
+      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS">SHA256SUMS</a></p></li>
+
+      <li><p>{{page.download_checksums_sigs}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
 
       <li><p>{{page.cd_to_downloads}}</p>
 
@@ -111,19 +131,21 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
 
       <li><p>{{page.ensure_checksum_matches}}</p>
 
-        <pre class="highlight"><code>type SHA256SUMS.asc</code></pre></li>
+        <pre class="highlight"><code>type SHA256SUMS</code></pre></li>
 
       <li><p>{{page.install_gpg}} <a
       href="{{GPG_WINDOWS_DOWNLOAD_URL}}">{{page.gpg_download_page}}</a>
       {{page.gpg_download_other}}
       <a href="{{GPG_DOWNLOAD_URL}}">{{page.gpg_download_options}}</a></p></li>
 
-      <li><p>{{page.obtain_release_key}}</p>
+      <li><p>{{OBTAIN_RELEASE_KEY}}</p>
 
-        <pre class="highlight"><code>{{GPG}}{{site.strings.gpg_keyserver}} --recv-keys {{SIGNING_KEY_FINGERPRINT}}</code></pre>
+        <pre class="highlight"><code>{{GPG}}{{site.strings.gpg_keyserver}} --recv-keys {{example_builder_key}}</code></pre>
 
         <p>{{page.release_key_obtained}}</p></li>
 
+      <li><p>{{page.choosing_builders | replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url }}</p></li>
+
       <li>{{page.verify_checksums_file}}
 
         <pre class="highlight"><code>{{GPG}} --verify SHA256SUMS.asc</code></pre></li>
@@ -133,7 +155,7 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
           <li><p>{{page.complete_line_saying}} <code>{{page.localized_gpg_primary_fingerprint}} {{SIGNING_KEY_FINGERPRINT_EXPLODED}}</code></p></li>
         </ol>
 
-        <p>{{page.gpg_trust_warning}}</p></li>
+        <p>{{page.gpg_trust_warning | replace: '$(SHORT_BUILDER_KEY)', SHORT_BUILDER_KEY }}</p></li>
 
     </ol>
   </details>
@@ -143,7 +165,9 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
     <ol>
       <li><p>{{page.download_release}}</p></li>
 
-      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
+      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS">SHA256SUMS</a></p></li>
+
+      <li><p>{{page.download_checksums_sigs}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
 
       <li><p>{{page.cd_to_downloads}}</p>
 
@@ -153,7 +177,7 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
 
       <li><p>{{page.verify_download_checksum}}</p>
 
-        <pre class="highlight"><code>shasum -a 256 --check SHA256SUMS.asc</code></pre>
+        <pre class="highlight"><code>shasum -a 256 --check SHA256SUMS</code></pre>
 
         <p>{{page.checksum_warning_and_ok | replace, "$(SHASUMS_OK)", page.localized_checksum_ok}} <code>{{FILE_PREFIX}}{{site.data.binaries.macdmg}}: {{page.localized_checksum_ok}}</code></p></li>
 
@@ -162,12 +186,14 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
       {{page.gpg_download_other}}
       <a href="{{GPG_DOWNLOAD_URL}}">{{page.gpg_download_options}}</a></p></li>
 
-      <li><p>{{page.obtain_release_key}}</p>
+      <li><p>{{page.obtain_release_key | replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url | replace: '$(EXAMPLE_BUILDERS_LINE)', page.example_builders_line}}</p>
 
-        <pre class="highlight"><code>gpg{{site.strings.gpg_keyserver}} --recv-keys {{SIGNING_KEY_FINGERPRINT}}</code></pre>
+        <pre class="highlight"><code>gpg{{site.strings.gpg_keyserver}} --recv-keys {{example_builder_key}}</code></pre>
 
         <p>{{page.release_key_obtained}}</p></li>
 
+      <li><p>{{page.choosing_builders | replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url }}</p></li>
+
       <li>{{page.verify_checksums_file}}
 
         <pre class="highlight"><code>gpg --verify SHA256SUMS.asc</code></pre></li>
@@ -177,7 +203,7 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
           <li><p>{{page.complete_line_saying}} <code>{{page.localized_gpg_primary_fingerprint}} {{SIGNING_KEY_FINGERPRINT_EXPLODED}}</code></p></li>
         </ol>
 
-        <p>{{page.gpg_trust_warning}}</p></li>
+        <p>{{page.gpg_trust_warning | replace: '$(SHORT_BUILDER_KEY)', SHORT_BUILDER_KEY }}</p></li>
     </ol>
   </details>
 
@@ -186,7 +212,9 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
     <ol>
       <li><p>{{page.download_release}}</p></li>
 
-      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
+      <li><p>{{page.download_checksums}} <a href="{{ PATH_PREFIX }}/SHA256SUMS">SHA256SUMS</a></p></li>
+
+      <li><p>{{page.download_checksums_sigs}} <a href="{{ PATH_PREFIX }}/SHA256SUMS.asc">SHA256SUMS.asc</a></p></li>
 
       <li><p>{{page.cd_to_downloads}}</p>
 
@@ -196,16 +224,18 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
 
       <li><p>{{page.verify_download_checksum}}</p>
 
-        <pre class="highlight"><code>sha256sum --ignore-missing --check SHA256SUMS.asc</code></pre>
+        <pre class="highlight"><code>sha256sum --ignore-missing --check SHA256SUMS</code></pre>
 
         <p>{{page.checksum_warning_and_ok | replace, "$(SHASUMS_OK)", page.localized_checksum_ok}} <code>{{FILE_PREFIX}}-{{site.data.binaries.lin64}}: {{page.localized_checksum_ok}}</code></p></li>
 
-      <li><p>{{page.obtain_release_key}}</p>
+      <li><p>{{page.obtain_release_key | replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url | replace: '$(EXAMPLE_BUILDERS_LINE)', page.example_builders_line}}</p>
 
-        <pre class="highlight"><code>gpg{{site.strings.gpg_keyserver}} --recv-keys {{SIGNING_KEY_FINGERPRINT}}</code></pre>
+        <pre class="highlight"><code>gpg{{site.strings.gpg_keyserver}} --recv-keys {{example_builder_key}}</code></pre>
 
         <p>{{page.release_key_obtained}}</p></li>
 
+      <li><p>{{page.choosing_builders | replace: '$(BUILDER_KEYS_URL)', page.builder_keys_url }}</p></li>
+
       <li>{{page.verify_checksums_file}}
 
         <pre class="highlight"><code>gpg --verify SHA256SUMS.asc</code></pre></li>
@@ -215,7 +245,7 @@ <h2 style="text-align: center" id="{{page.verify_download | slugify}}">{{page.ve
           <li><p>{{page.complete_line_saying}} <code>{{page.localized_gpg_primary_fingerprint}} {{SIGNING_KEY_FINGERPRINT_EXPLODED}}</code></p></li>
         </ol>
 
-        <p>{{page.gpg_trust_warning}}</p></li>
+        <p>{{page.gpg_trust_warning | replace: '$(SHORT_BUILDER_KEY)', SHORT_BUILDER_KEY }}</p></li>
 
     </ol>
   </details>

_posts/en/pages/2017-01-01-download.md

@@ -4,7 +4,7 @@ permalink: /en/download/
 type: pages
 layout: page
 lang: en
-version: 4
+version: 5
 
 ## These strings need to be localized.  In the listing below, the
 ## comment above each entry contains the English text.  The key before the
@@ -21,8 +21,10 @@ latestversion: "Latest version:"
 download: "Download Bitcoin Core"
 # downloados: "Or choose your operating system"
 downloados: "Or choose your operating system"
-# downloadsig: "Verify release signatures"
-downloadsig: "Verify release signatures"
+# download_sha: "SHA256 binary hashes"
+download_sha: "SHA256 binary hashes"
+# download_sig: "SHA256 hash signatures"
+download_sig: "SHA256 hash signatures"
 # downloadtorrent: "Download torrent"
 downloadtorrent: "Download torrent"
 # source: "Source code"
@@ -50,37 +52,72 @@ notesync: >
 full_node_guide: "For more information about setting up Bitcoin Core, please read the <a href=\"https://bitcoin.org/en/full-node\">full node guide</a>."
 # patient: "Check your bandwidth and space"
 patient: "Check your bandwidth and space"
-# releasekeys: "Bitcoin Core Release Signing Keys"
-releasekeys: "Bitcoin Core Release Signing Keys"
 
 pgp_key_fingerprint: "PGP key fingerprint"
 verify_download: "Verify your download"
-verification_recommended: "Download verification is optional but highly recommended.  Click one of the lines below to view verification instructions for that platform."
+
+verification_recommended: >
+  <p>Download verification is optional but highly recommended. Performing the
+  verification steps here ensures that you have not downloaded an unexpected or
+  tampered version of Bitcoin, which may result in loss of funds.</p> 
+
+  <p>Click one of the lines below to view verification instructions for that
+  platform.</p>
+
 windows_instructions: "Windows verification instructions"
 macos_instructions: "MacOS verification instructions"
 linux_instructions: "Linux verification instructions"
 snap_instructions: "Snap package verification instructions"
 download_release: "Click the link in the list above to download the release for your platform and wait for the file to finish downloading."
 download_checksums: "Download the list of cryptographic checksums:"
+download_checksums_sigs: "Download the signatures attesting to validity of the checksums:"
 cd_to_downloads: "Open a terminal (command line prompt) and Change Directory (cd) to the folder you use for downloads.  For example:"
 cd_example_linux: "cd Downloads/"
 cd_example_windows: >
   cd %UserProfile%\Downloads
 
 verify_download_checksum: "Verify that the checksum of the release file is listed in the checksums file using the following command:"
 checksum_warning_and_ok: 'In the output produced by the above command, you can safely ignore any warnings and failures, but you must ensure the output lists "$(SHASUMS_OK)" after the name of the release file you downloaded.  For example:'
-obtain_release_key: "Obtain a copy of the release signing key by running the following command:"
+
+example_builders_line: "E777299FC265DD04793070EB944D35F9AC3DB76A Michael Ford (fanquake)"
+builder_keys_url: "https://github.com/bitcoin/bitcoin/tree/master/contrib/builder-keys"
+
+obtain_release_key: >
+  <p>Bitcoin releases are signed by a number of individuals, each with a unique public
+  key. In order to recognize the validity of signatures, you must use GPG to load these
+  public keys locally. You can find many developer keys listed in the <a
+  href='$(BUILDER_KEYS_URL)'>bitcoin/bitcoin repository</a>, which you can then load
+  into your GPG key database.</p>
+
+  <p>For example, given the <a href='$(BUILDER_KEYS_TXT_URL)'><code>
+  builders-key/keys.txt</code></a> line
+  <pre class='highlight'><code>$(EXAMPLE_BUILDERS_LINE)</code></pre>you could load that
+  key using this command:</p>
+
+choosing_builders: >
+  It is recommended that you choose a few individuals from this list who you find
+  trustworthy and import their keys as above, or import all the keys per the
+  instructions in the <a href="$(BUILDER_KEYS_URL)"><code>contrib/builder-key</code>
+  README</a>. You will later use their keys to check the signature attesting to the
+  validity of the checksums you use to check the binaries.
+
 release_key_obtained: "The output of the command above should say that one key was imported, updated, has new signatures, or remained unchanged."
+
 verify_checksums_file: "Verify that the checksums file is PGP signed by the release signing key:"
-check_gpg_output: "Check the output from the above command for the following text:"
+
+check_gpg_output: >
+  The command above will output a series of signature checks for each of the public
+  keys that signed the checksums. Each signature will show the following text:
+
 line_starts_with: "A line that starts with:"
 complete_line_saying: "A complete line saying:"
+
 gpg_trust_warning: >
-  The output from the verify command may contain a warning that
-  the "key is not certified with a trusted signature." This means that
-  to fully verify your download, you need to ask people you trust to
-  confirm that the key fingerprint printed above belongs to the Bitcoin
-  Core Project's release signing key.
+  The output from the verify command may contain warnings that the "key is not
+  certified with a trusted signature." This means that to fully verify your download,
+  you need to confirm that the signing key's fingerprint (e.g.
+  <code>$(SHORT_BUILDER_KEY)</code>) listed in the second line above matches what
+  you had expected for the signers public key.
 
 localized_checksum_ok: "OK"
 localized_gpg_good_sig: "Good signature"
@@ -140,4 +177,3 @@ key_refresh: "Refresh expired keys using:"
 ---
 
 {% include templates/download.html %}
-