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