functionality-differences.md

No-op Symbols and Configurations

Although the OPENSSL_IS_AWSLC preprocessor macro is available for downstream projects to distinguish AWS-LC from OpenSSL, we wish to limit the number of #ifdefs needed for projects to support us. No-ops symbols are used in place for functions that are less involved in key code paths to allow for easier integration. A no-op (no operation) symbol refers to a symbol that does nothing and has no effect on the state of the program. AWS-LC uses these across various utility functions and configuration flags to provide easier compatibility with OpenSSL.

No-op symbols can be differentiated into two types:

1. Symbols related to certain functionalities and configurations in OpenSSL that we don’t support (i.e. Security Levels, DH ciphersuites, etc).
2. Symbols that were historically needed to configure OpenSSL correctly, but aren’t needed to configure AWS-LC (i.e. threading, entropy configuration, etc.)

libssl No-ops & Absent Functionality

libssl is the portion of OpenSSL which supports TLS. AWS-LC does not have support for every OpenSSL libssl feature. Notable absent functionalities from libssl include SSL Security Levels, SSL Compression, and DANE TLSA. Certain SSL ciphersuites are also not supported such as ciphers using FFDH and RC4. Partially absent features include minimalTLS renegotiation support and Stateful Session Resumption (only supported for TLS 1.2 and earlier). More details can be found in the ssl.h header documentation.

When migrating to AWS-LC, it is important to understand the SSL features your application is reliant on from OpenSSL**. Many nuances with libssl can only be discovered at runtime****, so consumers should have specific test cases available****. For example, absent ciphersuite support cannot be detected unless there are specific tests expecting the ciphersuite to be available.** Migrators to AWS-LC are expected to understand their intended use cases and have tests surrounding functionality they are dependent on. AWS-LC provides test coverage for functional correctness and compliance with TLS standards and implemented extensions. Different cryptographic libraries may implement some behavior by convention that is not standardized and thus is not guaranteed to work the same way in AWS-LC. Customers are responsible for writing their own tests to determine whether they are affected by these kinds of differences, and AWS-LC will publish a list of known differences in the future.

If you have a valid use case for any missing functionality or if anything is not clarified in our documentation, feel free to cut an issue or create a PR to let us know.

libssl No-ops

Related Functionality	Details	No-op function	Return value
Security Levels	Security Levels No-ops	SSL_CTX_get_security_level	Returns zero.
		SSL_CTX_set_security_level	Does nothing.
DH ciphersuites	FFDH Ciphersuite No-ops	SSL_CTX_set_tmp_dh	Returns one.
		SSL_set_tmp_dh	Returns one.
		SSL_CTX_set_tmp_dh_callback	Does nothing.
		SSL_set_tmp_dh_callback	Does nothing.
SSL_COMP and COMP_METHOD	SSL_COMP and COMP_METHOD No-ops	SSL_COMP_get_compression_methods	Returns NULL.
		SSL_COMP_add_compression_method	Returns one.
		SSL_COMP_get_name	Returns NULL.
		SSL_COMP_free_compression_methods	Does nothing.
		SSL_get_current_compression	Returns NULL.
		SSL_get_current_expansion	Returns NULL.
TLS Renegotiation	TLS Renegotiation	SSL_renegotiate	Returns 1 on success, 0 on failure. There is no support for renegotiation for TLS as a server or DTLS. There is only minimal support for initiating renegotiation as a client. SSL_set_renegotiate_mode must be set to ssl_renegotiate_once, ssl_renegotiate_freely, or ssl_renegotiate_explicit for SSL_renegotiate to work.
General	SSL_get_shared_ciphers	SSL_get_shared_ciphers	Writes an empty string and returns a pointer containing it or returns NULL.
	SSL_get_shared_sigalgs	SSL_get_shared_sigalgs	Returns zero.
	SSL_get_server_tmp_key	SSL_get_server_tmp_key	Returns zero.

libssl TLS supported ciphersuites

TLS 1.2 supported cipher suites between AWS-LC and OpenSSL 1.1.1u:

Ciphersuite	OpenSSL 1.1.1	AWS-LC
AES128-GCM-SHA256	X	X
AES128-SHA	X	X
AES128-SHA256	X	X
AES256-GCM-SHA384	X	X
AES256-SHA	X	X
AES256-SHA256	X
DES-CBC3-SHA		X
DHE-RSA-AES128-GCM-SHA256	X
DHE-RSA-AES128-SHA	X
DHE-RSA-AES128-SHA256	X
DHE-RSA-AES256-GCM-SHA384	X
DHE-RSA-AES256-SHA	X
DHE-RSA-AES256-SHA256	X
DHE-RSA-CHACHA20-POLY1305	X
ECDHE-ECDSA-AES128-GCM-SHA256	X	X
ECDHE-ECDSA-AES128-SHA	X	X
ECDHE-ECDSA-AES128-SHA256	X
ECDHE-ECDSA-AES256-GCM-SHA384	X	X
ECDHE-ECDSA-AES256-SHA	X	X
ECDHE-ECDSA-AES256-SHA384	X
ECDHE-ECDSA-CHACHA20-POLY1305	X	X
ECDHE-PSK-AES128-CBC-SHA		X
ECDHE-PSK-AES256-CBC-SHA		X
ECDHE-PSK-CHACHA20-POLY1305		X
ECDHE-RSA-AES128-GCM-SHA256	X	X
ECDHE-RSA-AES128-SHA	X	X
ECDHE-RSA-AES128-SHA256	X	X
ECDHE-RSA-AES256-GCM-SHA384	X	X
ECDHE-RSA-AES256-SHA	X	X
ECDHE-RSA-AES256-SHA384	X	X
ECDHE-RSA-CHACHA20-POLY1305	X	X
PSK-AES128-CBC-SHA		X
PSK-AES256-CBC-SHA		X

TLS 1.3 supported cipher suites between AWS-LC and OpenSSL 1.1.1u:

Ciphersuite	OpenSSL 1.1.1	AWS-LC
TLS_AES_128_GCM_SHA256	X	X
TLS_AES_256_GCM_SHA384	X	X
TLS_CHACHA20_POLY1305_SHA256	X	X

libcrypto No-ops & Absent Functionality

libcrypto is the portion of OpenSSL for performing general-purpose cryptography, which can be used without libssl. Commonly used standardized formats such as X509 and ASN1 are also implemented in libcrypto. AWS-LC does not have support for every feature in OpenSSL’s libcrypto. Notable absent functionalities include OpenSSL’s CONF modules. Utility functions surrounding RAND are no-ops, consumers should call RAND_bytes directly instead. Setting flags to configure EVP_MD_CTX and EVP_CIPHER_CTX is also not supported.

Older and less common usages of EVP_PKEY have been removed. For example, signing and verifying with EVP_PKEY_DSA is not supported. More details on specific features can be found in the corresponding header documentation.

When migrating to AWS-LC, it is important to understand the specific libcrypto components your application is reliant on from OpenSSL. For example, there may be underlying differences when consuming X509 certificate verification from AWS-LC. Migrators to AWS-LC are expected to understand their intended use cases and have tests surrounding functionality they are dependent on. AWS-LC provides test coverage for functional and cryptographic correctness, along with compliance with standards like PKCS and X509. Different cryptographic libraries may implement some behavior by convention that is not standardized and thus is not guaranteed to work the same way in AWS-LC. Customers are responsible for writing their own tests to determine whether they are affected by these kinds of differences, and AWS-LC will publish a list of known differences in the future.

If you have a valid use case for any missing functionality or if anything is not clarified in our documentation, feel free to cut an issue or create a PR to let us know.

libcrypto No-ops

Related Functionality	Details	No-op function	Return value
EVP_PKEY	EVP_PKEY_DSA No-ops Porting Guide	EVP_PKEY_CTX_set_dsa_paramgen_bits	Returns zero.
		EVP_PKEY_CTX_set_dsa_paramgen_q_bits	Returns zero.
	EVP_PKEY_DH No-ops	EVP_PKEY_get0_DH	Returns NULL.
		EVP_PKEY_get1_DH	Returns NULL.
	evp.h	EVP_PKEY_get0	Void function that does not return anything (NULL).
EC	EC_KEY EC_GROUP	EC_KEY_set_asn1_flag	Does nothing.
		EC_GROUP_set_asn1_flag	Does nothing.
		EC_GROUP_get_asn1_flag	Returns OPENSSL_EC_NAMED_CURVE.
	EC_METHOD	EC_GROUP_method_of	Returns a dummy non-NULL EC_METHOD pointer.
		EC_METHOD_get_field_type	Returns NID_X9_62_prime_field.
	Compressed Forms	EC_GROUP_set_point_conversion_form	Returns nothing as a void function. Aborts if a form other than POINT_CONVERSION_UNCOMPRESSED or POINT_CONVERSION_COMPRESSED is requested.
CONF modules	conf.h	CONF_modules_load_file	Returns one.
		CONF_get1_default_config_file	Returns a fixed dummy string("No support for Config files in AWS-LC.")
		CONF_modules_unload	Does nothing.
		CONF_modules_finish	Does nothing.
		CONF_modules_free	Does nothing.
RAND Functions	rand.h Entropy Sources	RAND_load_file	Returns a non-negative number.
		RAND_write_file	Does nothing and returns negative one.
		RAND_file_name	Returns NULL.
		RAND_add	Does nothing.
		RAND_egd	Returns 255.
		RAND_poll	Returns one.
		RAND_status	Returns one.
		RAND_cleanup	Does nothing.
		RAND_SSLeay	Returns a dummy RAND_METHOD pointer.
		RAND_OpenSSL	Returns a dummy RAND_METHOD pointer.
		RAND_get_rand_method	Returns a dummy RAND_METHOD pointer.
		RAND_set_rand_method	Returns one.
		RAND_keep_random_devices_open	Does nothing.
ASN1	asn1.h	ASN1_STRING_set_default_mask	Does nothing.
		ASN1_STRING_set_default_mask_asc	Returns one.
		ASN1_STRING_get_default_mask	Returns B_ASN1_UTF8STRING (The default value AWS-LC uses).
		ASN1_STRING_TABLE_cleanup	Does nothing.
Thread Safety	thread.h	CRYPTO_num_locks	Returns one.
		CRYPTO_set_locking_callback	Does nothing.
		CRYPTO_set_add_lock_callback	Does nothing.
		CRYPTO_get_locking_callback	Returns NULL.
		CRYPTO_get_lock_name	Returns a fixed dummy string ("No old-style OpenSSL locks anymore")
		CRYPTO_THREADID_set_callback	Returns one.
		CRYPTO_THREADID_set_numeric	Does nothing.
		CRYPTO_THREADID_set_pointer	Does nothing.
		CRYPTO_THREADID_current	Does nothing.
		CRYPTO_set_id_callback	Does nothing.
		CRYPTO_set_dynlock_create_callback	Does nothing.
		CRYPTO_set_dynlock_lock_callback	Does nothing.
		CRYPTO_set_dynlock_destroy_callback	Does nothing.
		CRYPTO_get_dynlock_create_callback	Returns NULL.
		CRYPTO_get_dynlock_lock_callback	Returns NULL.
		CRYPTO_get_dynlock_destroy_callback	Returns NULL.
Miscellaneous	evp.h	OpenSSL_add_all_algorithms	Does nothing.
		OPENSSL_add_all_algorithms_conf	Does nothing.
		OpenSSL_add_all_ciphers	Does nothing.
		OpenSSL_add_all_digests	Does nothing.
		EVP_cleanup	Does nothing.
	cipher.h	EVP_CIPHER_CTX_set_flags	Does nothing. This functions sets flags for EVP_CIPHER_CTX, so any related flags are also no-ops. Related no-op flags can be found in the surrounding documentation .
		EVP_add_cipher_alias	Does nothing and returns one
	digest.h	EVP_MD_CTX_set_flags	Does nothing. This functions sets flags for EVP_MD_CTX, so any related flags are also no-ops. Related no-op flags can be found in the surrounding documentation .
		EVP_add_digest	Does nothing and returns one
	dh.h	DH_clear_flags	Does nothing. This functions clears flags for DH, so any related flags are also no-ops. Related no-op flags can be found in the surrounding documentation .
	ex_data.h	CRYPTO_cleanup_all_ex_data	Does nothing.
		CRYPTO_EX_dup	Legacy Callback function that's ignored.
	bio.h	BIO_set_write_buffer_size	Returns zero.