README-FIPS.md

   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/manmaster/man7/fips_module.html