configuration-differences.md

Differences in Configuration Defaults

Cryptography and SSL should have less configurations and be hard to misuse. As mentioned earlier, AWS-LC has cut down on the available knobs in crypto/ssl and made certain optimizations the default. Most configuration flags OpenSSL historically had available have been changed to no-ops in AWS-LC. No-op flags can also be differentiated into two types here:

1. The configuration is already provided by default in AWS-LC.
2. There are certain configurations and historic workarounds in OpenSSL that we don’t support (see SSL_OP_ALL).

There are also a few configurations which OpenSSL has “OFF” by default, that AWS-LC has turned “ON” by default. This section outlines all known no-op configuration flags and default configuration differences.

Default Behavioral Differences and No-op Configuration Flags

The following tables only contains the differences in configuration options AWS-LC and OpenSSL provides.

1. The following two tables under libssl and libcrypto only focus on the flags that exist within AWS-LC. There are other flags supported by only OpenSSL that aren’t listed here. Missing flags we are aware of are documented in Intentionally Omitted Configuration Flags. If there is a valid use case for an undocumented flag non-existent within AWS-LC, feel free to cut an issue to us.
2. Flags that are no-ops within both AWS-LC and OpenSSL have been omitted from the table.
3. Flags that are listed as no-ops in the Configurability section, means that there is no support to configure the listed behavior within AWS-LC. The flags are merely provided for easier compatibility.

Things to be Aware

When integrating with AWS-LC, it is important to keep note if your application is dependent on any of the flags outlined in the following tables. Your application should have tests regarding expected behavior and understand the customer impact behavioral changes will cause before migrating to AWS-LC.

• Anything that is labeled “ON” in “AWS-LC Default” is a behavioral difference between AWS-LC and OpenSSL (with the exception of SSL_MODE_AUTO_RETRY). Developers should make sure that migrating to AWS-LC, is the equivalent of turning these flags “ON” by default in OpenSSL.
  • Aside from SSL_MODE_NO_AUTO_CHAIN, there is no way to clear any flags that are “ON” by default in AWS-LC.
• Anything that is labeled “OFF” in “AWS-LC Default” is also a "NO-OP". These flags merely exist for compatibility and the state of AWS-LC does not change when attempting to configure them. If any of these flags are used, differences will be exposed at run-time with your application.

To determine whether your consuming application is impacted, do a search for the relevant “Context Flags Setting Function"s in your codebase. If the function is used, be aware of any relevant flags that have been listed in “Context Flags”. More context on what each flag configures can be found in our documentation by clicking the corresponding link.

libssl Differences

The following table contains the differences in libssl configuration options AWS-LC and OpenSSL provides. These flags are relevant to all TLS connections, unless specified otherwise.

• Aside from and SSL_MODE_AUTO_RETRY being "ON" by default in OpenSSL, everything is "OFF" by default in OpenSSL.
• Each “Context Flag” has a link that provides more details on the flag’s functionality and our decision behind it (WIP)

Context Flags Setting Function	Context Flags	AWS-LC Default	Configurability
SSL_CTX_set_mode SSL_set_mode SSL_CTX_clear_mode SSL_clear_mode	SSL_MODE_NO_AUTO_CHAIN	ON	Configurable
	SSL_MODE_AUTO_RETRY	ON	NO-OP
	SSL_MODE_RELEASE_BUFFERS	ON	NO-OP
	SSL_MODE_SEND_CLIENTHELLO_TIME	OFF	NO-OP
	SSL_MODE_SEND_SERVERHELLO_TIME	ON	NO-OP
SSL_CTX_set_options SSL_set_options SSL_CTX_clear_options SSL_clear_options	SSL_OP_ALL	OFF	NO-OP
	SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION	OFF	NO-OP
	SSL_OP_CRYPTOPRO_TLSEXT_BUG	OFF	NO-OP
	SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS	ON	NO-OP
	SSL_OP_LEGACY_SERVER_CONNECT	OFF	NO-OP
	SSL_OP_NO_COMPRESSION	ON	NO-OP
	SSL_OP_NO_RENEGOTIATION	ON	NO-OP Renegotiation is enabled with SSL_set_renegotiate_mode, an AWS-LC/BoringSSL specific API.
	SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION	ON	NO-OP
	SSL_OP_NO_SSLv3	ON	NO-OP
	SSL_OP_SAFARI_ECDHE_ECDSA_BUG	ON	NO-OP
	SSL_OP_TLSEXT_PADDING	ON	NO-OP
	SSL_OP_TLS_ROLLBACK_BUG	OFF	NO-OP
	SSL_VERIFY_CLIENT_ONCE	OFF	NO-OP
SSL_set_hostflags X509_STORE_CTX_set_flags X509_STORE_set_flags X509_VERIFY_PARAM_set_flags X509_VERIFY_PARAM_set_hostflags	X509_V_FLAG_X509_STRICT	ON	NO-OP
	X509_V_FLAG_ALLOW_PROXY_CERTS	OFF	NO-OP

libcrypto Differences

The following table contains the differences in libcrypto configuration options AWS-LC and OpenSSL provides.

• Everything is "OFF" and "Configurable" by default in OpenSSL.
• Each “Context Flag” has a link that provides more details on the flag’s functionality (WIP)

Context Flags Setting Function	Context Flags	AWS-LC Default	Configurability
X509_check_host X509_check_email X509_check_ip X509_check_ip_asc	X509_CHECK_FLAG_NO_WILDCARDS	OFF	Configurable
	X509_CHECK_FLAG_NEVER_CHECK_SUBJECT	OFF	Configurable
	X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT	OFF	NO-OP
	X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS	ON	NO-OP
	X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS	OFF	NO-OP
	X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS	OFF	NO-OP
PKCS7_sign	PKCS7_DETACHED	OFF	Configurable
	PKCS7_BINARY	Partially Supported These flags must be used simultaneously together with PKCS7_DETACHED to generate a detached RSA SHA-256 signature of the data and produces a PKCS#7 SignedData structure containing it.	Must be used along with PKCS7_DETACHED. Other combinations are not supported.
	PKCS7_NOATTR
	PKCS7_PARTIAL
	PKCS7_TEXT	OFF	NO-OP
	PKCS7_NOCERTS	OFF	NO-OP
	PKCS7_STREAM	OFF	NO-OP
	PKCS7_NOSMIMECAP	OFF	NO-OP
EVP_PKEY_assign	EVP_PKEY_DH	Not Supported	NO-OP
	EVP_PKEY_X448	Not Supported	NO-OP
	EVP_PKEY_ED448	Not Supported	NO-OP
	EVP_PKEY_RSA2	Not Supported	NO-OP

Intentionally Omitted Configuration Flags

The following table contains configuration options AWS-LC has intentionally omitted. If your application uses a non-existent flag outlined here, it will fail to compile with AWS-LC.

• Each “Context Flag” has a link that provides more details on the flag’s functionality (WIP)
• If you feel that there is a valid use case for any of these flags, feel free to cut an issue to us.

Context Flags Setting Function	Context Flags	AWS-LC Default
BN_set_flags	BN_FLG_CONSTTIME	Not Implemented
ASN1_aux_cb	ASN1_OP_I2D_PRE	Not Implemented
	ASN1_OP_I2D_POST	Not Implemented