From nobody Sun Oct 08 18:03:22 2023 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4S3VQL5gygz4wkgW for ; Sun, 8 Oct 2023 18:03:22 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4S3VQL3FfYz3dr2; Sun, 8 Oct 2023 18:03:22 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1696788202; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=AchKs00ZsW99jex9NybxkUrZOkcgJ+QA7I9MKep32AI=; b=yoz9vE7aTfMNnlTgdrLz2TLpRqhqgTr7oMj5n3e92EbFpJPcNFRStONb9a1WTII+6pF6j/ fgtACujicgfh9kTWbxbzlXXlamov9ir3hvMlUcdtEL3/HWhOka1DtxPNkH+WBCWA0YBl+h JYGlmFDB5VRZgbqmAYf/4sZeFyas59TMoESV2+I/Zbtcuplvz5TkGYFab2sSqfDE6VVUwJ HU88jSeNfS1r+SB0rKr8bZVP9+IN9s7nInfiq7Wce6++Adb3cwaqwiRntJfWHZ86qyZZhj KPvI/tmSy4t/XfejGVW/NgTM29GINbJNKma6BX96/60H7hE7rU2QTV61iNJH1w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1696788202; a=rsa-sha256; cv=none; b=PXBpuXDWQglC6kUNX2Mal2Q6zuJwtr1Imaufa/eFPGNPXX6yeJPslmNURTtTopsCBu8MZ2 E9lZhh4quKQtd3Bx6ItF8MRsqhwfdNjGyyjQgaB1MpfQEain+o3TsAhUvo/wpOM6m30itt SOOKzBrAd9IPszeYAFM877kWnx7wgDqQf7Wy9L6vGXaQJ+sIWMxKMC0kF3HqFDjtIW+Rkq CKKMtRrlbJzm8D5j+set/nLSp4sucdLe1JpGbYC9rE+cbcdGGqDvEfp6VVCnF41orGN0eL LOKwUTPM1+U+7cs1Y5tGD+4BVGgqauLPFDYDKYj0OYx0Yw0lYs+tUNYb8FWlXw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1696788202; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=AchKs00ZsW99jex9NybxkUrZOkcgJ+QA7I9MKep32AI=; b=QDz43/n/H3txCOjhvKHXzbLOqnPpjIQkwAg6AmA1ofLTBoE47qNYwnwVuYxpyZIWq4IbYi GjrDv+gDpj5GCJPSCHI9zr5ok/itGVdJa2qK2p2aBLrnUKEvoBFkmF07FRXnfsB6LJhwhY F3/xNn9isWZmZWjoksGoxnBO2GK8xJWu/JdLAr5RRNVwREw241S/efFcNTFxrv2pN92+1T eWn5fr7/jib1cQ0k/8wItiW1rM9E01Y1h8h7g4Wh81BV63tZEeSzoxd/Y/2QP9thc1TkVb rH9EZggameYOJVu5e/f97JfToQvDG79xUVkniXhPHt34CfDENcmLt6Gzdf3ZqA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4S3VQL2KGpz7YS; Sun, 8 Oct 2023 18:03:22 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 398I3M3Y056323; Sun, 8 Oct 2023 18:03:22 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 398I3MsW056320; Sun, 8 Oct 2023 18:03:22 GMT (envelope-from git) Date: Sun, 8 Oct 2023 18:03:22 GMT Message-Id: <202310081803.398I3MsW056320@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: fb21a60804 - main - Handbook - Security: document OpenSSL's FIPS provider List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: fb21a60804dfd1cfbb8f00afc4439bb3e5001cca Auto-Submitted: auto-generated The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=fb21a60804dfd1cfbb8f00afc4439bb3e5001cca commit fb21a60804dfd1cfbb8f00afc4439bb3e5001cca Author: Pierre Pronchery AuthorDate: 2023-10-08 18:02:26 +0000 Commit: Sergio Carlavilla Delgado CommitDate: 2023-10-08 18:02:26 +0000 Handbook - Security: document OpenSSL's FIPS provider Pull Request: https://github.com/freebsd/freebsd-doc/pull/264 --- .../content/en/books/handbook/security/_index.adoc | 101 +++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc index 78d502c2e6..252f417fc7 100644 --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -1062,6 +1062,107 @@ 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 +.... + +The ouput should be similar to the following: + +[.programlisting] +.... +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 +.... + +The ouput should be similar to the following: + +[.programlisting] +.... +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 +.... + +The ouput should be similar to the following: + +[.programlisting] +.... +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