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.
nodejs · mayrbenjamin92 · Jul 14, 2021 · Jul 14, 2021 · Jul 14, 2021 · Jul 14, 2021
commit 1c820e0f8dd9bc81608874871ddb1a48fd69b548
diff --git a/BUILDING.md b/BUILDING.md
@@ -765,24 +765,40 @@ 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:
+For quictls/openssl 3.0 it is possible to enable FIPS when dynamically linking. If you want to build Node.js using openssl-3.0.0+quic, you can follow these steps:
+
+**clone OpenSSL source and prepare build**
 ```console
-$ git clone git@github.com:quictls/openssl.git
-$ cd openssl
-$ ./config --prefix=/path/to/install/dir/ shared enable-fips linux-x86_64
+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 +813,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 <<EOT >> /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
+```
+
+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
+export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf
+export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules
 ```
 
-Node.js can then be configured to enable FIPS:
+**build Node.js**
 ```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
+./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:
+**verify the produced executable**
 ```console
-$ ldd ./node
+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 +871,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
 ```