Handbook - Security: document OpenSSL's FIPS provider

The new FIPS provider module from OpenSSL 3 is protected from use
without passing an integrity check, which is expected to be configured
by the local system administrator.

This new section documents a way to configure this on FreeBSD, so that
every user on the system is allowed to pass this check and use the FIPS
module.

documentation/content/en/books/handbook/security/_index.adoc

@@ -1062,6 +1062,89 @@ Common Name (e.g. server FQDN or YOUR name) []:localhost.example.org
 Email Address []:user@FreeBSD.org
 ....
 
+[[fips-provider]]
+=== Configuring the FIPS Provider
+
+With the import of OpenSSL 3 into the base system (on FreeBSD 14 and later), its new concept of provider modules was introduced in the system.
+Besides the default provider module built-in to the library, the _legacy_ module implements the now optional deprecated cryptography algorithms, while the _fips_ module restricts the OpenSSL implementation to the cryptography algorithms present in the link:https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards[FIPS] set of standards.
+This part of OpenSSL receives link:https://www.openssl.org/docs/fips.html[particular care], including a link:https://www.openssl.org/news/fips-cve.html[list of relevant security issues], and is subject to the link:https://github.com/openssl/openssl/blob/master/README-FIPS.md[FIPS 140 validation process] on a regular basis.
+The link:https://www.openssl.org/source/[list of FIPS validated versions] is also available.
+This allows users to ensure FIPS compliance in their use of OpenSSL.
+
+Importantly, the man:fips_module[7] is protected by an additional security measure, preventing its use without passing an integrity check.
+This check can be setup by the local system administrator, allowing every user of OpenSSL 3 to load this module.
+When not configured correctly, the FIPS module is expected to fail as follows:
+
+[source,shell]
+....
+# echo test | openssl aes-128-cbc -a -provider fips -pbkdf2
+aes-128-cbc: unable to load provider fips
+Hint: use -provider-path option or OPENSSL_MODULES environment variable.
+00206124D94D0000:error:1C8000D5:Provider routines:SELF_TEST_post:missing config data:crypto/openssl/providers/fips/self_test.c:275:
+00206124D94D0000:error:1C8000E0:Provider routines:ossl_set_error_state:fips module entering error state:crypto/openssl/providers/fips/self_test.c:373:
+00206124D94D0000:error:1C8000D8:Provider routines:OSSL_provider_init_int:self test post failure:crypto/openssl/providers/fips/fipsprov.c:707:
+00206124D94D0000:error:078C0105:common libcrypto routines:provider_init:init fail:crypto/openssl/crypto/provider_core.c:932:name=fips
+....
+
+The check can be configured through the creation of a file in [.filename]#/etc/ssl/fipsmodule.cnf#, which will then be referenced in OpenSSL's main configuration file [.filename]#/etc/ssl/openssl.cnf#.
+OpenSSL provides the man:openssl-fipsinstall[1] utility to help with this process, which can be used as follows:
+
+[source,shell]
+....
+# openssl fipsinstall -module /usr/lib/ossl-modules/fips.so -out /etc/ssl/fipsmodule.cnf
+INSTALL PASSED
+....
+
+The [.filename]#/etc/ssl/openssl.cnf# should then be modified, in order to:
+
+* Include the [.filename]#/etc/ssl/fipsmodule.cnf# file generated above,
+* Expose the FIPS module for possible use,
+* And explicitly activate the default module.
+
+[.programlisting]
+....
+[...]
+# For FIPS
+# Optionally include a file that is generated by the OpenSSL fipsinstall
+# application. This file contains configuration data required by the OpenSSL
+# fips provider. It contains a named section e.g. [fips_sect] which is
+# referenced from the [provider_sect] below.
+# Refer to the OpenSSL security policy for more information.
+.include /etc/ssl/fipsmodule.cnf
+
+[...]
+
+# List of providers to load
+[provider_sect]
+default = default_sect
+# The fips section name should match the section name inside the
+# included fipsmodule.cnf.
+fips = fips_sect
+
+# If no providers are activated explicitly, the default one is activated implicitly.
+# See man 7 OSSL_PROVIDER-default for more details.
+#
+# If you add a section explicitly activating any other provider(s), you most
+# probably need to explicitly activate the default provider, otherwise it
+# becomes unavailable in openssl.  As a consequence applications depending on
+# OpenSSL may not work correctly which could lead to significant system
+# problems including inability to remotely access the system.
+[default_sect]
+activate = 1
+....
+
+With this done, it should be possible to confirm that the FIPS module is effectively available and working:
+
+[source,shell]
+....
+# echo test | openssl aes-128-cbc -a -provider fips -pbkdf2
+enter AES-128-CBC encryption password:
+Verifying - enter AES-128-CBC encryption password:
+U2FsdGVkX18idooW6e3LqWeeiKP76kufcOUClh57j8U=
+....
+
+This procedure has to be repeated every time the FIPS module is modified, e.g., after performing system updates, or after applying security fixes affecting OpenSSL in the base system.
+
 [[kerberos5]]
 == Kerberos