Skip to content

Commit 43c08bf

Browse files
swissspidyswissspidy
authored
Merge pull request #585 from wp-cli/copilot/document-cryptographic-verification
2 parents ccbe7dd + 81292a6 commit 43c08bf

File tree

3 files changed

+228
-0
lines changed

3 files changed

+228
-0
lines changed

‎bin/handbook-manifest.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -575,6 +575,12 @@
575575
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/troubleshooting.md",
576576
"parent": "guides"
577577
},
578+
"verifying-downloads": {
579+
"title": "Verifying WP-CLI Downloads",
580+
"slug": "verifying-downloads",
581+
"markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/verifying-downloads.md",
582+
"parent": "guides"
583+
},
578584
"when-i-launch-in-the-background": {
579585
"title": "When \/^I launch in the background `([^`]+)`$\/",
580586
"slug": "when-i-launch-in-the-background",

‎guides/installing.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,18 @@ First, download [wp-cli.phar](https://raw.githubusercontent.com/wp-cli/builds/gh
1010
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
1111
```
1212

13+
### Verifying the download (optional but recommended)
14+
15+
Before using the downloaded file, you can verify its authenticity and integrity. See our [guide to verifying WP-CLI downloads](https://make.wordpress.org/cli/handbook/guides/verifying-downloads/) for detailed instructions on using GPG signatures or checksums to ensure the file hasn't been tampered with.
16+
17+
Quick verification using GPG:
18+
19+
```
20+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.asc
21+
curl -L https://raw.githubusercontent.com/wp-cli/builds/gh-pages/wp-cli.pgp | gpg --import
22+
gpg --verify wp-cli.phar.asc wp-cli.phar
23+
```
24+
1325
Then, check if it works:
1426

1527
```
@@ -114,6 +126,8 @@ Open Alfred and try searching for a specific command. For example, this gives yo
114126

115127
## Alternative installation methods
116128

129+
**Note:** For all Phar-based installation methods below, you can verify the downloaded file's authenticity and integrity. See the [guide to verifying WP-CLI downloads](https://make.wordpress.org/cli/handbook/guides/verifying-downloads/) for instructions.
130+
117131
### Installing via Git
118132

119133
If you intend to work on WP-CLI itself, see the [Setting up](https://make.wordpress.org/cli/handbook/pull-requests/#setting-up) section in [Pull Requests](https://make.wordpress.org/cli/handbook/pull-requests/).

‎guides/verifying-downloads.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Verifying WP-CLI Downloads
2+
3+
This guide explains how to cryptographically verify the authenticity and integrity of WP-CLI releases after downloading them from the Internet and before installing them on your system.
4+
5+
## Why verify downloads?
6+
7+
Verifying downloads ensures:
8+
- **Authenticity**: The file was created and signed by the WP-CLI maintainers
9+
- **Integrity**: The file has not been corrupted or tampered with during download
10+
11+
## Quick verification guide
12+
13+
After downloading `wp-cli.phar`, you can verify it using either GPG signatures or checksums.
14+
15+
### Method 1: Verify using GPG signature (Recommended)
16+
17+
This method provides the strongest security as it verifies both the integrity and authenticity of the download.
18+
19+
#### Step 1: Download the signature file
20+
21+
```bash
22+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.asc
23+
```
24+
25+
For a specific version release, download from GitHub releases (replace `X.X.X` with the desired version):
26+
27+
```bash
28+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/vX.X.X/wp-cli-X.X.X.phar
29+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/vX.X.X/wp-cli-X.X.X.phar.asc
30+
```
31+
32+
For example, to download version 2.12.0:
33+
34+
```bash
35+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/v2.12.0/wp-cli-2.12.0.phar
36+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/v2.12.0/wp-cli-2.12.0.phar.asc
37+
```
38+
39+
#### Step 2: Import the WP-CLI release signing key
40+
41+
WP-CLI releases are signed with the WP-CLI release signing key. Import the public key:
42+
43+
```bash
44+
curl -L https://raw.githubusercontent.com/wp-cli/builds/gh-pages/wp-cli.pgp | gpg --import
45+
```
46+
47+
The key fingerprint is:
48+
```
49+
63AF 7AA1 5067 C056 16FD DD88 A3A2 E8F2 26F0 BC06
50+
```
51+
52+
You can verify the key fingerprint after importing:
53+
54+
```bash
55+
gpg --list-keys --with-fingerprint releases@wp-cli.org
56+
```
57+
58+
The output should include:
59+
```
60+
pub rsa2048 2018-05-31 [SC]
61+
63AF 7AA1 5067 C056 16FD DD88 A3A2 E8F2 26F0 BC06
62+
uid [ unknown] WP-CLI Releases <releases@wp-cli.org>
63+
sub rsa2048 2018-05-31 [E]
64+
```
65+
66+
**Note:** Releases prior to v1.5.1 (July 2016) were signed with a different key (fingerprint: `3B91 91CD 3CF1 B5C5 10EE FAF6 AFAA E4A2 85E0 40A8`). If you need to verify older releases, import that key from the [builds repository README](https://github.com/wp-cli/builds/blob/gh-pages/README.md).
67+
68+
#### Step 3: Verify the signature
69+
70+
For the latest stable release:
71+
72+
```bash
73+
gpg --verify wp-cli.phar.asc wp-cli.phar
74+
```
75+
76+
For a specific version:
77+
78+
```bash
79+
gpg --verify wp-cli-2.12.0.phar.asc wp-cli-2.12.0.phar
80+
```
81+
82+
If the signature is valid, you'll see output similar to:
83+
84+
```
85+
gpg: Signature made {DATE}
86+
gpg: using RSA key 63AF7AA15067C05616FDDD88A3A2E8F226F0BC06
87+
gpg: Good signature from "WP-CLI Releases <releases@wp-cli.org>" [unknown]
88+
```
89+
90+
You may see a warning about the key not being trusted:
91+
```
92+
gpg: WARNING: This key is not certified with a trusted signature!
93+
gpg: There is no indication that the signature belongs to the owner.
94+
```
95+
96+
This is expected if you haven't personally verified and signed the WP-CLI key. The important part is seeing "Good signature" which confirms the file was signed by this key and hasn't been modified.
97+
98+
### Method 2: Verify using checksums
99+
100+
If GPG is not available, you can verify the integrity (but not authenticity) using SHA-512 or SHA-256 checksums.
101+
102+
#### Using SHA-512
103+
104+
Download the SHA-512 checksum file:
105+
106+
```bash
107+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.sha512
108+
```
109+
110+
Or for a specific release (replace `X.X.X` with your version):
111+
112+
```bash
113+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/vX.X.X/wp-cli-X.X.X.phar.sha512
114+
```
115+
116+
Verify the checksum by comparing the output:
117+
118+
```bash
119+
sha512sum wp-cli.phar
120+
cat wp-cli.phar.sha512
121+
```
122+
123+
The two hashes should match exactly.
124+
125+
#### Using SHA-256
126+
127+
Download the SHA-256 checksum file:
128+
129+
```bash
130+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.sha256
131+
```
132+
133+
Or for a specific release (replace `X.X.X` with your version):
134+
135+
```bash
136+
curl -LO https://github.com/wp-cli/wp-cli/releases/download/vX.X.X/wp-cli-X.X.X.phar.sha256
137+
```
138+
139+
Verify the checksum by comparing the output:
140+
141+
```bash
142+
sha256sum wp-cli.phar
143+
cat wp-cli.phar.sha256
144+
```
145+
146+
The two hashes should match exactly.
147+
148+
**Note:** Checksum verification only confirms the file matches the published checksum. It does not verify that the file was created by the WP-CLI maintainers. For complete security, use GPG signature verification.
149+
150+
## Where to find verification files
151+
152+
### Latest stable and nightly builds
153+
154+
Verification files for the latest stable and nightly builds are available at:
155+
- <https://github.com/wp-cli/builds/tree/gh-pages/phar>
156+
157+
Available files:
158+
- `wp-cli.phar.asc` - GPG signature for latest stable
159+
- `wp-cli.phar.sha512` - SHA-512 checksum for latest stable
160+
- `wp-cli.phar.md5` - MD5 checksum (not recommended for security; MD5 is cryptographically broken and vulnerable to collision attacks)
161+
- `wp-cli-nightly.phar.asc` - GPG signature for nightly
162+
- `wp-cli-nightly.phar.sha512` - SHA-512 checksum for nightly
163+
164+
### Specific version releases
165+
166+
For a specific version, verification files are available on the [GitHub releases page](https://github.com/wp-cli/wp-cli/releases):
167+
168+
Each release includes:
169+
- `wp-cli-X.X.X.phar` - The WP-CLI phar file
170+
- `wp-cli-X.X.X.phar.asc` - Detached GPG signature
171+
- `wp-cli-X.X.X.phar.gpg` - Inline GPG signature
172+
- `wp-cli-X.X.X.phar.sha512` - SHA-512 checksum
173+
- `wp-cli-X.X.X.phar.sha256` - SHA-256 checksum
174+
- `wp-cli-X.X.X.phar.md5` - MD5 checksum (not recommended for security; MD5 is cryptographically broken and vulnerable to collision attacks)
175+
176+
## Complete installation example with verification
177+
178+
Here's a complete example of downloading, verifying, and installing WP-CLI:
179+
180+
```bash
181+
# Download WP-CLI
182+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
183+
184+
# Download signature
185+
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.asc
186+
187+
# Import signing key (first time only)
188+
curl -L https://raw.githubusercontent.com/wp-cli/builds/gh-pages/wp-cli.pgp | gpg --import
189+
190+
# Verify signature
191+
gpg --verify wp-cli.phar.asc wp-cli.phar
192+
193+
# If verification succeeds, test it works
194+
php wp-cli.phar --info
195+
196+
# Make executable and move to PATH
197+
chmod +x wp-cli.phar
198+
sudo mv wp-cli.phar /usr/local/bin/wp
199+
200+
# Verify installation
201+
wp --info
202+
```
203+
204+
## Additional resources
205+
206+
- [WP-CLI Builds Repository](https://github.com/wp-cli/builds) - Contains signing keys and latest builds
207+
- [GitHub Releases](https://github.com/wp-cli/wp-cli/releases) - All version releases with verification files
208+
- [GNU Privacy Guard](https://gnupg.org/) - Learn more about GPG

0 commit comments

Comments
 (0)