From e552b1a79182bb5c2323c070bdcc55bf8f728fd1 Mon Sep 17 00:00:00 2001 From: Benjamin Mayr Date: Wed, 14 Jul 2021 20:20:21 +0200 Subject: [PATCH] doc: improve node.js+fips instructions Improves the documentation for building Node.js with openssl-3.0.0+quic with enabled FIPS support. Adds missing but necesary steps to the documentation and makes it complete. Co-authored-by: Antoine du Hamel PR-URL: https://github.com/nodejs/node/pull/39390 Reviewed-By: Daniel Bevenius --- BUILDING.md | 109 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 30 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index d8e6e715868db3..6f54601b5a078c 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -766,23 +766,42 @@ to enable FIPS using the configuration flag `--openssl-is-fips`. ### Configuring and building quictls/openssl for FIPS For quictls/openssl 3.0 it is possible to enable FIPS when dynamically linking. -Node.js currently uses openssl-3.0.0+quic which can be configured as -follows: -```console -$ git clone git@github.com:quictls/openssl.git -$ cd openssl -$ ./config --prefix=/path/to/install/dir/ shared enable-fips linux-x86_64 +If you want to build Node.js using openssl-3.0.0+quic, you can follow these +steps: + +**clone OpenSSL source and prepare build** +```bash +git clone git@github.com:quictls/openssl.git + +cd openssl + +./config \ + --prefix=/path/to/install/dir/ \ + shared \ + enable-fips \ + linux-x86_64 ``` -This can be compiled and installed using the following commands: + +The `/path/to/install/dir` is the path in which the `make install` instructions +will publish the OpenSSL libraries and such. We will also use this path +(and sub-paths) later when compiling Node.js. + +**compile and install OpenSSL** ```console -$ make -j8 -$ make install_ssldirs -$ make install_fips +make -j8 +make install +make install_ssldirs +make install_fips ``` -After the FIPS module and configuration file have been installed by the above -instructions we also need to update `/path/to/install/dir/ssl/openssl.cnf` to -use the generated FIPS configuration file (`fipsmodule.cnf`): +After the OpenSSL (including FIPS) modules have been compiled and installed +(into the `/path/to/install/dir`) by the above instructions we also need to +update the OpenSSL configuration file located under +`/path/to/install/dir/ssl/openssl.cnf`. Right next to this file, you should +find the `fipsmodule.cnf` file - let's add the following to the end of the +`openssl.cnf` file. + +**alter openssl.cnf** ```text .include fipsmodule.cnf @@ -797,25 +816,53 @@ fips = fips_sect activate = 1 ``` -In the above case OpenSSL is not installed in the default location so two -environment variables need to be set, `OPENSSL_CONF`, and `OPENSSL_MODULES` -which should point to the OpenSSL configuration file and the directory where -OpenSSL modules are located: +You can e.g. accomplish this by running the following command - be sure to +replace `/path/to/install/dir/` with the path you have selected. Please make +sure that you specify an absolute path for the `.include fipsmodule.cnf` line - +using relative paths did not work on my system! + +**alter openssl.cnf using a script** ```console -$ export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf -$ export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules +cat <> /path/to/install/dir/ssl/openssl.cnf +.include /path/to/install/dir/ssl/fipsmodule.cnf + +# List of providers to load +[provider_sect] +default = default_sect +# The fips section name should match the section name inside the +# included /path/to/install/dir/ssl/fipsmodule.cnf. +fips = fips_sect + +[default_sect] +activate = 1 +EOT ``` -Node.js can then be configured to enable FIPS: +As you might have picked a non-custom path for your OpenSSL install dir, we +have to export the following two environment variables in order for Node.js to +find our OpenSSL modules we built beforehand: ```console -$ ./configure --shared-openssl --shared-openssl-libpath=/path/to/install/dir/lib --shared-openssl-includes=/path/to/install/dir/include --shared-openssl-libname=crypto,ssl --openssl-is-fips -$ export LD_LIBRARY_PATH=/path/to/install/dir/lib -$ make -j8 +export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf +export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules ``` -Verify the produced executable: +**build Node.js** ```console -$ ldd ./node +./configure \ + --shared-openssl \ + --shared-openssl-libpath=/path/to/install/dir/lib \ + --shared-openssl-includes=/path/to/install/dir/include \ + --shared-openssl-libname=crypto,ssl \ + --openssl-is-fips + +export LD_LIBRARY_PATH=/path/to/install/dir/lib + +make -j8 +``` + +**verify the produced executable** +```console +ldd ./node linux-vdso.so.1 (0x00007ffd7917b000) libcrypto.so.81.3 => /path/to/install/dir/lib/libcrypto.so.81.3 (0x00007fd911321000) libssl.so.81.3 => /path/to/install/dir/lib/libssl.so.81.3 (0x00007fd91125e000) @@ -827,21 +874,23 @@ $ ldd ./node libc.so.6 => /usr/lib64/libc.so.6 (0x00007fd910cec000) /lib64/ld-linux-x86-64.so.2 (0x00007fd9117f2000) ``` + If the `ldd` command says that `libcrypto` cannot be found one needs to set `LD_LIBRARY_PATH` to point to the directory used above for `--shared-openssl-libpath` (see previous step). -Verify the OpenSSL version: +**verify the OpenSSL version** ```console -$ ./node -p process.versions.openssl +./node -p process.versions.openssl 3.0.0-alpha16+quic ``` -Verify that FIPS is available: +**verify that FIPS is available** ```console -$ ./node -p 'process.config.variables.openssl_is_fips' +./node -p 'process.config.variables.openssl_is_fips' true -$ ./node --enable-fips -p 'crypto.getFips()' + +./node --enable-fips -p 'crypto.getFips()' 1 ```