From 8353b2dfacd723db5ba8b833b95e68e9600d1cf5 Mon Sep 17 00:00:00 2001 From: Pauli Date: Thu, 19 Jan 2023 11:16:40 +1100 Subject: [PATCH] fips: document that the EdDSA algorithms are not-validated Ed25519 and Ed448 are included in the FIPS 140-3 provider for compatibility purposes but are flagged as "fips=no" to prevent their accidental use. This therefore requires that applications always specify the "fips=yes" property query to enforce FIPS correctness. Reviewed-by: Tomas Mraz Reviewed-by: Hugo Landau (Merged from https://github.com/openssl/openssl/pull/20079) --- doc/man7/OSSL_PROVIDER-FIPS.pod | 22 ++++++++++++++++++++-- doc/man7/fips_module.pod | 32 +++++++++++++++++++++++++++++++- doc/man7/migration_guide.pod | 14 +++++++++++++- 3 files changed, 64 insertions(+), 4 deletions(-) diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod index 494878a866..b73728e294 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -7,7 +7,7 @@ OSSL_PROVIDER-FIPS - OpenSSL FIPS provider =head1 DESCRIPTION The OpenSSL FIPS provider is a special provider that conforms to the Federal -Information Processing Standards (FIPS) specified in FIPS 140-2. This 'module' +Information Processing Standards (FIPS) specified in FIPS 140-3. This 'module' contains an approved set of cryptographic algorithms that is validated by an accredited testing laboratory. @@ -32,7 +32,7 @@ L. It isn't mandatory to query for any of these properties, except to make sure to get implementations of this provider and none other. -The "fips=yes" property can be use to make sure only FIPS approved +The C property can be use to make sure only FIPS approved implementations are used for crypto operations. This may also include other non-crypto support operations that are not in the FIPS provider, such as asymmetric key encoders, @@ -390,6 +390,20 @@ A simple self test callback is shown below for illustrative purposes. return ret; } +=head1 NOTES + +The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, +consequently the property query C is mandatory for applications that +want to operate in a FIPS approved manner. The algorithms are: + +=over 4 + +=item Triple DES + +=item EdDSA + +=back + =head1 SEE ALSO L, @@ -405,6 +419,10 @@ L This functionality was added in OpenSSL 3.0. +OpenSSL 3.0 includes a FIPS 140-2 approved FIPS provider. + +OpenSSL 3.1 includes a FIPS 140-3 approved FIPS provider. + =head1 COPYRIGHT Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod index 3eda2b6ed9..8eee14ca55 100644 --- a/doc/man7/fips_module.pod +++ b/doc/man7/fips_module.pod @@ -80,6 +80,7 @@ Edit the config file to add the following lines near the beginning: [openssl_init] providers = provider_sect + alg_section = algorithm_sect [provider_sect] fips = fips_sect @@ -88,6 +89,9 @@ Edit the config file to add the following lines near the beginning: [base_sect] activate = 1 + [algorithm_sect] + default_properties = fips=yes + Obviously the include file location above should match the path and name of the FIPS module config file that you installed earlier. See L. @@ -330,6 +334,14 @@ base providers. The other library context will just use the default provider. if (!OSSL_LIB_CTX_load_config(fips_libctx, "openssl-fips.cnf")) goto err; + /* + * Set the default property query on the FIPS library context to + * ensure that only FIPS algorithms can be used. There are a few non-FIPS + * approved algorithms in the FIPS provider for backward compatibility reasons. + */ + if (!EVP_set_default_properties(fips_libctx, "fips=yes")) + goto err; + /* * We don't need to do anything special to load the default * provider into nonfips_libctx. This happens automatically if no @@ -419,7 +431,7 @@ contexts. * We assume that a nondefault 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()); + SSL_CTX *fips_ssl_ctx = SSL_CTX_new_ex(fips_libctx, "fips=yes", TLS_method()); /* * We assume that a nondefault library context with the default * provider loaded has been created called non_fips_libctx. @@ -456,6 +468,20 @@ use L. To extract the name from the B, use L. +=head1 NOTES + +The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, +consequently the property query C is mandatory for applications that +want to operate in a FIPS approved manner. The algorithms are: + +=over 4 + +=item Triple DES + +=item EdDSA + +=back + =head1 SEE ALSO L, L, L @@ -465,6 +491,10 @@ L, L, L The FIPS module guide was created for use with the new FIPS provider in OpenSSL 3.0. +OpenSSL 3.0 includes a FIPS 140-2 approved FIPS provider. + +OpenSSL 3.1 includes a FIPS 140-3 approved FIPS provider. + =head1 COPYRIGHT Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod index 8bd44a6ce7..e82471370f 100644 --- a/doc/man7/migration_guide.pod +++ b/doc/man7/migration_guide.pod @@ -20,7 +20,19 @@ L. =head2 Main Changes from OpenSSL 3.0 -There are no changes requiring additional migration measures since OpenSSL 3.0. +The FIPS provider in OpenSSL 3.1 includes some non-FIPS validated algorithms, +consequently the property query C is mandatory for applications that +want to operate in a FIPS approved manner. The algorithms are: + +=over 4 + +=item Triple DES + +=item EdDSA + +=back + +There are no other changes requiring additional migration measures since OpenSSL 3.0. =head1 OPENSSL 3.0 -- 2.34.1