OSSForks/node
1
0
Fork 0
mirror of https://github.com/zebrajr/node.git synced 2025-12-06 00:20:08 +01:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

doc: improve node.js+fips instructions

Browse Source 
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 <duhamelantoine1995@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/39390
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
This commit is contained in:
Benjamin Mayr 2021-07-14 20:20:21 +02:00 committed by Beth Griggs
parent b1d38ddc8a
commit e552b1a791
No known key found for this signature in database
GPG Key ID: D7062848A1AB005C
1 changed files with 81 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
BUILDING.md
View File

@ -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
```
This can be compiled and installed using the following commands:
```console
$ make -j8
$ make install_ssldirs
$ make install_fips
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
```
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`):
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
make install_ssldirs
make install_fips
```
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 <<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
```
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
```