From cbc42a203512e4f3da421733a5889e65affd6331 Mon Sep 17 00:00:00 2001 From: toidiu Date: Tue, 22 Oct 2024 13:46:11 -0700 Subject: [PATCH 1/8] docs: update fips documentation to specify supported libcrypto --- api/s2n.h | 6 +++--- codebuild/bin/install_awslc_fips_2022.sh | 11 ++++------- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/api/s2n.h b/api/s2n.h index ea6e1cc515b..c00923d88ef 100644 --- a/api/s2n.h +++ b/api/s2n.h @@ -262,9 +262,9 @@ typedef enum { /** * Determines whether s2n-tls is operating in FIPS mode. * - * s2n-tls enters FIPS mode on initialization when the linked libcrypto has FIPS mode enabled. Some - * libcryptos, such as AWS-LC-FIPS, have FIPS mode enabled by default. With other libcryptos, such - * as OpenSSL, FIPS mode must be enabled before initialization by calling `FIPS_mode_set()`. + * s2n-tls enters FIPS mode on initialization when the linked libcrypto has FIPS mode enabled. + * s2n-tls only supports FIPS mode when built with AWS-LC-FIPS or AWS-LC-FIPS-2022. AWS-LC-FIPS + * and AWS-LC-FIPS-2022 have FIPS mode enabled by default. * * s2n-tls MUST be linked to a FIPS libcrypto and MUST be in FIPS mode in order to comply with FIPS * requirements. Applications desiring FIPS compliance should use this API to ensure that s2n-tls diff --git a/codebuild/bin/install_awslc_fips_2022.sh b/codebuild/bin/install_awslc_fips_2022.sh index b593bd24e39..4d8ae96517c 100755 --- a/codebuild/bin/install_awslc_fips_2022.sh +++ b/codebuild/bin/install_awslc_fips_2022.sh @@ -32,16 +32,13 @@ if [[ ! -f "$(which clang)" ]]; then exit 1 fi -# There are currently no AWSLC release tags for the 2022 FIPS branch. The -# following is the latest commit in this branch as of 8/19/24: -# https://github.com/aws/aws-lc/commits/fips-2022-11-02 -AWSLC_VERSION=ec94d74a19b5a0aa738b436a95bb06ff87fc7ba9 +AWSLC_VERSION=AWS-LC-FIPS-2.0.17 mkdir -p "$BUILD_DIR" || true cd "$BUILD_DIR" -git clone https://github.com/aws/aws-lc.git -cd aws-lc -git checkout "${AWSLC_VERSION}" +# --branch can also take tags and detaches the HEAD at that commit in the resulting repository +# --depth 1 Create a shallow clone with a history truncated to 1 commit +git clone https://github.com/awslabs/aws-lc.git --branch "$AWSLC_VERSION" --depth 1 build() { shared=$1 From c9a1227ac09b3b8450ac7af5641710892affd124 Mon Sep 17 00:00:00 2001 From: toidiu Date: Tue, 22 Oct 2024 15:30:34 -0700 Subject: [PATCH 2/8] include build instructions for fips --- docs/BUILD.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/BUILD.md b/docs/BUILD.md index d79e1241f6a..32a165ff2c5 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -112,6 +112,8 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l - [AWS-LC](https://github.com/aws/aws-lc) - Limited ["Sandboxing"](https://github.com/aws/aws-lc/blob/main/SANDBOXING.md) is only supported and tested with AWS-LC. - [PQ key exchange](https://aws.github.io/s2n-tls/usage-guide/ch15-post-quantum.html) is only supported with AWS-LC. + - s2n-tls enters FIPS mode when linked to AWS-LC-FIPS. AWS-LC-FIPS can be built by first checking out the FIPS tagged + commit from the official AWS-LC repo (eg. [AWS-LC-FIPS-2.0.17](https://github.com/aws/aws-lc/tree/AWS-LC-FIPS-2.0.17)) - [OpenSSL](https://www.openssl.org/) (versions 1.0.2 - 3.0) - ChaChaPoly is not supported before Openssl-1.1.1. - RSA-PSS is not supported before Openssl-1.1.1. From 9241eebc9b3cdcd52bde2475035e5019dc13fe04 Mon Sep 17 00:00:00 2001 From: toidiu Date: Thu, 24 Oct 2024 10:17:09 -0700 Subject: [PATCH 3/8] update Readme docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f7140481296..d300978133d 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ s2n-tls avoids implementing rarely used options and extensions, as well as featu The security of TLS and its associated encryption algorithms depends upon secure random number generation. s2n-tls provides every thread with two separate random number generators. One for "public" randomly generated data that may appear in the clear, and one for "private" data that should remain secret. This approach lessens the risk of potential predictability weaknesses in random number generation algorithms from leaking information across contexts. ##### Modularized encryption -s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL (versions 1.0.2, 1.1.1 and 3.0.x), LibreSSL, BoringSSL, AWS-LC, and the Apple Common Crypto framework to perform the underlying cryptographic operations. +s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL (versions 1.0.2, 1.1.1 and 3.0.x), LibreSSL, BoringSSL, AWS-LC, and the Apple Common Crypto framework to perform the underlying cryptographic operations. s2n-tls only supports FIPS mode when built with AWS-LC-FIPS. ##### Timing blinding s2n-tls includes structured support for blinding time-based side-channels that may leak sensitive data. For example, if s2n-tls fails to parse a TLS record or handshake message, s2n-tls will add a randomized delay of between 10 and 30 seconds, granular to nanoseconds, before responding. This raises the complexity of real-world timing side-channel attacks by a factor of at least tens of trillions. From f81e94631692163839c293e8f2a41176db21e053 Mon Sep 17 00:00:00 2001 From: toidiu Date: Thu, 24 Oct 2024 15:10:44 -0700 Subject: [PATCH 4/8] update wording --- README.md | 2 +- api/s2n.h | 10 ++++------ docs/BUILD.md | 6 ++++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d300978133d..939faad8176 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ s2n-tls avoids implementing rarely used options and extensions, as well as featu The security of TLS and its associated encryption algorithms depends upon secure random number generation. s2n-tls provides every thread with two separate random number generators. One for "public" randomly generated data that may appear in the clear, and one for "private" data that should remain secret. This approach lessens the risk of potential predictability weaknesses in random number generation algorithms from leaking information across contexts. ##### Modularized encryption -s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports OpenSSL (versions 1.0.2, 1.1.1 and 3.0.x), LibreSSL, BoringSSL, AWS-LC, and the Apple Common Crypto framework to perform the underlying cryptographic operations. s2n-tls only supports FIPS mode when built with AWS-LC-FIPS. +s2n-tls has been structured so that different encryption libraries may be used. Today s2n-tls supports AWS-LC, OpenSSL (versions 1.0.2, 1.1.1 and 3.0.x), LibreSSL, and BoringSSL to perform the underlying cryptographic operations. Check the [libcrypto build documentation](docs/BUILD.md#building-with-a-specific-libcrypto) for a list of libcrypto-specific features. ##### Timing blinding s2n-tls includes structured support for blinding time-based side-channels that may leak sensitive data. For example, if s2n-tls fails to parse a TLS record or handshake message, s2n-tls will add a randomized delay of between 10 and 30 seconds, granular to nanoseconds, before responding. This raises the complexity of real-world timing side-channel attacks by a factor of at least tens of trillions. diff --git a/api/s2n.h b/api/s2n.h index c00923d88ef..b1f0071e767 100644 --- a/api/s2n.h +++ b/api/s2n.h @@ -262,13 +262,11 @@ typedef enum { /** * Determines whether s2n-tls is operating in FIPS mode. * - * s2n-tls enters FIPS mode on initialization when the linked libcrypto has FIPS mode enabled. - * s2n-tls only supports FIPS mode when built with AWS-LC-FIPS or AWS-LC-FIPS-2022. AWS-LC-FIPS - * and AWS-LC-FIPS-2022 have FIPS mode enabled by default. + * s2n-tls enters FIPS mode on initialization when linked with a FIPS validated version of AWS-LC. * - * s2n-tls MUST be linked to a FIPS libcrypto and MUST be in FIPS mode in order to comply with FIPS - * requirements. Applications desiring FIPS compliance should use this API to ensure that s2n-tls - * has been properly linked with a FIPS libcrypto and has successfully entered FIPS mode. + * s2n-tls MUST be linked to a FIPS validated libcrypto and MUST be in FIPS mode in order to comply + * with FIPS requirements. Applications desiring FIPS compliance should use this API to ensure that + * s2n-tls has been properly linked with a FIPS libcrypto and has successfully entered FIPS mode. * * @param fips_mode Set to the FIPS mode of s2n-tls. * @returns S2N_SUCCESS on success. S2N_FAILURE on failure. diff --git a/docs/BUILD.md b/docs/BUILD.md index 32a165ff2c5..caf0865061e 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -112,15 +112,17 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l - [AWS-LC](https://github.com/aws/aws-lc) - Limited ["Sandboxing"](https://github.com/aws/aws-lc/blob/main/SANDBOXING.md) is only supported and tested with AWS-LC. - [PQ key exchange](https://aws.github.io/s2n-tls/usage-guide/ch15-post-quantum.html) is only supported with AWS-LC. - - s2n-tls enters FIPS mode when linked to AWS-LC-FIPS. AWS-LC-FIPS can be built by first checking out the FIPS tagged - commit from the official AWS-LC repo (eg. [AWS-LC-FIPS-2.0.17](https://github.com/aws/aws-lc/tree/AWS-LC-FIPS-2.0.17)) + - FIPS mode is supported when s2n-tls is linked with a FIPS validated version of [AWS-LC](https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md). - [OpenSSL](https://www.openssl.org/) (versions 1.0.2 - 3.0) - ChaChaPoly is not supported before Openssl-1.1.1. - RSA-PSS is not supported before Openssl-1.1.1. - RC4 is not supported with Openssl-3.0 or later. + - FIPS mode is not supported with Openssl. - [BoringSSL](https://boringssl.googlesource.com/boringssl) - OCSP features are not supported with BoringSSL. + - FIPS mode is not supported with BoringSSL. - [LibreSSL](https://www.libressl.org/) + - FIPS mode is not supported with LibreSSL. By default, s2n-tls will attempt to find a system libcrypto to link with when building. However, this search can be overridden to any of the above libcryptos by specifying the install directory with the `CMAKE_PREFIX_PATH` flag. From 8628181590f4597f9e14899b00356f415912a84c Mon Sep 17 00:00:00 2001 From: toidiu Date: Fri, 25 Oct 2024 09:51:24 -0700 Subject: [PATCH 5/8] fips not supported with openssl 3 --- docs/BUILD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/BUILD.md b/docs/BUILD.md index caf0865061e..d8cc071d07e 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -117,7 +117,7 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l - ChaChaPoly is not supported before Openssl-1.1.1. - RSA-PSS is not supported before Openssl-1.1.1. - RC4 is not supported with Openssl-3.0 or later. - - FIPS mode is not supported with Openssl. + - FIPS mode is not supported with Openssl-3.0 or later. - [BoringSSL](https://boringssl.googlesource.com/boringssl) - OCSP features are not supported with BoringSSL. - FIPS mode is not supported with BoringSSL. From 083a3f19a66b1a58dcbb5426f7196214cd255073 Mon Sep 17 00:00:00 2001 From: toidiu Date: Fri, 25 Oct 2024 09:54:12 -0700 Subject: [PATCH 6/8] libressl is not fips certified --- docs/BUILD.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/BUILD.md b/docs/BUILD.md index d8cc071d07e..2386519418a 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -122,7 +122,6 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l - OCSP features are not supported with BoringSSL. - FIPS mode is not supported with BoringSSL. - [LibreSSL](https://www.libressl.org/) - - FIPS mode is not supported with LibreSSL. By default, s2n-tls will attempt to find a system libcrypto to link with when building. However, this search can be overridden to any of the above libcryptos by specifying the install directory with the `CMAKE_PREFIX_PATH` flag. From 54b9958e4327762d8b8459154aae36cc64dd3ebe Mon Sep 17 00:00:00 2001 From: toidiu Date: Fri, 25 Oct 2024 15:34:18 -0700 Subject: [PATCH 7/8] update api docs --- api/s2n.h | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/api/s2n.h b/api/s2n.h index b1f0071e767..48f70a6a41a 100644 --- a/api/s2n.h +++ b/api/s2n.h @@ -262,11 +262,13 @@ typedef enum { /** * Determines whether s2n-tls is operating in FIPS mode. * - * s2n-tls enters FIPS mode on initialization when linked with a FIPS validated version of AWS-LC. + * s2n-tls enters FIPS mode on initialization when built with a version of AWS-LC that supports + * FIPS (https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md). FIPS mode controls + * some internal configuration related to FIPS support, like which random number generator is used. * - * s2n-tls MUST be linked to a FIPS validated libcrypto and MUST be in FIPS mode in order to comply - * with FIPS requirements. Applications desiring FIPS compliance should use this API to ensure that - * s2n-tls has been properly linked with a FIPS libcrypto and has successfully entered FIPS mode. + * FIPS mode does not enforce the use of FIPS-approved cryptography. Applications attempting to use + * only FIPS-approved cryptography should also ensure that s2n-tls is configured to use a security + * policy that only supports FIPS-approved cryptography. * * @param fips_mode Set to the FIPS mode of s2n-tls. * @returns S2N_SUCCESS on success. S2N_FAILURE on failure. From 086ee1f0f8260053943730a48a1e238d1f0fb1af Mon Sep 17 00:00:00 2001 From: toidiu Date: Fri, 25 Oct 2024 15:57:08 -0700 Subject: [PATCH 8/8] update build instructions --- docs/BUILD.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/BUILD.md b/docs/BUILD.md index 2386519418a..bc3ebd9f131 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -112,7 +112,8 @@ s2n-tls has a dependency on a libcrypto library. A supported libcrypto must be l - [AWS-LC](https://github.com/aws/aws-lc) - Limited ["Sandboxing"](https://github.com/aws/aws-lc/blob/main/SANDBOXING.md) is only supported and tested with AWS-LC. - [PQ key exchange](https://aws.github.io/s2n-tls/usage-guide/ch15-post-quantum.html) is only supported with AWS-LC. - - FIPS mode is supported when s2n-tls is linked with a FIPS validated version of [AWS-LC](https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md). + - FIPS mode is supported with versions of AWS-LC [that support + FIPS](https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md). - [OpenSSL](https://www.openssl.org/) (versions 1.0.2 - 3.0) - ChaChaPoly is not supported before Openssl-1.1.1. - RSA-PSS is not supported before Openssl-1.1.1.