README-FIPS.md

   1 OpenSSL FIPS support
   2 ====================
   3
   4 This release of OpenSSL includes a cryptographic module that can be
   5 FIPS 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 provider
  32 ============================
  33
  34 In order to be FIPS compliant you must only use FIPS validated source code.
  35 Refer to <https://www.openssl.org/source/> for information related to
  36 which versions are FIPS validated. The instructions given below build OpenSSL
  37 just using the FIPS validated source code.
  38
  39 If you want to use a validated FIPS provider, but also want to use the latest
  40 OpenSSL release to build everything else, then refer to the next section.
  41
  42 The following is only a guide.
  43 Please read the Security Policy for up to date installation instructions.
  44
  45 If the FIPS provider is enabled, it gets installed automatically during the
  46 normal installation process. Simply follow the normal procedure (configure,
  47 make, make test, make install) as described in the [INSTALL](INSTALL.md) file.
  48
  49 For example, on Unix the final command
  50
  51     $ make install
  52
  53 effectively executes the following install targets
  54
  55     $ make install_sw
  56     $ make install_ssldirs
  57     $ make install_docs
  58     $ make install_fips     # for `enable-fips` only
  59
  60 The `install_fips` make target can also be invoked explicitly to install
  61 the FIPS provider independently, without installing the rest of OpenSSL.
  62
  63 The Installation of the FIPS provider consists of two steps. In the first step,
  64 the shared library is copied to its installed location, which by default is
  65
  66     /usr/local/lib/ossl-modules/fips.so                  on Unix, and
  67     C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll   on Windows.
  68
  69 In the second step, the `openssl fipsinstall` command is executed, which completes
  70 the installation by doing the following two things:
  71
  72 - Runs the FIPS module self tests
  73 - Generates the so-called FIPS module configuration file containing information
  74   about the module such as the module checksum (and for OpenSSL 3.0 the
  75   self test status).
  76
  77 The FIPS module must have the self tests run, and the FIPS module config file
  78 output generated on every machine that it is to be used on. For OpenSSL 3.0,
  79 you must not copy the FIPS module config file output data from one machine to another.
  80
  81 On Unix, the `openssl fipsinstall` command will be invoked as follows by default:
  82
  83     $ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
  84
  85 If you configured OpenSSL to be installed to a different location, the paths will
  86 vary accordingly. In the rare case that you need to install the fipsmodule.cnf
  87 to a non-standard location, you can execute the `openssl fipsinstall` command manually.
  88
  89 Installing the FIPS provider and using it with the latest release
  90 =================================================================
  91
  92 This normally requires you to download 2 copies of the OpenSSL source code.
  93
  94 Download and build a validated FIPS provider
  95 --------------------------------------------
  96
  97 Refer to <https://www.openssl.org/source/> for information related to
  98 which versions are FIPS validated. For this example we use OpenSSL 3.0.0.
  99
 100     $ wget https://www.openssl.org/source/openssl-3.0.0.tar.gz
 101     $ tar -xf openssl-3.0.0.tar.gz
 102     $ cd openssl-3.0.0
 103     $ ./Configure enable-fips
 104     $ make
 105     $ cd ..
 106
 107 Download and build the latest release of OpenSSL
 108 ------------------------------------------------
 109
 110 We use OpenSSL 3.1.0 here, (but you could also use the latest 3.0.X)
 111
 112     $ wget https://www.openssl.org/source/openssl-3.1.0.tar.gz
 113     $ tar -xf openssl-3.1.0.tar.gz
 114     $ cd openssl-3.1.0
 115     $ ./Configure enable-fips
 116     $ make
 117
 118 Use the OpenSSL FIPS provider for testing
 119 -----------------------------------------
 120
 121 We do this by replacing the artifact for the OpenSSL 3.1.0 FIPS provider.
 122 Note that the OpenSSL 3.1.0 FIPS provider has not been validated
 123 so it must not be used for FIPS purposes.
 124
 125     $ cp ../openssl-3.0.0/providers/fips.so providers/.
 126     $ cp ../openssl-3.0.0/providers/fipsmodule.cnf providers/.
 127     // Note that for OpenSSL 3.0 that the `fipsmodule.cnf` file should not
 128     // be copied across multiple machines if it contains an entry for
 129     // `install-status`. (Otherwise the self tests would be skipped).
 130
 131     // Validate the output of the following to make sure we are using the
 132     // OpenSSL 3.0.0 FIPS provider
 133     $ ./util/wrap.pl -fips apps/openssl list -provider-path providers \
 134     -provider fips -providers
 135
 136     // Now run the current tests using the OpenSSL 3.0 FIPS provider.
 137     $ make tests
 138
 139 Copy the FIPS provider artifacts (`fips.so` & `fipsmodule.cnf`) to known locations
 140 -------------------------------------------------------------------------------------
 141
 142     $ cd ../openssl-3.0.0
 143     $ sudo make install_fips
 144
 145 Check that the correct FIPS provider is being used
 146 --------------------------------------------------
 147
 148     $./util/wrap.pl -fips apps/openssl list -provider-path providers \
 149     -provider fips -providers
 150
 151     // This should produce the following output
 152     Providers:
 153       base
 154         name: OpenSSL Base Provider
 155         version: 3.1.0
 156         status: active
 157       fips
 158         name: OpenSSL FIPS Provider
 159         version: 3.0.0
 160         status: active
 161
 162 Using the FIPS Module in applications
 163 =====================================
 164
 165 Documentation about using the FIPS module is available on the [fips_module(7)]
 166 manual page.
 167
 168  [fips_module(7)]: https://www.openssl.org/docs/manmaster/man7/fips_module.html