mirror of
https://github.com/openssl/openssl.git
synced 2024-11-27 03:54:14 +08:00
Update README-FIPS.md
The README-FIPS.md file was still the one used from 1.1.1. We update it with 3.0 specific information. Fixes #14237 Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14575)
This commit is contained in:
Matt Caswell
Pauli
parent
9fe4f5bc82
commit
2154a7a754
443
README-FIPS.md
443
README-FIPS.md
@ -1,4 +1,445 @@
|
||||
OpenSSL FIPS support
|
||||
====================
|
||||
|
||||
This release does not support a FIPS 140-2 validated module.
|
||||
This release of OpenSSL includes a cryptographic module that is intended to be
|
||||
FIPS 140-2 validated. The module is implemented as an OpenSSL provider. See
|
||||
the [README-PROVIDERS](README-PROVIDERS.md) file for further details about
|
||||
providers.
|
||||
|
||||
Installing the FIPS module
|
||||
==========================
|
||||
|
||||
Once OpenSSL has been built and installed you will need to take explicit steps
|
||||
to complete the installation of the FIPS module (if you wish to use it). The
|
||||
OpenSSL 3.0 FIPS support is in the form of the FIPS provider which, on Unix, is
|
||||
in a `fips.so` file. On Windows this will be called `fips.dll`. Following
|
||||
installation of OpenSSL 3.0 the default location for this file is
|
||||
`/usr/local/lib/ossl-modules/fips.so` on Unix or
|
||||
`C:\Program Files\OpenSSL\lib\ossl-modules\fips.dll` on Windows.
|
||||
|
||||
To complete the installation you need to run the `fipsinstall` command line
|
||||
application. This does 2 things:
|
||||
|
||||
- Runs the FIPS module self tests
|
||||
- Generates FIPS module config file output containing information about the
|
||||
module such as the self test status, and the module checksum.
|
||||
|
||||
The FIPS module must have the self tests run, and the FIPS module config file
|
||||
output generated on every machine that it is to be used on. You must not copy
|
||||
the FIPS module config file output data from one machine to another.
|
||||
|
||||
For example, to install the FIPS module to its default location on Unix:
|
||||
|
||||
$ openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib/ossl-modules/fips.so
|
||||
|
||||
If you installed OpenSSL to a different location, you need to adjust the output
|
||||
and module path accordingly.
|
||||
|
||||
|
||||
Using the FIPS Module in applications
|
||||
=====================================
|
||||
|
||||
There are a number of different ways that OpenSSL can be used in conjunction
|
||||
with the FIPS module. Which is the correct approach to use will depend on your
|
||||
own specific circumstances and what you are attempting to achieve. Note that the
|
||||
old functions `FIPS_mode()` and `FIPS_mode_set()` are no longer present so you
|
||||
must remove them from your application if you use them.
|
||||
|
||||
Applications written to use the OpenSSL 3.0 FIPS module should not use any
|
||||
legacy APIs or features that avoid the FIPS module. Specifically this includes:
|
||||
|
||||
- Low level cryptographic APIs (use the high level APIs, such as EVP, instead)
|
||||
- Engines
|
||||
- Any functions that create or modify custom "METHODS" (for example
|
||||
`EVP_MD_meth_new`, `EVP_CIPHER_meth_new`, `EVP_PKEY_meth_new`, `RSA_meth_new`,
|
||||
`EC_KEY_METHOD_new`, etc.)
|
||||
|
||||
All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
|
||||
avoid using all deprecated functions.
|
||||
|
||||
Making all applications use the FIPS module by default
|
||||
------------------------------------------------------
|
||||
|
||||
One simple approach is to cause all applications that are using OpenSSL to only
|
||||
use the FIPS module for cryptographic algorithms by default.
|
||||
|
||||
This approach can be done purely via configuration. As long as applications are
|
||||
built and linked against OpenSSL 3.0 and do not override the loading of the
|
||||
default config file or its settings then they can automatically start using the
|
||||
FIPS module without the need for any further code changes.
|
||||
|
||||
To do this the default OpenSSL config file will have to be modified. The
|
||||
location of this config file will depend on the platform, and any options that
|
||||
were given during the build process. You can check the location of the config
|
||||
file by running this command:
|
||||
|
||||
$ openssl version -d
|
||||
OPENSSLDIR: "/usr/local/ssl"
|
||||
|
||||
Caution: Many Operating Systems install OpenSSL by default. It is a common error
|
||||
to not have the correct version of OpenSSL on your $PATH. Check that you are
|
||||
running an OpenSSL 3.0 version like this:
|
||||
|
||||
$ openssl version -v
|
||||
OpenSSL 3.0.0-dev xx XXX xxxx (Library: OpenSSL 3.0.0-dev xx XXX xxxx)
|
||||
|
||||
The OPENSSLDIR value above gives the directory name for where the default config
|
||||
file is stored. So in this case the default config file will be called
|
||||
`/usr/local/ssl/openssl.cnf`
|
||||
|
||||
Edit the config file to add the following lines near the beginning:
|
||||
|
||||
openssl_conf = openssl_init
|
||||
|
||||
.include /usr/local/ssl/fipsmodule.cnf
|
||||
|
||||
[openssl_init]
|
||||
providers = provider_sect
|
||||
|
||||
[provider_sect]
|
||||
fips = fips_sect
|
||||
base = base_sect
|
||||
|
||||
[base_sect]
|
||||
activate = 1
|
||||
|
||||
Obviously the include file location above should match the name of the FIPS
|
||||
module config file that you installed earlier.
|
||||
|
||||
Any applications that use OpenSSL 3.0 and are started after these changes are
|
||||
made will start using only the FIPS module unless those applications take
|
||||
explicit steps to avoid this default behaviour. Note that this configuration
|
||||
also activates the "base" provider. The base provider does not include any
|
||||
cryptographic algorithms (and therefore does not impact the validation status of
|
||||
any cryptographic operations), but does include other supporting algorithms that
|
||||
may be required. It is designed to be used in conjunction with the FIPS module.
|
||||
|
||||
This approach has the primary advantage that it is simple, and no code changes
|
||||
are required in applications in order to benefit from the FIPS module. There are
|
||||
some disadvantages to this approach:
|
||||
|
||||
- You may not want all applications to use the FIPS module. It may be the case
|
||||
that some applications should and some should not.
|
||||
- If applications take explicit steps to not load the default config file or set
|
||||
different settings then this method will not work for them
|
||||
- The algorithms available in the FIPS module are a subset of the algorithms
|
||||
that are available in the default OpenSSL Provider. If those applications
|
||||
attempt to use any algorithms that are not present, then they will fail.
|
||||
- Usage of certain deprecated APIs avoids the use of the FIPS module. If any
|
||||
applications use those APIs then the FIPS module will not be used.
|
||||
|
||||
Selectively making applications use the FIPS module by default
|
||||
--------------------------------------------------------------
|
||||
|
||||
A variation on the above approach is to do the same thing on an individual
|
||||
application basis. The default OpenSSL config file depends on the compiled in
|
||||
value for OPENSSLDIR as described in the section above. However it is also
|
||||
possible to override the config file to be used via the `OPENSSL_CONF`
|
||||
environment variable. For example the following on Unix will cause the
|
||||
application to be executed with a non-standard config file location:
|
||||
|
||||
$ OPENSSL_CONF=/my/non-default/openssl.cnf myapplication
|
||||
|
||||
Using this mechanism you can control which config file is loaded (and hence
|
||||
whether the FIPS module is loaded) on an application by application basis.
|
||||
|
||||
This removes the disadvantage listed above that you may not want all
|
||||
applications to use the FIPS module. All the other advantages and disadvantages
|
||||
still apply.
|
||||
|
||||
Programmatically loading the FIPS module (default library context)
|
||||
------------------------------------------------------------------
|
||||
|
||||
Applications may choose to load the FIPS provider explicitly rather than relying
|
||||
on config to do this. The config file is still necessary in order to hold the
|
||||
FIPS module config data (such as its self test status and integrity data). But
|
||||
in this case we do not automatically activate the FIPS provider via that config
|
||||
file.
|
||||
|
||||
To do things this way configure as per the section "Making all applications use
|
||||
the FIPS module by default" above, but edit the `fipsmodule.cnf` file to remove
|
||||
or comment out the line which says `activate = 1` (note that setting this value
|
||||
to 0 is **not** sufficient). This means all the required config information will
|
||||
be available to load the FIPS module, but it is not actually automatically
|
||||
loaded when the application starts. The FIPS provider can then be loaded
|
||||
programmatically like this:
|
||||
|
||||
#include <openssl/provider.h>
|
||||
|
||||
int main(void)
|
||||
{
|
||||
OSSL_PROVIDER *fips;
|
||||
OSSL_PROVIDER *base;
|
||||
|
||||
fips = OSSL_PROVIDER_load(NULL, "fips");
|
||||
if (fips == NULL) {
|
||||
printf("Failed to load FIPS provider\n");
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
base = OSSL_PROVIDER_load(NULL, "base");
|
||||
if (base == NULL) {
|
||||
OSSL_PROVIDER_unload(fips);
|
||||
printf("Failed to load base provider\n");
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
|
||||
/* Rest of application */
|
||||
|
||||
OSSL_PROVIDER_unload(base);
|
||||
OSSL_PROVIDER_unload(fips);
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
|
||||
Note that this should be one of the first things that you do in your
|
||||
application. If any OpenSSL functions get called that require the use of
|
||||
cryptographic functions before this occurs then, if no provider has yet been
|
||||
loaded, then the default provider will be automatically loaded. If you then
|
||||
later explicitly load the FIPS provider then you will have both the FIPS and the
|
||||
default provider loaded at the same time. It is undefined which implementation
|
||||
of an algorithm will be used if multiple implementations are available and you
|
||||
have not explicitly specified via a property query (see below) which one should
|
||||
be used.
|
||||
|
||||
Also note that in this example we have additionally loaded the "base" provider.
|
||||
This loads a sub-set of algorithms that are also available in the default
|
||||
provider - specifically non cryptographic ones which may be used in conjunction
|
||||
with the FIPS provider. For example this contains algorithms for encoding and
|
||||
decoding keys. If you decide not to load the default provider then you
|
||||
will usually want to load the base provider instead.
|
||||
|
||||
In this example we are using the "default" library context. OpenSSL functions
|
||||
operate within the scope of a library context. If no library context is
|
||||
explicitly specified then the default library context is used. For further
|
||||
details about library contexts see the `OSSL_LIB_CTX(3)` man page.
|
||||
|
||||
Loading the FIPS module at the same time as other providers
|
||||
-----------------------------------------------------------
|
||||
|
||||
It is possible to have the FIPS provider and other providers (such as the
|
||||
default provider) all loaded at the same time into the same library context. You
|
||||
can use a property query string during algorithm fetches to specify which
|
||||
implementation you would like to use.
|
||||
|
||||
For example to fetch an implementation of SHA256 which conforms to FIPS
|
||||
standards you can specify the property query `fips=yes` like this:
|
||||
|
||||
EVP_MD *sha256;
|
||||
|
||||
sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");
|
||||
|
||||
If no property query is specified, or more than one implementation matches the
|
||||
property query then it is undefined which implementation of a particular
|
||||
algorithm will be returned.
|
||||
|
||||
This example shows an explicit request for an implementation of SHA256 from the
|
||||
default provider:
|
||||
|
||||
EVP_MD *sha256;
|
||||
|
||||
sha256 = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
|
||||
|
||||
It is also possible to set a default property query string. The following
|
||||
example sets the default property query of "fips=yes" for all fetches within the
|
||||
default library context:
|
||||
|
||||
EVP_set_default_properties(NULL, "fips=yes");
|
||||
|
||||
If a fetch function has both an explicit property query specified, and a
|
||||
default property query is defined then the two queries are merged together and
|
||||
both apply. The local property query overrides the default properties if the
|
||||
same property name is specified in both.
|
||||
|
||||
There are two important built-in properties that you should be aware of:
|
||||
|
||||
The "provider" property enables you to specify which provider you want an
|
||||
implementation to be fetched from, e.g. `provider=default` or `provider=fips`.
|
||||
All algorithms implemented in a provider have this property set on them.
|
||||
|
||||
There is also the `fips` property. All FIPS algorithms match against the
|
||||
property query `fips=yes`. There are also some non-cryptographic algorithms
|
||||
available in the default and base providers that also have the `fips=yes`
|
||||
property defined for them. These are the encoder and decoder algorithms that
|
||||
can (for example) be used to write out a key generated in the FIPS provider to a
|
||||
file. The encoder and decoder algorithms are not in the FIPS module itself but
|
||||
are allowed to be used in conjunction with the FIPS algorithms.
|
||||
|
||||
It is possible to specify default properties within a config file. For example
|
||||
the following config file automatically loads the default and fips providers and
|
||||
sets the default property value to be `fips=yes`. Note that this config file
|
||||
does not load the "base" provider. All supporting algorithms that are in "base"
|
||||
are also in "default", so it is unnecessary in this case:
|
||||
|
||||
openssl_conf = openssl_init
|
||||
|
||||
.include /usr/local/ssl/fipsmodule.cnf
|
||||
|
||||
[openssl_init]
|
||||
providers = provider_sect
|
||||
alg_section = algorithm_sect
|
||||
|
||||
[provider_sect]
|
||||
fips = fips_sect
|
||||
default = default_sect
|
||||
|
||||
[default_sect]
|
||||
activate = 1
|
||||
|
||||
[algorithm_sect]
|
||||
default_properties = fips=yes
|
||||
|
||||
Programmatically loading the FIPS module (non-default library context)
|
||||
----------------------------------------------------------------------
|
||||
|
||||
In addition to using properties to separate usage of the FIPS module from other
|
||||
usages this can also be achieved using library contexts. In this example we
|
||||
create two library contexts. In one we assume the existence of a config file
|
||||
called "openssl-fips.cnf" that automatically loads and configures the FIPS and
|
||||
base providers. The other library context will just use the default provider.
|
||||
|
||||
OSSL_LIB_CTX *fipslibctx, *nonfipslibctx;
|
||||
OSSL_PROVIDER *defctxnull = NULL;
|
||||
EVP_MD *fipssha256 = NULL, *nonfipssha256 = NULL;
|
||||
int ret = 1;
|
||||
|
||||
/*
|
||||
* Create two non-default library contexts. One for fips usage and one for
|
||||
* non-fips usage
|
||||
*/
|
||||
fipslibctx = OSSL_LIB_CTX_new();
|
||||
nonfipslibctx = OSSL_LIB_CTX_new();
|
||||
if (fipslibctx == NULL || nonfipslibctx == NULL)
|
||||
goto err;
|
||||
|
||||
/* Prevent anything from using the default library context */
|
||||
defctxnull = OSSL_PROVIDER_load(NULL, "null");
|
||||
|
||||
/*
|
||||
* Load config file for the FIPS library context. We assume that this
|
||||
* config file will automatically activate the FIPS and base providers so we
|
||||
* don't need to explicitly load them here.
|
||||
*/
|
||||
if (!OSSL_LIB_CTX_load_config(fipslibctx, "openssl-fips.cnf"))
|
||||
goto err;
|
||||
|
||||
/*
|
||||
* We don't need to do anything special to load the default provider into
|
||||
* nonfipslibctx. This happens automatically if no other providers are
|
||||
* loaded. Because we don't call OSSL_LIB_CTX_load_config() explicitly for
|
||||
* nonfipslibctx it will just use the default config file.
|
||||
*/
|
||||
|
||||
/* As an example get some digests */
|
||||
|
||||
/* Get a FIPS validated digest */
|
||||
fipssha256 = EVP_MD_fetch(fipslibctx, "SHA2-256", NULL);
|
||||
if (fipssha256 == NULL)
|
||||
goto err;
|
||||
|
||||
/* Get a non-FIPS validated digest */
|
||||
nonfipssha256 = EVP_MD_fetch(nonfipslibctx, "SHA2-256", NULL);
|
||||
if (nonfipssha256 == NULL)
|
||||
goto err;
|
||||
|
||||
/* Use the digests */
|
||||
|
||||
printf("Success\n");
|
||||
ret = 0;
|
||||
|
||||
err:
|
||||
EVP_MD_free(fipssha256);
|
||||
EVP_MD_free(nonfipssha256);
|
||||
OSSL_LIB_CTX_free(fipslibctx);
|
||||
OSSL_LIB_CTX_free(nonfipslibctx);
|
||||
OSSL_PROVIDER_unload(defctxnull);
|
||||
|
||||
return ret;
|
||||
|
||||
Note that we have made use of the special "null" provider here which we load
|
||||
into the default library context. We could have chosen to use the default
|
||||
library context for FIPS usage, and just create one additional library context
|
||||
for other usages - or vice versa. However if code has not been converted to use
|
||||
library contexts then the default library context will be automatically used.
|
||||
This could be the case for your own existing applications as well as certain
|
||||
parts of OpenSSL itself. Not all parts of OpenSSL are library context aware. If
|
||||
this happens then you could "accidentally" use the wrong library context for a
|
||||
particular operation. To be sure this doesn't happen you can load the "null"
|
||||
provider into the default library context. Because a provider has been
|
||||
explicitly loaded, the default provider will not automatically load. This means
|
||||
code using the default context by accident will fail because no algorithms will
|
||||
be available.
|
||||
|
||||
Using Encoders and Decoders with the FIPS module
|
||||
------------------------------------------------
|
||||
|
||||
Encoders and decoders are used to read and write keys or parameters from or to
|
||||
some external format (for example a PEM file). If your application generates
|
||||
keys or parameters that then need to be written into PEM or DER format
|
||||
then it is likely that you will need to use an encoder to do this. Similarly
|
||||
you need a decoder to read previously saved keys and parameters. In most cases
|
||||
this will be invisible to you if you are using APIs that existed in
|
||||
OpenSSL 1.1.1 or earlier such as i2d_PrivateKey. However the appropriate
|
||||
encoder/decoder will need to be available in the library context associated with
|
||||
the key or parameter object. The built-in OpenSSL encoders and decoders are
|
||||
implemented in both the default and base providers and are not in the FIPS
|
||||
module boundary. However since they are not cryptographic algorithms themselves
|
||||
it is still possible to use them in conjunction with the FIPS module, and
|
||||
therefore these encoders/decoders have the "fips=yes" property against them.
|
||||
You should ensure that either the default or base provider is loaded into the
|
||||
library context in this case.
|
||||
|
||||
Using the FIPS module in SSL/TLS
|
||||
--------------------------------
|
||||
|
||||
Writing an application that uses libssl in conjunction with the FIPS module is
|
||||
much the same as writing a normal libssl application. If you are using global
|
||||
properties and the default library context to specify usage of FIPS validated
|
||||
algorithms then this will happen automatically for all cryptographic algorithms
|
||||
in libssl. If you are using a non-default library context to load the FIPS
|
||||
provider then you can supply this to libssl using the function
|
||||
`SSL_CTX_new_ex()`. This works as a drop in replacement for the function
|
||||
`SSL_CTX_new()` except it provides you with the capability to specify the
|
||||
library context to be used. You can also use the same function to specify
|
||||
libssl specific properties to use.
|
||||
|
||||
In this first example we create two SSL_CTX objects using two different library
|
||||
contexts.
|
||||
|
||||
/*
|
||||
* We assume that a non-default library context with the FIPS provider
|
||||
* loaded has been created called fips_libctx.
|
||||
/
|
||||
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, NULL, TLS_method());
|
||||
/*
|
||||
* We assume that a non-default library context with the default provider
|
||||
* loaded has been created called non_fips_libctx.
|
||||
*/
|
||||
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(non_fips_libctx, NULL,
|
||||
TLS_method());
|
||||
|
||||
In this second example we create two SSL_CTX objects using different properties
|
||||
to specify FIPS usage:
|
||||
|
||||
/*
|
||||
* The "fips=yes" property includes all FIPS approved algorithms as well as
|
||||
* encoders from the default provider that are allowed to be used. The NULL
|
||||
* below indicates that we are using the default library context.
|
||||
*/
|
||||
SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(NULL, "fips=yes", TLS_method());
|
||||
/*
|
||||
* The "provider!=fips" property allows algorithms from any provider except
|
||||
* the FIPS provider
|
||||
*/
|
||||
SSL_CTX *non_fips_ssl_ctx = SSL_CTX_new_ex(NULL, "provider!=fips",
|
||||
TLS_method());
|
||||
|
||||
Confirming that an algorithm is being provided by the FIPS module
|
||||
-----------------------------------------------------------------
|
||||
|
||||
A chain of links needs to be followed to go from an algorithm instance to the
|
||||
provider that implements it. The process is similar for all algorithms. Here the
|
||||
example of a digest is used.
|
||||
|
||||
To go from an `EVP_MD_CTX` to an `EVP_MD`, use the `EVP_MD_CTX_md()` call. To go
|
||||
from the `EVP_MD` to its `OSSL_PROVIDER`, use the `EVP_MD_provider()` call. To
|
||||
extract the name from the `OSSL_PROVIDER`, use the `OSSL_PROVIDER_name()` call.
|
||||
Finally, use `strcmp(3)` or `printf(3)` on the name.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user