Skip to content

Commit

Permalink
docs: update fips documentation to specify supported libcrypto (#4857)
Browse files Browse the repository at this point in the history
  • Loading branch information
toidiu authored Oct 28, 2024
1 parent 778cd84 commit b8c463b
Show file tree
Hide file tree
Showing 4 changed files with 15 additions and 14 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.
Expand Down
12 changes: 6 additions & 6 deletions api/s2n.h
Original file line number Diff line number Diff line change
Expand Up @@ -262,13 +262,13 @@ 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 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 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.
Expand Down
11 changes: 4 additions & 7 deletions codebuild/bin/install_awslc_fips_2022.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,12 +112,16 @@ 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 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.
- RC4 is not supported with Openssl-3.0 or later.
- 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.
- [LibreSSL](https://www.libressl.org/)

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.
Expand Down

0 comments on commit b8c463b

Please sign in to comment.