doc: describe root cert update process

PR-URL: https://github.com/nodejs/node/pull/25113
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

1 files changed, 122 insertions, 0 deletions

diff --git a/doc/guides/updating-root-certs.md b/doc/guides/updating-root-certs.md
new file mode 100644
index 0000000000..f25f74a3e7
--- /dev/null
+++ b/doc/guides/updating-root-certs.md
@@ -0,0 +1,122 @@
+# Updating the Root Certificates
+
+Node.js contains a compiled-in set of root certificates used as trust anchors
+for TLS certificate validation.
+
+The certificates come from Mozilla, specifically NSS's `certdata.txt` file.
+
+The PEM encodings of the certificates are converted to C strings, and committed
+in `src/node_root_certs.h`.
+
+## When to update
+
+Root certificates should be updated sometime after Mozilla makes an NSS release,
+check the [NSS release schedule][].
+
+## Process
+
+Commands assume that the current working directory is the root of a checkout of
+the nodejs/node repository.
+
+1. Find NSS metadata for update.
+
+The latest released NSS version, release date, Firefox version, and Firefox
+release date can be found in the [NSS release schedule][].
+
+The tag to fetch `certdata.txt` from is found by looking for the release
+version in the [tag list][].
+
+2. Update `certdata.txt` from the NSS release tag.
+
+Update the tag in the commands below, and run:
+```shell
+cd tools/
+./mk-ca-bundle -v 2>_before
+curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
+```
+
+The `_before` file will be used later. Verify that running `mk-ca-bundle` made
+no changes to `src/node_root_certs.h`. If it did, something went wrong with the
+previous update. Seek help!
+
+Update metadata in the message below, and commit `certdata.txt`:
+
+```text
+tools: update certdata.txt
+
+This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03.
+
+This is the version of NSS that will ship in Firefox 65 on
+2018-12-11.
+
+[0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
+```
+
+3. Update `node_root_certs.h` from `certdata.txt`.
+
+Run the command below:
+
+```shell
+./mk-ca-bundle.pl -v 2>_after
+```
+
+Confirm that `../src/node_root_certs.h` was updated.
+
+Determine what changes were made by diffing the before and after files:
+```shell
+% diff _before _after
+11d10
+< Parsing: Visa eCommerce Root
+106d104
+< Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
+113,117d110
+< Parsing: Certplus Root CA G1
+< Parsing: Certplus Root CA G2
+< Parsing: OpenTrust Root CA G1
+< Parsing: OpenTrust Root CA G2
+< Parsing: OpenTrust Root CA G3
+134c127,136
+< Done (133 CA certs processed, 20 skipped).
+---
+> Parsing: GlobalSign Root CA - R6
+> Parsing: OISTE WISeKey Global Root GC CA
+> Parsing: GTS Root R1
+> Parsing: GTS Root R2
+> Parsing: GTS Root R3
+> Parsing: GTS Root R4
+> Parsing: UCA Global G2 Root
+> Parsing: UCA Extended Validation Root
+> Parsing: Certigna Root CA
+> Done (135 CA certs processed, 16 skipped).
+```
+
+Use the diff to update the message below, and commit `src/node_root_certs.h`:
+```text
+crypto: update root certificates
+
+Update the list of root certificates in src/node_root_certs.h with
+tools/mk-ca-bundle.pl.
+
+Certificates added:
+- GlobalSign Root CA - R6
+- OISTE WISeKey Global Root GC CA
+- GTS Root R1
+- GTS Root R2
+- GTS Root R3
+- GTS Root R4
+- UCA Global G2 Root
+- UCA Extended Validation Root
+- Certigna Root CA
+
+Certificates removed:
+- Visa eCommerce Root
+- TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
+- Certplus Root CA G1
+- Certplus Root CA G2
+- OpenTrust Root CA G1
+- OpenTrust Root CA G2
+- OpenTrust Root CA G3
+```
+
+[NSS release schedule]: https://wiki.mozilla.org/NSS:Release_Versions
+[tag list]: https://hg.mozilla.org/projects/nss/tags