1# Maintaining the root certificates
2
3Node.js contains a compiled-in set of root certificates used as trust anchors
4for TLS certificate validation.
5
6The certificates come from Mozilla, specifically NSS's `certdata.txt` file.
7
8The PEM encodings of the certificates are converted to C strings, and committed
9in `src/node_root_certs.h`.
10
11## When to update
12
13Root certificates should be updated sometime after Mozilla makes an NSS release,
14check the [NSS release schedule][].
15
16## Process
17
18The `tools/dep_updaters/update-root-certs.mjs` script automates the update of
19the root certificates, including:
20
21* Downloading `certdata.txt` from Mozilla's source control repository.
22* Running `tools/mk-ca-bundle.pl` to convert the certificates and generate
23  `src/node_root_certs.h`.
24* Using `git diff-files` to determine which certificate have been added and/or
25  removed.
26
27Manual instructions are included in the following collapsed section.
28
29<details>
30
31Commands assume that the current working directory is the root of a checkout of
32the nodejs/node repository.
33
341. Find NSS metadata for update.
35
36   The latest released NSS version, release date, Firefox version, and Firefox
37   release date can be found in the [NSS release schedule][].
38
39   The tag to fetch `certdata.txt` from is found by looking for the release
40   version in the [tag list][].
41
422. Update `certdata.txt` from the NSS release tag.
43
44   Update the tag in the commands below, and run:
45
46   ```bash
47   cd tools/
48   ./mk-ca-bundle.pl -v 2>_before
49   curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
50   ```
51
52   The `_before` file will be used later. Verify that running `mk-ca-bundle`
53   made no changes to `src/node_root_certs.h`. If it did, something went wrong
54   with the previous update. Seek help!
55
56   Update metadata in the message below, and commit `certdata.txt`:
57
58   ```text
59   tools: update certdata.txt
60
61   This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03.
62
63   This is the version of NSS that will ship in Firefox 65 on
64   2018-12-11.
65
66   [0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
67   ```
68
693. Update `node_root_certs.h` from `certdata.txt`.
70
71   Run the command below:
72
73   ```bash
74   ./mk-ca-bundle.pl -v 2>_after
75   ```
76
77   Confirm that `../src/node_root_certs.h` was updated.
78
79   Determine what changes were made by diffing the before and after files:
80
81   ```console
82   % diff _before _after
83   11d10
84   < Parsing: Visa eCommerce Root
85   106d104
86   < Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
87   113,117d110
88   < Parsing: Certplus Root CA G1
89   < Parsing: Certplus Root CA G2
90   < Parsing: OpenTrust Root CA G1
91   < Parsing: OpenTrust Root CA G2
92   < Parsing: OpenTrust Root CA G3
93   134c127,136
94   < Done (133 CA certs processed, 20 skipped).
95   ---
96   > Parsing: GlobalSign Root CA - R6
97   > Parsing: OISTE WISeKey Global Root GC CA
98   > Parsing: GTS Root R1
99   > Parsing: GTS Root R2
100   > Parsing: GTS Root R3
101   > Parsing: GTS Root R4
102   > Parsing: UCA Global G2 Root
103   > Parsing: UCA Extended Validation Root
104   > Parsing: Certigna Root CA
105   > Done (135 CA certs processed, 16 skipped).
106   ```
107
108   Use the diff to update the message below, and commit `src/node_root_certs.h`:
109
110   ```text
111   crypto: update root certificates
112
113   Update the list of root certificates in src/node_root_certs.h with
114   tools/mk-ca-bundle.pl.
115
116   Certificates added:
117   - GlobalSign Root CA - R6
118   - OISTE WISeKey Global Root GC CA
119   - GTS Root R1
120   - GTS Root R2
121   - GTS Root R3
122   - GTS Root R4
123   - UCA Global G2 Root
124   - UCA Extended Validation Root
125   - Certigna Root CA
126
127   Certificates removed:
128   - Visa eCommerce Root
129   - TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
130   - Certplus Root CA G1
131   - Certplus Root CA G2
132   - OpenTrust Root CA G1
133   - OpenTrust Root CA G2
134   - OpenTrust Root CA G3
135   ```
136
137</details>
138
139[NSS release schedule]: https://wiki.mozilla.org/NSS:Release_Versions
140[tag list]: https://hg.mozilla.org/projects/nss/tags
141