Skip to content

Commit 486db81

Browse files
feelepxyzfeelepxyz
authored
Add documentation for new registry signatures (#14)
1 parent b2dfac7 commit 486db81

File tree

6 files changed

+141
-8
lines changed

6 files changed

+141
-8
lines changed

‎content/packages-and-modules/securing-your-code/about-pgp-signatures-for-packages-in-the-public-registry.mdx

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
---
2-
title: About package PGP signatures
2+
title: About PGP registry signatures (deprecated)
33
---
4+
<Note>
5+
6+
**Note:** PGP signatures will be deprecated early 2023, in favour of ECDSA registry signatures that can be verified using the npm CLI. [Learn more.](/about-registry-signatures)
7+
8+
</Note>
49

510
To increase confidence in the npm public registry, we add our [PGP][pgp-wiki] signature to package metadata and publicize our public PGP key on [Keybase][keybase]. Our Keybase account is "[npmregistry][npmregistry]" and our public PGP key can be found at https://keybase.io/npmregistry/pgp_keys.asc
611

@@ -21,7 +26,7 @@ Keybase offers two advantages over the core OpenPGP experience that move us to r
2126
- The Keybase application and CLI provide an excellent user experience for PGP, which can be intimidating for newcomers.
2227
- Keybase manages and displays social proofs that the entity that controls a specific PGP key also controls accounts on social media and other places. These proofs help you determine whether you can trust an account.
2328

24-
We’ve established proofs on Keybase that we control [@npmjs][npmjs-twitter] on Twitter, the domain [npmjs.com][npmjs-com], and the domain [npmjs.org][npmjs-org]. Verifying these proofs won’t tell you who owns those domains, but it does establish that the same entity controls them and the PGP key advertised on Keybase.
29+
We’ve established proofs on Keybase that we control [@npmjs][npmjs-twitter] on Twitter, the domain [npmjs.com][npmjs-com], and the domain [npmjs.org][npmjs-org]. Verifying these proofs won’t tell you who owns those domains, but it does establish that the same entity controls them, and the PGP key advertised on Keybase.
2530

2631
If you install Keybase and create an account, you can follow npmregistry yourself and obtain a local copy of the registry’s public key. For more information, and to verify the PGP signature of a specific package version from the npm public registry, see "[Verifying the PGP signature for a package from the npm public registry][verify-pgp]".
2732

‎content/packages-and-modules/securing-your-code/about-registry-signatures.mdx

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: About ECDSA registry signatures
3+
---
4+
5+
Packages published to the public npm registry are signed to make it possible to detect if the package content has been tampered with.
6+
7+
Signing and verifying published packages protects against an attacker controlling a registry mirror or proxy where they attempt to intercept and tamper with the package tarball content.
8+
9+
## Migrating from PGP to ECDSA signatures
10+
11+
<Note>
12+
13+
**Note:** PGP signatures will be deprecated early 2023, in favour of ECDSA registry signatures. More information will soon be provided.
14+
15+
</Note>
16+
17+
The public npm registry is migrating away from the existing PGP signatures to ECDSA signatures that are more compact and can be verified without extra dependencies in the npm CLI.
18+
19+
Signature verification was previously a multi-step process involving the Keybase CLI, as well as manually retrieving and parsing the signature from the package metadata.
20+
21+
Read more about <a href="/verifying-registry-signatures">migrating and verifying signatures</a> using the npm CLI.
22+
23+
## Supporting signatures on third-party registries
24+
25+
The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
26+
27+
**1. Signatures are provided in the package's `packument` in each published version within the `dist` object:**
28+
29+
```
30+
"dist":{
31+
..omitted..,
32+
"signatures": [{
33+
"keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
34+
"sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
35+
}],
36+
```
37+
38+
See this <a href="https://registry.npmjs.org/light-cycle/1.4.3" target="_blank">example of a signed package from the public npm registry</a>.
39+
40+
To generate the signature, sign the package name, version and tarball sha integrity: `${package.name}@${package.version}:${package.dist.integrity}`.
41+
42+
The current best practice is to use a <a href="https://en.wikipedia.org/wiki/Key_management#Key_management_system" target="_blank">Key Management System</a> that does the signing operation on a <a href="https://en.wikipedia.org/wiki/Hardware_security_module" target="_blank">Hardware Security Module (HSM)</a> in order to not directly handle the private key part, which reduces the attack surface.
43+
44+
The `keyid` must match one of the public signing keys below.
45+
46+
**2. Public signing keys are provided at `registry-host.tld/-/npm/v1/keys` in the following format:**
47+
48+
```
49+
{
50+
"keys": [{
51+
"expires": null,
52+
"keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
53+
"keytype": "ecdsa-sha2-nistp256",
54+
"scheme": "ecdsa-sha2-nistp256",
55+
"key": "{{B64_PUBLIC_KEY}}"
56+
}]
57+
}
58+
```
59+
60+
Keys response:
61+
62+
- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
63+
- `keydid`: sha256 fingerprint of the public key
64+
- `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
65+
- `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
66+
- `key`: base64 encoded public key
67+
68+
See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.

‎content/packages-and-modules/securing-your-code/verifying-registry-signatures.mdx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Verifying ECDSA registry signatures
3+
---
4+
5+
To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.
6+
7+
## Prerequisites
8+
9+
1. Install npm CLI version v8.15.0 or later
10+
2. Install dependencies using `npm install` or `npm ci`
11+
12+
## Verifying registry signatures
13+
14+
Registry signatures can be verified using the following `audit` command:
15+
16+
```
17+
npm audit signatures
18+
```
19+
20+
Example response if all installed versions have valid registry signatures:
21+
22+
```
23+
audited 1640 packages in 2s
24+
25+
1640 have verified registry signatures
26+
```
27+
28+
## Troubleshooting
29+
30+
### Some packages are missing registry signatures
31+
32+
The CLI will error if packages don't have signatures *and* if the package registry supports signatures. This could mean an attacker might be trying to circumvent signature verification.
33+
You can check if the registry supports signatures by requesting the public signing keys from `registry-host.tld/-/npm/v1/keys`.
34+
35+
Example response if some versions have missing registry signatures:
36+
37+
```
38+
audited 1640 packages in 2s
39+
40+
1405 packages have verified registry signatures
41+
42+
235 packages have missing registry signatures but the registry is providing signing keys:
43+
44+
missing-dep@1.0.0 (https://registry.npmjs.org/)
45+
...
46+
```

‎content/packages-and-modules/securing-your-code/verifying-the-pgp-signature-for-a-package-from-the-npm-public-registry.mdx

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
---
2-
title: Verifying the PGP signature of a package from the npm public registry
2+
title: Verifying the PGP registry signature of a package from the npm public registry (deprecated)
33
---
44

5+
<Note>
6+
7+
**Note:** PGP signatures will be deprecated early 2023, in favour of ECDSA registry signatures that can be verified using the npm CLI. More information will soon be provided.
8+
9+
</Note>
10+
511
To ensure the integrity of a package version you download from the npm public registry, you can manually verify the [PGP signature][about-pgp-sig] of the package.
612

713
<Note>
814

9-
**Note:** Since fully verifying signatures on Keybase requires rechecking proofs (which requires network activity) and is therefore expensive, we recommend only verifying signatures if it is absolutely necessary -- for example, when verifying a deploy artifact, or when initially storing a package in your cache.
15+
**Note:** Since fully verifying signatures on Keybase requires rechecking proofs (which requires network activity) and is therefore expensive, we recommend only verifying signatures if it is necessary -- for example, when verifying a deploy artifact, or when initially storing a package in your cache.
1016

1117
</Note>
1218

‎src/gatsby-theme-doctornpm/nav.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,9 +152,13 @@
152152
url: /about-audit-reports
153153
- title: Auditing package dependencies for security vulnerabilities
154154
url: /auditing-package-dependencies-for-security-vulnerabilities
155-
- title: About package PGP signatures
155+
- title: About ECDSA registry signatures
156+
url: /about-registry-signatures
157+
- title: Verifying ECDSA registry signatures
158+
url: /verifying-registry-signatures
159+
- title: About PGP registry signatures (deprecated)
156160
url: /about-pgp-signatures-for-packages-in-the-public-registry
157-
- title: Verifying the PGP signature of a package from the npm public registry
161+
- title: Verifying PGP registry signatures (deprecated)
158162
url: /verifying-the-pgp-signature-for-a-package-from-the-npm-public-registry
159163
- title: Requiring 2FA for package publishing and settings modification
160164
url: /requiring-2fa-for-package-publishing-and-settings-modification

‎src/nav-base.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,9 +150,13 @@
150150
url: /about-audit-reports
151151
- title: Auditing package dependencies for security vulnerabilities
152152
url: /auditing-package-dependencies-for-security-vulnerabilities
153-
- title: About package PGP signatures
153+
- title: About ECDSA registry signatures
154+
url: /about-registry-signatures
155+
- title: Verifying ECDSA registry signatures
156+
url: /verifying-registry-signatures
157+
- title: About PGP registry signatures (deprecated)
154158
url: /about-pgp-signatures-for-packages-in-the-public-registry
155-
- title: Verifying the PGP signature of a package from the npm public registry
159+
- title: Verifying PGP registry signatures (deprecated)
156160
url: /verifying-the-pgp-signature-for-a-package-from-the-npm-public-registry
157161
- title: Requiring 2FA for package publishing and settings modification
158162
url: /requiring-2fa-for-package-publishing-and-settings-modification

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy