1# Maintaining OpenSSL 2 3This document describes how to update `deps/openssl/`. 4 5If you need to provide updates across all active release lines you will 6currently need to generate three PRs as follows: 7 8* a PR for master which is generated following the instructions 9 below which include the QUIC patch. 10* a PR for 14.x following the instruction below based on the 11 14,x branch but skipping the step to apply the QUICK patch. 12 This PR should cherry pick back to the active release lines 13 except for the 10.x line. 14* a PR which uses the same commit from the second PR to apply the 15 updates to the openssl source code, with a new commit generated 16 by following steps 2 onwards on the 10.x line. This is 17 necessary because differences in 10.x requires that the 18 configuration files be regenerated specifically for 10.x. 19 20## Requirements 21* Linux environment. 22* `perl` Only Perl version 5 is tested. 23* `nasm` (<https://www.nasm.us/>) Version 2.11 or higher is needed. 24* GNU `as` in binutils. Version 2.26 or higher is needed. 25 26## 0. Check requirements 27 28```console 29% perl -v 30 31This is perl 5, version 22, subversion 1 (v5.22.1) built for 32x86_64-linux-gnu-thread-multi 33(with 60 registered patches, see perl -V for more detail) 34 35% as --version 36GNU assembler (GNU Binutils for Ubuntu) 2.26.1 37Copyright (C) 2015 Free Software Foundation, Inc. 38... 39% nasm -v 40NASM version 2.11.08 41``` 42 43## 1. Obtain and extract new OpenSSL sources 44 45Get a new source from <https://www.openssl.org/source/> and extract 46all files into `deps/openssl/openssl`. Then add all files and commit 47them. 48```console 49% cd deps/openssl/ 50% rm -rf openssl 51% tar zxf ~/tmp/openssl-1.1.0h.tar.gz 52% mv openssl-1.1.0h openssl 53% git add --all openssl 54% git commit openssl 55``` 56 57The commit message can be written as (with the openssl version set 58to the relevant value): 59```text 60deps: upgrade openssl sources to 1.1.0h 61 62This updates all sources in deps/openssl/openssl by: 63 $ cd deps/openssl/ 64 $ rm -rf openssl 65 $ tar zxf ~/tmp/openssl-1.1.0h.tar.gz 66 $ mv openssl-1.1.0h openssl 67 $ git add --all openssl 68 $ git commit openssl 69``` 70 71## 2. Execute `make` in `deps/openssl/config` directory 72 73Use `make` to regenerate all platform dependent files in 74`deps/openssl/config/archs/`: 75```console 76# On non-Linux machines 77% make gen-openssl 78 79# On Linux machines 80% make -C deps/openssl/config 81``` 82 83## 3. Check diffs 84 85Check diffs to ensure updates are right. Even if there are no updates in openssl 86sources, `buildinf.h` files will be updated because they have timestamp 87data in them. 88```console 89% git diff -- deps/openssl 90``` 91 92*Note*: On Windows, OpenSSL Configure generates a `makefile` that can be 93used for the `nmake` command. The `make` command in step 2 (above) uses 94 `Makefile_VC-WIN64A` and `Makefile_VC-WIN32` that are manually 95created. When source files or build options are updated in Windows, 96it needs to change these two Makefiles by hand. If you are not sure, 97please ask @shigeki for details. 98 99## 4. Commit and make test 100 101Update all architecture dependent files. Do not forget to git add or remove 102files if they are changed before committing: 103```console 104% git add deps/openssl/config/archs 105% git add deps/openssl/openssl/include/crypto/bn_conf.h 106% git add deps/openssl/openssl/include/crypto/dso_conf.h 107% git add deps/openssl/openssl/include/openssl/opensslconf.h 108% git commit 109``` 110 111The commit message can be written as (with the openssl version set 112to the relevant value): 113```text 114 deps: update archs files for OpenSSL-1.1.0 115 116 After an OpenSSL source update, all the config files need to be 117 regenerated and committed by: 118 $ make -C deps/openssl/config 119 $ git add deps/openssl/config/archs 120 $ git add deps/openssl/openssl/include/crypto/bn_conf.h 121 $ git add deps/openssl/openssl/include/crypto/dso_conf.h 122 $ git add deps/openssl/openssl/include/openssl/opensslconf.h 123 $ git commit 124``` 125 126Finally, build Node.js and run the tests. 127