README-FIPS.md

   1 OpenSSL FIPS support
   2 ====================
   3
   4 This release of OpenSSL includes a cryptographic module that can 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 A cryptographic module is only FIPS validated after it has gone through the complex
  11 FIPS 140 validation process. As this process takes a very long time, it is not
  12 possible to validate every minor release of OpenSSL.
  13 If you need a FIPS validated module then you must ONLY generate a FIPS provider
  14 using OpenSSL versions that have valid FIPS certificates. A FIPS certificate
  15 contains a link to a Security Policy, and you MUST follow the instructions
  16 in the Security Policy in order to be FIPS compliant.
  17 See <https://www.openssl.org/source/> for information related to OpenSSL
  18 FIPS certificates and Security Policies.
  19
  20 Newer OpenSSL Releases that include security or bug fixes can be used to build
  21 all other components (such as the core API's, TLS and the default, base and
  22 legacy providers) without any restrictions, but the FIPS provider must be built
  23 as specified in the Security Policy (normally with a different version of the
  24 source code).
  25
  26 The OpenSSL FIPS provider is a shared library called `fips.so` (on Unix), or
  27 resp. `fips.dll` (on Windows). The FIPS provider does not get built and
  28 installed automatically. To enable it, you need to configure OpenSSL using
  29 the `enable-fips` option.
  30
  31 Installing the FIPS module
  32 ==========================
  33
  34 The following is only a guide.
  35 Please read the Security Policy for up to date installation instructions.
  36
  37 If the FIPS provider is enabled, it gets installed automatically during the
  38 normal installation process. Simply follow the normal procedure (configure,
  39 make, make test, make install) as described in the [INSTALL](INSTALL.md) file.
  40
  41 For example, on Unix the final command
  42
  43     $ make install
  44
  45 effectively executes the following install targets
  46
  47     $ make install_sw
  48     $ make install_ssldirs
  49     $ make install_docs
  50     $ make install_fips     # for `enable-fips` only
  51
  52 The `install_fips` make target can also be invoked explicitly to install
  53 the FIPS provider independently, without installing the rest of OpenSSL.
  54
  55 The Installation of the FIPS provider consists of two steps. In the first step,
  56 the shared library is copied to its installed location, which by default is
  57
  58     /usr/local/lib/ossl-modules/fips.so                  on Unix, and
  59     C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll   on Windows.
  60
  61 In the second step, the `openssl fipsinstall` command is executed, which completes
  62 the installation by doing the following two things:
  63
  64 - Runs the FIPS module self tests
  65 - Generates the so-called FIPS module configuration file containing information
  66   about the module such as the self test status, and the module checksum.
  67
  68 The FIPS module must have the self tests run, and the FIPS module config file
  69 output generated on every machine that it is to be used on. You must not copy
  70 the FIPS module config file output data from one machine to another.
  71
  72 On Unix, the `openssl fipsinstall` command will be invoked as follows by default:
  73
  74     $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
  75
  76 If you configured OpenSSL to be installed to a different location, the paths will
  77 vary accordingly. In the rare case that you need to install the fipsmodule.cnf
  78 to non-standard location, you can execute the `openssl fipsinstall` command manually.
  79
  80 Using the FIPS Module in applications
  81 =====================================
  82
  83 Documentation about using the FIPS module is available on the [fips_module(7)]
  84 manual page.
  85
  86  [fips_module(7)]: https://www.openssl.org/docs/manmaster/man7/fips_module.html