Skip to content

Commit

Permalink
Merge #803: Update binary verification instructions for multiple signers
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@harding
harding committed Sep 20, 2021
2 parents 2aeaa47 + ca85967 commit 4bf8149
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 34 deletions.
70 changes: 50 additions & 20 deletions _includes/templates/download.html
View file
Expand Up @@ -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" %}
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>

Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>

Expand All @@ -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>

Expand All @@ -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>
Expand All @@ -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>

Expand All @@ -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>

Expand All @@ -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>
Expand All @@ -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>
Expand Down
64 changes: 50 additions & 14 deletions _posts/en/pages/2017-01-01-download.md
View file
Expand Up @@ -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
Expand All @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -140,4 +177,3 @@ key_refresh: "Refresh expired keys using:"
---

{% include templates/download.html %}

0 comments on commit 4bf8149

Please sign in to comment.