1# Maintaining OpenSSL
2
3OpenSSL is automatically updated by the [update-openssl-action][].
4There is also a script in `tools/dep_updaters` that can be used to update it.
5This document describes how to manually update `deps/openssl/`.
6
7If you need to provide updates across all active release lines you will
8currently need to generate four PRs as follows:
9
10* a PR for `main` which is generated following the instructions
11  below for OpenSSL 3.x.x.
12* a PR for 18.x following the instructions in the v18.x-staging version
13  of this guide.
14* a PR for 16.x following the instructions in the v16.x-staging version
15  of this guide.
16
17## Use of the quictls/openssl fork
18
19Node.js currently uses the quictls/openssl fork, which closely tracks
20the main openssl/openssl releases with the addition of APIs to support
21the QUIC protocol.
22
23Details on the fork, as well as the latest sources, can be found at
24<https://github.com/quictls/openssl>.
25
26Branches are used per OpenSSL version (for instance,
27<https://github.com/quictls/openssl/tree/OpenSSL_1_1_1j+quic>).
28
29## Requirements
30
31* Linux environment.
32* `perl` Only Perl version 5 is tested.
33* `nasm` (<https://www.nasm.us/>) Version 2.11 or higher is needed.
34* GNU `as` in binutils. Version 2.26 or higher is needed.
35
36## 0. Check requirements
37
38```console
39% perl -v
40
41This is perl 5, version 22, subversion 1 (v5.22.1) built for
42x86_64-linux-gnu-thread-multi
43(with 60 registered patches, see perl -V for more detail)
44
45% as --version
46GNU assembler (GNU Binutils for Ubuntu) 2.26.1
47Copyright (C) 2015 Free Software Foundation, Inc.
48...
49% nasm -v
50NASM version 2.11.08
51```
52
53## 1. Obtain and extract new OpenSSL sources
54
55Get a new source from <https://github.com/quictls/openssl/tree/openssl-3.0.5+quic>
56and copy all files into `deps/openssl/openssl`. Then add all files and commit
57them. (The link above, and the branch, will change with each new OpenSSL
58release).
59
60### OpenSSL 3.x.x
61
62```console
63% git clone https://github.com/quictls/openssl
64% cd openssl
65% cd ../node/deps/openssl
66% rm -rf openssl
67% cp -R ../../../openssl openssl
68% rm -rf openssl/.git* openssl/.travis*
69% git add --all openssl
70% git commit openssl
71```
72
73```text
74deps: upgrade openssl sources to quictls/openssl-3.0.5+quic
75
76This updates all sources in deps/openssl/openssl by:
77    $ git clone git@github.com:quictls/openssl.git
78    $ cd openssl
79    $ git checkout openssl-3.0.5+quic
80    $ cd ../node/deps/openssl
81    $ rm -rf openssl
82    $ cp -R ../../../openssl openssl
83    $ rm -rf openssl/.git* openssl/.travis*
84    $ git add --all openssl
85    $ git commit openssl
86```
87
88## 2. Execute `make` in `deps/openssl/config` directory
89
90Use `make` to regenerate all platform dependent files in
91`deps/openssl/config/archs/`:
92
93```console
94# On non-Linux machines
95% make gen-openssl
96
97# On Linux machines
98% make -C deps/openssl/config clean
99% make -C deps/openssl/config
100```
101
102**Note**: If the 32-bit Windows is failing to compile run this workflow instead:
103
104```console
105% make -C deps/openssl/config clean
106# Edit deps/openssl/openssl/crypto/perlasm/x86asm.pl changing
107# #ifdef to %ifdef to make it compatible to nasm on 32-bit Windows.
108# See: https://github.com/nodejs/node/pull/43603#issuecomment-1170670844
109# Reference: https://github.com/openssl/openssl/issues/18459
110```
111
112## 3. Check diffs
113
114Check diffs to ensure updates are right. Even if there are no updates in openssl
115sources, `buildinf.h` files will be updated because they have timestamp
116data in them.
117
118```console
119% git diff -- deps/openssl
120```
121
122_Note_: On Windows, OpenSSL Configure generates a `makefile` that can be
123used for the `nmake` command. The `make` command in step 2 (above) uses
124`Makefile_VC-WIN64A` and `Makefile_VC-WIN32` that are manually
125created. When source files or build options are updated in Windows,
126it needs to change these two Makefiles by hand. If you are not sure,
127please ask @shigeki for details.
128
129## 4. Commit and make test
130
131Update all architecture dependent files. Do not forget to git add or remove
132files if they are changed before committing:
133
134```console
135% git add deps/openssl/config/archs
136% git add deps/openssl/openssl
137% git commit
138```
139
140The commit message can be written as (with the openssl version set
141to the relevant value):
142
143### OpenSSL 3.x.x
144
145```text
146deps: update archs files for quictls/openssl-3.0.5+quic
147
148After an OpenSSL source update, all the config files need to be
149regenerated and committed by:
150    $ make -C deps/openssl/config
151    $ git add deps/openssl/config/archs
152    $ git add deps/openssl/openssl
153    $ git commit
154```
155
156Finally, build Node.js and run the tests.
157
158[update-openssl-action]: ../../../.github/workflows/update-openssl.yml
159