| 1 | OpenSSL FIPS support
|
|---|
| 2 | ====================
|
|---|
| 3 |
|
|---|
| 4 | This release of OpenSSL includes a cryptographic module that is intended to be
|
|---|
| 5 | FIPS 140-2 validated. The module is implemented as an OpenSSL provider.
|
|---|
| 6 | A provider is essentially a dynamically loadable module which implements
|
|---|
| 7 | cryptographic algorithms, see the [README-PROVIDERS](README-PROVIDERS.md) file
|
|---|
| 8 | for further details.
|
|---|
| 9 |
|
|---|
| 10 | The OpenSSL FIPS provider comes as shared library called `fips.so` (on Unix)
|
|---|
| 11 | resp. `fips.dll` (on Windows). The FIPS provider does not get built and
|
|---|
| 12 | installed automatically. To enable it, you need to configure OpenSSL using
|
|---|
| 13 | the `enable-fips` option.
|
|---|
| 14 |
|
|---|
| 15 | Installing the FIPS module
|
|---|
| 16 | ==========================
|
|---|
| 17 |
|
|---|
| 18 | If the FIPS provider is enabled, it gets installed automatically during the
|
|---|
| 19 | normal installation process. Simply follow the normal procedure (configure,
|
|---|
| 20 | make, make test, make install) as described in the [INSTALL](INSTALL.md) file.
|
|---|
| 21 |
|
|---|
| 22 | For example, on Unix the final command
|
|---|
| 23 |
|
|---|
| 24 | $ make install
|
|---|
| 25 |
|
|---|
| 26 | effectively executes the following install targets
|
|---|
| 27 |
|
|---|
| 28 | $ make install_sw
|
|---|
| 29 | $ make install_ssldirs
|
|---|
| 30 | $ make install_docs
|
|---|
| 31 | $ make install_fips # for `enable-fips` only
|
|---|
| 32 |
|
|---|
| 33 | The `install_fips` make target can also be invoked explicitly to install
|
|---|
| 34 | the FIPS provider independently, without installing the rest of OpenSSL.
|
|---|
| 35 |
|
|---|
| 36 | The Installation of the FIPS provider consists of two steps. In the first step,
|
|---|
| 37 | the shared library is copied to its installed location, which by default is
|
|---|
| 38 |
|
|---|
| 39 | /usr/local/lib/ossl-modules/fips.so on Unix, and
|
|---|
| 40 | C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll on Windows.
|
|---|
| 41 |
|
|---|
| 42 | In the second step, the `openssl fipsinstall` command is executed, which completes
|
|---|
| 43 | the installation by doing the following two things:
|
|---|
| 44 |
|
|---|
| 45 | - Runs the FIPS module self tests
|
|---|
| 46 | - Generates the so-called FIPS module configuration file containing information
|
|---|
| 47 | about the module such as the self test status, and the module checksum.
|
|---|
| 48 |
|
|---|
| 49 | The FIPS module must have the self tests run, and the FIPS module config file
|
|---|
| 50 | output generated on every machine that it is to be used on. You must not copy
|
|---|
| 51 | the FIPS module config file output data from one machine to another.
|
|---|
| 52 |
|
|---|
| 53 | On Unix the `openssl fipsinstall` command will be invoked as follows by default:
|
|---|
| 54 |
|
|---|
| 55 | $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
|
|---|
| 56 |
|
|---|
| 57 | If you configured OpenSSL to be installed to a different location, the paths will
|
|---|
| 58 | vary accordingly. In the rare case that you need to install the fipsmodule.cnf
|
|---|
| 59 | to non-standard location, you can execute the `openssl fipsinstall` command manually.
|
|---|
| 60 |
|
|---|
| 61 | Using the FIPS Module in applications
|
|---|
| 62 | =====================================
|
|---|
| 63 |
|
|---|
| 64 | Documentation about using the FIPS module is available on the [fips_module(7)]
|
|---|
| 65 | manual page.
|
|---|
| 66 |
|
|---|
| 67 | [fips_module(7)]: https://www.openssl.org/docs/man3.0/man7/fips_module.html
|
|---|
