• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
18Commands assume that the current working directory is the root of a checkout of
19the nodejs/node repository.
20
211. Find NSS metadata for update.
22
23    The latest released NSS version, release date, Firefox version, and Firefox
24    release date can be found in the [NSS release schedule][].
25
26    The tag to fetch `certdata.txt` from is found by looking for the release
27    version in the [tag list][].
28
292. Update `certdata.txt` from the NSS release tag.
30
31    Update the tag in the commands below, and run:
32
33    ```bash
34    cd tools/
35    ./mk-ca-bundle.pl -v 2>_before
36    curl -O https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
37    ```
38
39    The `_before` file will be used later. Verify that running `mk-ca-bundle`
40    made no changes to `src/node_root_certs.h`. If it did, something went wrong
41    with the previous update. Seek help!
42
43    Update metadata in the message below, and commit `certdata.txt`:
44
45    ```text
46    tools: update certdata.txt
47
48    This is the certdata.txt[0] from NSS 3.41, released on 2018-12-03.
49
50    This is the version of NSS that will ship in Firefox 65 on
51    2018-12-11.
52
53    [0] https://hg.mozilla.org/projects/nss/raw-file/NSS_3_41_RTM/lib/ckfw/builtins/certdata.txt
54    ```
55
563. Update `node_root_certs.h` from `certdata.txt`.
57
58    Run the command below:
59
60    ```bash
61    ./mk-ca-bundle.pl -v 2>_after
62    ```
63
64    Confirm that `../src/node_root_certs.h` was updated.
65
66    Determine what changes were made by diffing the before and after files:
67
68    ```console
69    % diff _before _after
70    11d10
71    < Parsing: Visa eCommerce Root
72    106d104
73    < Parsing: TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
74    113,117d110
75    < Parsing: Certplus Root CA G1
76    < Parsing: Certplus Root CA G2
77    < Parsing: OpenTrust Root CA G1
78    < Parsing: OpenTrust Root CA G2
79    < Parsing: OpenTrust Root CA G3
80    134c127,136
81    < Done (133 CA certs processed, 20 skipped).
82    ---
83    > Parsing: GlobalSign Root CA - R6
84    > Parsing: OISTE WISeKey Global Root GC CA
85    > Parsing: GTS Root R1
86    > Parsing: GTS Root R2
87    > Parsing: GTS Root R3
88    > Parsing: GTS Root R4
89    > Parsing: UCA Global G2 Root
90    > Parsing: UCA Extended Validation Root
91    > Parsing: Certigna Root CA
92    > Done (135 CA certs processed, 16 skipped).
93    ```
94
95    Use the diff to update the message below, and commit `src/node_root_certs.h`:
96
97    ```text
98    crypto: update root certificates
99
100    Update the list of root certificates in src/node_root_certs.h with
101    tools/mk-ca-bundle.pl.
102
103    Certificates added:
104    - GlobalSign Root CA - R6
105    - OISTE WISeKey Global Root GC CA
106    - GTS Root R1
107    - GTS Root R2
108    - GTS Root R3
109    - GTS Root R4
110    - UCA Global G2 Root
111    - UCA Extended Validation Root
112    - Certigna Root CA
113
114    Certificates removed:
115    - Visa eCommerce Root
116    - TÜRKTRUST Elektronik Sertifika Hizmet Sağlayıcısı H5
117    - Certplus Root CA G1
118    - Certplus Root CA G2
119    - OpenTrust Root CA G1
120    - OpenTrust Root CA G2
121    - OpenTrust Root CA G3
122    ```
123
124[NSS release schedule]: https://wiki.mozilla.org/NSS:Release_Versions
125[tag list]: https://hg.mozilla.org/projects/nss/tags
126