From 596aac3e0a76057a590deb8b7f5b275e1b274924 Mon Sep 17 00:00:00 2001 From: George Poulios Date: Sat, 30 Nov 2024 12:12:39 +0200 Subject: [PATCH] Update MbedTLS 3.4.0 -> 3.6.2 and set it as default Even though one could in theory simply set CONFIG_MBEDTLS_VERSION="3.6.2", this commit is needed for 2 reasons: 1. The patches need to be updated: 0001 works almost as-is (with fuzz 2) but 0002 hunk #4 fails and needed adjustment. Otherwise, the patches are identical. 2. mbedtls_config.h needs to be updated: Following the same approach for the Kconfig this commit updates both Kconfig and mbedtls_config.h according to the changes: mbedtls$ git diff v3.4.0...v3.6.2 -- include/mbedtls/mbedtls_config.h Signed-off-by: George Poulios --- crypto/controlse/Kconfig | 2 +- ...poll-use-getrandom-to-get-the-system.patch | 33 +- ...02-mbedtls-add-mbedtls-x509-crt-pool.patch | 82 +- crypto/mbedtls/Kconfig | 148 ++- .../mbedtls/include/mbedtls/mbedtls_config.h | 1072 +++++++++++------ 5 files changed, 907 insertions(+), 430 deletions(-) diff --git a/crypto/controlse/Kconfig b/crypto/controlse/Kconfig index e1da37dcd1..76b85ec571 100644 --- a/crypto/controlse/Kconfig +++ b/crypto/controlse/Kconfig @@ -8,7 +8,7 @@ config CRYPTO_CONTROLSE default n depends on DEV_SE05X depends on CRYPTO_MBEDTLS - depends on MBEDTLS_VERSION = "3.4.0" + depends on MBEDTLS_VERSION = "3.6.2" select MBEDTLS_ECDSA_C select MBEDTLS_ECP_C select MBEDTLS_ECP_DP_SECP256R1_ENABLED diff --git a/crypto/mbedtls/0001-mbedtls-entropy_poll-use-getrandom-to-get-the-system.patch b/crypto/mbedtls/0001-mbedtls-entropy_poll-use-getrandom-to-get-the-system.patch index c97804e3dd..8a8aeab8ab 100644 --- a/crypto/mbedtls/0001-mbedtls-entropy_poll-use-getrandom-to-get-the-system.patch +++ b/crypto/mbedtls/0001-mbedtls-entropy_poll-use-getrandom-to-get-the-system.patch @@ -1,22 +1,31 @@ -From e40fdc9238384ee62013c41d74cb4d47ae8c1aad Mon Sep 17 00:00:00 2001 -From: makejian -Date: Mon, 11 Sep 2023 19:40:04 +0800 -Subject: [PATCH] mbedtls/entropy_poll: use 'getrandom' to get the system +From b82b0c314d78d44f717a69924e7a60d8d43eb200 Mon Sep 17 00:00:00 2001 +From: George Poulios +Date: Fri, 29 Nov 2024 10:32:54 +0200 +Subject: [PATCH 1/2] mbedtls/entropy_poll: use 'getrandom' to get the system entropy -VELAPLATFO-16390 +Original patch: + From e40fdc9238384ee62013c41d74cb4d47ae8c1aad Mon Sep 17 00:00:00 2001 + From: makejian + Date: Mon, 11 Sep 2023 19:40:04 +0800 + Subject: [PATCH] mbedtls/entropy_poll: use 'getrandom' to get the system + entropy -Change-Id: I885969c441cd174f5eedf8c9ce17b89e501148c8 -Signed-off-by: makejian + VELAPLATFO-16390 + + Change-Id: I885969c441cd174f5eedf8c9ce17b89e501148c8 + Signed-off-by: makejian + +Signed-off-by: George Poulios --- library/entropy_poll.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) -diff --git mbedtls/library/entropy_poll.c mbedtls/library/entropy_poll.c -index b5024c83f..e9431e812 100644 ---- mbedtls/library/entropy_poll.c -+++ mbedtls/library/entropy_poll.c -@@ -103,10 +103,11 @@ static int getrandom_wrapper(void *buf, size_t buflen, unsigned int flags) +diff --git a/library/entropy_poll.c b/library/entropy_poll.c +index 611768cd85..a26e154db1 100644 +--- a/library/entropy_poll.c ++++ b/library/entropy_poll.c +@@ -95,10 +95,11 @@ static int getrandom_wrapper(void *buf, size_t buflen, unsigned int flags) #endif /* SYS_getrandom */ #endif /* __linux__ || __midipix__ */ diff --git a/crypto/mbedtls/0002-mbedtls-add-mbedtls-x509-crt-pool.patch b/crypto/mbedtls/0002-mbedtls-add-mbedtls-x509-crt-pool.patch index 3bac43e8c7..728903abec 100644 --- a/crypto/mbedtls/0002-mbedtls-add-mbedtls-x509-crt-pool.patch +++ b/crypto/mbedtls/0002-mbedtls-add-mbedtls-x509-crt-pool.patch @@ -1,9 +1,17 @@ -From e9eeb5721637faa451f66bbb2789046b9a7963d5 Mon Sep 17 00:00:00 2001 -From: makejian -Date: Fri, 18 Aug 2023 15:52:45 +0800 -Subject: [PATCH 1/2] mbedtls: add mbedtls x509 crt pool +From f846c8fb13238a4db1f7d5e1a9ebce459c21faf7 Mon Sep 17 00:00:00 2001 +From: George Poulios +Date: Fri, 29 Nov 2024 10:33:57 +0200 +Subject: [PATCH 2/2] mbedtls: add mbedtls x509 crt pool -Signed-off-by: makejian +Original patch: + From e9eeb5721637faa451f66bbb2789046b9a7963d5 Mon Sep 17 00:00:00 2001 + From: makejian + Date: Fri, 18 Aug 2023 15:52:45 +0800 + Subject: [PATCH 1/2] mbedtls: add mbedtls x509 crt pool + + Signed-off-by: makejian + +Signed-off-by: George Poulios --- include/mbedtls/threading.h | 4 + library/threading.c | 3 + @@ -14,13 +22,13 @@ Signed-off-by: makejian create mode 100644 library/x509_crt_pool.c create mode 100644 library/x509_crt_pool.h -diff --git mbedtls/include/mbedtls/threading.h mbedtls/include/mbedtls/threading.h -index 1b9c7ced2..e3986cd67 100644 ---- mbedtls/include/mbedtls/threading.h -+++ mbedtls/include/mbedtls/threading.h -@@ -108,6 +108,10 @@ extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex; - extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex; - #endif /* MBEDTLS_HAVE_TIME_DATE && !MBEDTLS_PLATFORM_GMTIME_R_ALT */ +diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h +index d50d04ead1..9fffe6705d 100644 +--- a/include/mbedtls/threading.h ++++ b/include/mbedtls/threading.h +@@ -128,6 +128,10 @@ extern mbedtls_threading_mutex_t mbedtls_threading_psa_globaldata_mutex; + extern mbedtls_threading_mutex_t mbedtls_threading_psa_rngdata_mutex; + #endif +#if defined(MBEDTLS_X509_CRT_POOL) +extern mbedtls_threading_mutex_t mbedtls_threading_x509crtpool_mutex; @@ -29,24 +37,24 @@ index 1b9c7ced2..e3986cd67 100644 #endif /* MBEDTLS_THREADING_C */ #ifdef __cplusplus -diff --git mbedtls/library/threading.c mbedtls/library/threading.c -index 130c6963d..c91df6f6a 100644 ---- mbedtls/library/threading.c -+++ mbedtls/library/threading.c -@@ -189,5 +189,8 @@ mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex MUTEX_INIT; - #if defined(THREADING_USE_GMTIME) - mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex MUTEX_INIT; +diff --git a/library/threading.c b/library/threading.c +index 85db243f21..da500193f5 100644 +--- a/library/threading.c ++++ b/library/threading.c +@@ -191,5 +191,8 @@ mbedtls_threading_mutex_t mbedtls_threading_key_slot_mutex MUTEX_INIT; + mbedtls_threading_mutex_t mbedtls_threading_psa_globaldata_mutex MUTEX_INIT; + mbedtls_threading_mutex_t mbedtls_threading_psa_rngdata_mutex MUTEX_INIT; #endif +#if defined(MBEDTLS_X509_CRT_POOL) +mbedtls_threading_mutex_t mbedtls_threading_x509crtpool_mutex MUTEX_INIT; +#endif #endif /* MBEDTLS_THREADING_C */ -diff --git mbedtls/library/x509_crt.c mbedtls/library/x509_crt.c -index cf62532f2..8d058a092 100644 ---- mbedtls/library/x509_crt.c -+++ mbedtls/library/x509_crt.c -@@ -78,6 +78,10 @@ +diff --git a/library/x509_crt.c b/library/x509_crt.c +index 53cdcf0266..dd3c83a91a 100644 +--- a/library/x509_crt.c ++++ b/library/x509_crt.c +@@ -71,6 +71,10 @@ #endif /* !_WIN32 || EFIX64 || EFI32 */ #endif @@ -57,9 +65,9 @@ index cf62532f2..8d058a092 100644 /* * Item in a verification chain: cert and flags for it */ -@@ -995,6 +999,12 @@ static int x509_crt_parse_der_core(mbedtls_x509_crt *crt, +@@ -1113,6 +1117,12 @@ static int x509_crt_parse_der_core(mbedtls_x509_crt *crt, end = crt_end = p + len; - crt->raw.len = crt_end - buf; + crt->raw.len = (size_t) (crt_end - buf); if (make_copy != 0) { +#if defined(MBEDTLS_X509_CRT_POOL) + crt->raw.p = p = x509_crt_pool_ref_buf(buf, crt->raw.len); @@ -70,7 +78,7 @@ index cf62532f2..8d058a092 100644 /* Create and populate a new buffer for the raw field. */ crt->raw.p = p = mbedtls_calloc(1, crt->raw.len); if (crt->raw.p == NULL) { -@@ -1002,6 +1012,7 @@ static int x509_crt_parse_der_core(mbedtls_x509_crt *crt, +@@ -1120,6 +1130,7 @@ static int x509_crt_parse_der_core(mbedtls_x509_crt *crt, } memcpy(crt->raw.p, buf, crt->raw.len); @@ -78,24 +86,23 @@ index cf62532f2..8d058a092 100644 crt->own_buffer = 1; p += crt->raw.len - len; -@@ -2839,8 +2850,12 @@ void mbedtls_x509_crt_free(mbedtls_x509_crt *crt) - mbedtls_asn1_sequence_free(cert_cur->certificate_policies.next); +@@ -3246,7 +3257,11 @@ void mbedtls_x509_crt_free(mbedtls_x509_crt *crt) + mbedtls_asn1_sequence_free(cert_cur->authority_key_id.authorityCertIssuer.next); if (cert_cur->raw.p != NULL && cert_cur->own_buffer) { +#if defined(MBEDTLS_X509_CRT_POOL) + x509_crt_pool_unref_buf(cert_cur->raw.p); +#else - mbedtls_platform_zeroize(cert_cur->raw.p, cert_cur->raw.len); - mbedtls_free(cert_cur->raw.p); + mbedtls_zeroize_and_free(cert_cur->raw.p, cert_cur->raw.len); +#endif } cert_prv = cert_cur; -diff --git mbedtls/library/x509_crt_pool.c mbedtls/library/x509_crt_pool.c +diff --git a/library/x509_crt_pool.c b/library/x509_crt_pool.c new file mode 100644 -index 000000000..da00c88a8 +index 0000000000..da00c88a85 --- /dev/null -+++ mbedtls/library/x509_crt_pool.c ++++ b/library/x509_crt_pool.c @@ -0,0 +1,142 @@ +/* + * X.509 certificate pool @@ -239,11 +246,11 @@ index 000000000..da00c88a8 +} + +#endif /* MBEDTLS_X509_CRT_POOL */ -diff --git mbedtls/library/x509_crt_pool.h mbedtls/library/x509_crt_pool.h +diff --git a/library/x509_crt_pool.h b/library/x509_crt_pool.h new file mode 100644 -index 000000000..8592761de +index 0000000000..8592761de4 --- /dev/null -+++ mbedtls/library/x509_crt_pool.h ++++ b/library/x509_crt_pool.h @@ -0,0 +1,30 @@ +/** + * \file x509_crt_pool.h @@ -277,4 +284,3 @@ index 000000000..8592761de +#endif /* mbedtls_x509_crt_pool.h */ -- 2.40.0 - diff --git a/crypto/mbedtls/Kconfig b/crypto/mbedtls/Kconfig index 87c4e76a50..e04d7d4ecb 100644 --- a/crypto/mbedtls/Kconfig +++ b/crypto/mbedtls/Kconfig @@ -13,7 +13,7 @@ if CRYPTO_MBEDTLS config MBEDTLS_VERSION string "Mbed TLS Version" - default "3.4.0" + default "3.6.2" config MBEDTLS_DEBUG_C bool "This module provides debugging functions." @@ -103,7 +103,7 @@ config MBEDTLS_SSL_DTLS_HELLO_VERIFY default y config MBEDTLS_SSL_DTLS_CONNECTION_ID - bool "Enable the Connection ID extension." + bool "Enable support for the DTLS Connection ID (CID) extension." default y config MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT @@ -138,6 +138,10 @@ config MBEDTLS_NET_C bool "Enable the TCP and UDP over IPv6/IPv4 networking routines" default LIBC_NETDB +config MBEDTLS_OID_C + bool "Enable the OID database." + default y + config MBEDTLS_ECDSA_C bool "Enable the elliptic curve DSA library." default y @@ -154,8 +158,19 @@ config MBEDTLS_PEM_WRITE_C bool "Enable PEM encoding / writing." default y +config MBEDTLS_PK_C + bool "Enable the generic public (asymmetric) key layer." + depends on MBEDTLS_MD_C && MBEDTLS_RSA_C && MBEDTLS_ECP_C + default y + +config MBEDTLS_PK_PARSE_C + bool "Enable the generic public (asymmetric) key parser" + depends on MBEDTLS_ASN1_PARSE_C && MBEDTLS_OID_C && MBEDTLS_PK_C + default y + config MBEDTLS_PK_WRITE_C bool "Enable the generic public (asymmetric) key writer." + depends on MBEDTLS_ASN1_WRITE_C && MBEDTLS_OID_C && MBEDTLS_PK_C default y config MBEDTLS_X509_CREATE_C @@ -319,6 +334,10 @@ config MBEDTLS_PK_PARSE_EC_EXTENDED bool "Enhance support for reading EC keys using variants of SEC1 not allowed by RFC 5915 and RFC 5480." default y +config MBEDTLS_PK_PARSE_EC_COMPRESSED + bool "Enable the support for parsing public keys of type Short Weierstrass (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX) which are using the compressed point format." + default y + config MBEDTLS_ERROR_STRERROR_DUMMY bool "Enable a dummy error function to make use of mbedtls_strerror()." default y @@ -331,11 +350,24 @@ config MBEDTLS_PK_RSA_ALT_SUPPORT bool "Support external private RSA keys (eg from a HSM) in the PK layer." default y +config MBEDTLS_PKCS1_V21 + bool "Enable support for PKCS#1 v2.1 encoding." + default y + config MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG bool "Make the PSA Crypto module use an external random generator provided by a driver, instead of Mbed TLS's entropy and DRBG modules." depends on DEV_RANDOM default n +config MBEDTLS_PSA_KEY_STORE_DYNAMIC + bool "Dynamically resize the PSA key store to accommodate any number of volatile keys (until the heap memory is exhausted)." + depends on MBEDTLS_PSA_CRYPTO_C + default y + +config MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS + bool "Assume all buffers passed to PSA functions are owned exclusively by the PSA function and are not stored in shared memory." + default n + config MBEDTLS_SSL_CONTEXT_SERIALIZATION bool "Enable serialization of the TLS context structures." depends on MBEDTLS_GCM_C || MBEDTLS_CCM_C || MBEDTLS_CHACHAPOLY_C @@ -357,23 +389,43 @@ config MBEDTLS_SSL_MAX_FRAGMENT_LENGTH bool "Enable support for RFC 6066 max_fragment_length extension in SSL." default y +config MBEDTLS_SSL_PROTO_TLS1_2 + bool "Enable support for TLS 1.2 (and DTLS 1.2 if DTLS is enabled)." + depends on (MBEDTLS_USE_PSA_CRYPTO ||\ + (MBEDTLS_MD_C && (MBEDTLS_SHA256_C || MBEDTLS_SHA384_C))) + default y + help + If MBEDTLS_USE_PSA_CRYPTO is set, then PSA_WANT_ALG_SHA_256 or PSA_WANT_ALG_SHA_384 + must be defined. + +config MBEDTLS_SSL_PROTO_TLS1_3 + bool "Enable support for TLS 1.3." + depends on MBEDTLS_SSL_KEEP_PEER_CERTIFICATE && MBEDTLS_PSA_CRYPTO_C + default y + +config MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE + bool "Enable TLS 1.3 middlebox compatibility mode." + default y + config MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED bool "Enable TLS 1.3 PSK key exchange mode." default y config MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED bool "Enable TLS 1.3 ephemeral key exchange mode." - depends on MBEDTLS_ECDH_C + depends on MBEDTLS_X509_CRT_PARSE_C && \ + (MBEDTLS_ECDSA_C || MBEDTLS_USE_PSA_CRYPTO || MBEDTLS_PKCS1_V21) default y + help + Requires PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH to be defined. Also, if + MBEDTLS_USE_PSA_CRYPTO is used to satisfy its dependencies, then PSA_WANT_ALG_ECDSA + must also be defined. config MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED bool "Enable TLS 1.3 PSK ephemeral key exchange mode." - depends on MBEDTLS_ECDH_C default y - -config MBEDTLS_SSL_MAX_EARLY_DATA_SIZE - int "The default maximum amount of 0-RTT data." - default 1024 + help + Requires PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH. config MBEDTLS_SSL_SESSION_TICKETS bool "Enable support for RFC 5077 session tickets in SSL." @@ -388,6 +440,11 @@ config MBEDTLS_THREADING_PTHREAD depends on MBEDTLS_THREADING_C default n +config MBEDTLS_USE_PSA_CRYPTO + bool "Make the X.509 and TLS library use PSA for cryptographic operations, and enable new APIs for using keys handled by PSA Crypto." + depends on MBEDTLS_PSA_CRYPTO_C + default n + config MBEDTLS_VERSION_FEATURES bool "Allow run-time checking of compile-time enabled features." depends on MBEDTLS_VERSION_C @@ -395,11 +452,24 @@ config MBEDTLS_VERSION_FEATURES config MBEDTLS_X509_RSASSA_PSS_SUPPORT bool "Enable parsing and verification of X.509 certificates, CRLs and CSRS signed with RSASSA-PSS." + depends on MBEDTLS_PKCS1_V21 default y config MBEDTLS_AESCE_C bool "Enable AES cryptographic extension support on 64-bit Arm." - depends on MBEDTLS_HAVE_ASM + depends on MBEDTLS_AES_C + default y + +config MBEDTLS_AES_C + bool "Enable the AES block cipher." + default y + +config MBEDTLS_ASN1_PARSE_C + bool "Enable the generic ASN1 parser." + default y + +config MBEDTLS_ASN1_WRITE_C + bool "Enable the generic ASN1 writer." default y config MBEDTLS_ARIA_C @@ -474,17 +544,32 @@ config MBEDTLS_NIST_KW_C bool "Enable the Key Wrapping mode for 128-bit block ciphers." default y +config MBEDTLS_MD_C + bool "Enable the generic layer for message digest (hashing) and HMAC." + depends on MBEDTLS_MD5_C || MBEDTLS_RIPEMD160_C || MBEDTLS_SHA1_C ||\ + MBEDTLS_SHA224_C || MBEDTLS_SHA256_C || MBEDTLS_SHA384_C ||\ + MBEDTLS_SHA512_C || MBEDTLS_PSA_CRYPTO_C + default y + +config MBEDTLS_MD5_C + bool "Enable the MD5 hash algorithm." + default y + config MBEDTLS_PKCS5_C bool "Enable PKCS#5 functions." + select MBEDTLS_MD_C default y config MBEDTLS_PKCS7_C bool "Enable PKCS #7 core for using PKCS #7-formatted signatures." - depends on MBEDTLS_X509_CRL_PARSE_C + depends on MBEDTLS_ASN1_PARSE_C && MBEDTLS_OID_C && MBEDTLS_PK_PARSE_C &&\ + MBEDTLS_X509_CRT_PARSE_C && MBEDTLS_X509_CRL_PARSE_C &&\ + MBEDTLS_MD_C default y config MBEDTLS_PKCS12_C bool "Enable PKCS#12 PBE functions." + depends on MBEDTLS_ASN1_PARSE_C && (MBEDTLS_MD_C || MBEDTLS_PSA_CRYPTO_C) default y config MBEDTLS_PLATFORM_C @@ -512,6 +597,23 @@ config MBEDTLS_RIPEMD160_C bool "Enable the RIPEMD-160 hash algorithm." default y +config MBEDTLS_RSA_C + bool "Enable the RSA public-key cryptosystem." + depends on MBEDTLS_OID_C + default y + +config MBEDTLS_SHA1_C + bool "Enable the SHA1 cryptographic hash algorithm." + default y + +config MBEDTLS_SHA224_C + bool "Enable the SHA-224 cryptographic hash algorithm." + default y + +config MBEDTLS_SHA256_C + bool "Enable the SHA-256 cryptographic hash algorithm." + default y + config MBEDTLS_SHA384_C bool "Enable the SHA-384 cryptographic hash algorithm." default y @@ -520,6 +622,10 @@ config MBEDTLS_SHA512_C bool "Enable SHA-512 cryptographic hash algorithms." default y +config MBEDTLS_SHA3_C + bool "Enable the SHA3 cryptographic hash algorithm." + default y + config MBEDTLS_SSL_CACHE_C bool "Enable simple SSL cache implementation." default y @@ -538,21 +644,19 @@ config MBEDTLS_VERSION_C bool "Enable run-time version information." default y -config MBEDTLS_X509_CRL_PARSE_C - bool "Enable X.509 CRL parsing." +config MBEDTLS_X509_USE_C + bool "Enable X.509 core for using certificates." + depends on MBEDTLS_ASN1_PARSE_C && MBEDTLS_OID_C && MBEDTLS_PK_PARSE_C &&\ + (MBEDTLS_MD_C || MBEDTLS_USE_PSA_CRYPTO) default y -config MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE - int "Maximum time difference in milliseconds tolerated between the age of a ticket from the server and client point of view." - default 6000 - -config MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH - int "Size in bytes of a ticket nonce." - default 32 +config MBEDTLS_X509_CRT_PARSE_C + bool "Enable X.509 certificate parsing." + default y -config MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS - int "Default number of NewSessionTicket messages to be sent by a TLS 1.3 server after handshake completion." - default 1 +config MBEDTLS_X509_CRL_PARSE_C + bool "Enable X.509 CRL parsing." + default y if CRYPTO_CRYPTODEV diff --git a/crypto/mbedtls/include/mbedtls/mbedtls_config.h b/crypto/mbedtls/include/mbedtls/mbedtls_config.h index 77489f8e67..79bb51bd74 100644 --- a/crypto/mbedtls/include/mbedtls/mbedtls_config.h +++ b/crypto/mbedtls/include/mbedtls/mbedtls_config.h @@ -192,19 +192,56 @@ * * Enable the memory allocation layer. * - * By default mbed TLS uses the system-provided calloc() and free(). + * By default Mbed TLS uses the system-provided calloc() and free(). * This allows different allocators (self-implemented or provided) to be * provided to the platform abstraction layer. * - * Enabling MBEDTLS_PLATFORM_MEMORY without the + * Enabling #MBEDTLS_PLATFORM_MEMORY without the * MBEDTLS_PLATFORM_{FREE,CALLOC}_MACROs will provide * "mbedtls_platform_set_calloc_free()" allowing you to set an alternative * calloc() and free() function pointer at runtime. * - * Enabling MBEDTLS_PLATFORM_MEMORY and specifying + * Enabling #MBEDTLS_PLATFORM_MEMORY and specifying * MBEDTLS_PLATFORM_{CALLOC,FREE}_MACROs will allow you to specify the * alternate function at compile time. * + * An overview of how the value of mbedtls_calloc is determined: + * + * - if !MBEDTLS_PLATFORM_MEMORY + * - mbedtls_calloc = calloc + * - if MBEDTLS_PLATFORM_MEMORY + * - if (MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO): + * - mbedtls_calloc = MBEDTLS_PLATFORM_CALLOC_MACRO + * - if !(MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO): + * - Dynamic setup via mbedtls_platform_set_calloc_free is no + * possible with a default value MBEDTLS_PLATFORM_STD_CALLOC. + * - How is MBEDTLS_PLATFORM_STD_CALLOC handled? + * - if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS: + * - MBEDTLS_PLATFORM_STD_CALLOC is not set to anything; + * - MBEDTLS_PLATFORM_STD_MEM_HDR can be included if present; + * - if !MBEDTLS_PLATFORM_NO_STD_FUNCTIONS: + * - if MBEDTLS_PLATFORM_STD_CALLOC is present: + * - User-defined MBEDTLS_PLATFORM_STD_CALLOC is respected; + * - if !MBEDTLS_PLATFORM_STD_CALLOC: + * - MBEDTLS_PLATFORM_STD_CALLOC = calloc + * + * - At this point the presence of MBEDTLS_PLATFORM_STD_CALLOC is + * checked. + * - if !MBEDTLS_PLATFORM_STD_CALLOC + * - MBEDTLS_PLATFORM_STD_CALLOC = uninitialized_calloc + * + * - mbedtls_calloc = MBEDTLS_PLATFORM_STD_CALLOC. + * + * Defining MBEDTLS_PLATFORM_CALLOC_MACRO and #MBEDTLS_PLATFORM_STD_CALLOC at + * the same time is not possible. MBEDTLS_PLATFORM_CALLOC_MACRO and + * MBEDTLS_PLATFORM_FREE_MACRO must both be defined or undefined at the same + * time. #MBEDTLS_PLATFORM_STD_CALLOC and #MBEDTLS_PLATFORM_STD_FREE do not + * have to be defined at the same time, as, if they are used, dynamic setup + * of these functions is possible. See the tree above to see how are they + * handled in all cases. An uninitialized #MBEDTLS_PLATFORM_STD_CALLOC always + * fails, returning a null pointer. An uninitialized + * #MBEDTLS_PLATFORM_STD_FREE does not do anything. + * * Requires: MBEDTLS_PLATFORM_C * * Enable this layer to allow use of alternative memory allocators. @@ -236,10 +273,10 @@ /** * \def MBEDTLS_PLATFORM_EXIT_ALT * - * MBEDTLS_PLATFORM_XXX_ALT: Uncomment a macro to let mbed TLS support the + * MBEDTLS_PLATFORM_XXX_ALT: Uncomment a macro to let Mbed TLS support the * function in the platform abstraction layer. * - * Example: In case you uncomment MBEDTLS_PLATFORM_PRINTF_ALT, mbed TLS will + * Example: In case you uncomment MBEDTLS_PLATFORM_PRINTF_ALT, Mbed TLS will * provide a function "mbedtls_platform_set_printf()" that allows you to set * an alternative printf function pointer. * @@ -266,8 +303,54 @@ * #define MBEDTLS_PLATFORM_VSNPRINTF_ALT * #define MBEDTLS_PLATFORM_NV_SEED_ALT * #define MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT + * #define MBEDTLS_PLATFORM_MS_TIME_ALT */ +/** + * Uncomment the macro to let Mbed TLS use your alternate implementation of + * mbedtls_platform_gmtime_r(). This replaces the default implementation in + * platform_util.c. + * + * gmtime() is not a thread-safe function as defined in the C standard. The + * library will try to use safer implementations of this function, such as + * gmtime_r() when available. However, if Mbed TLS cannot identify the target + * system, the implementation of mbedtls_platform_gmtime_r() will default to + * using the standard gmtime(). In this case, calls from the library to + * gmtime() will be guarded by the global mutex + * mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is enabled. We + * recommend that calls from outside the library are also guarded with this + * mutex to avoid race conditions. However, if the macro + * MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, Mbed TLS will unconditionally + * use the implementation for mbedtls_platform_gmtime_r() supplied at + * compile time. + */ + +/* #define MBEDTLS_PLATFORM_GMTIME_R_ALT */ + +/** + * Uncomment the macro to let Mbed TLS use your alternate implementation of + * mbedtls_platform_zeroize(), to wipe sensitive data in memory. This + * replaces the default implementation in platform_util.c. + * + * By default, the library uses a system function such as memset_s() + * (optional feature of C11), explicit_bzero() (BSD and compatible), or + * SecureZeroMemory (Windows). If no such function is detected, the library + * falls back to a plain C implementation. Compilers are technically + * permitted to optimize this implementation out, meaning that the memory is + * not actually wiped. The library tries to prevent that, but the C language + * makes it impossible to guarantee that the memory will always be wiped. + * + * If your platform provides a guaranteed method to wipe memory which + * `platform_util.c` does not detect, define this macro to the name of + * a function that takes two arguments, a `void *` pointer and a length, + * and wipes that many bytes starting at the specified address. For example, + * if your platform has explicit_bzero() but `platform_util.c` does not + * detect its presence, define `MBEDTLS_PLATFORM_ZEROIZE_ALT` to be + * `explicit_bzero` to use that function as mbedtls_platform_zeroize(). + */ + +/* #define MBEDTLS_PLATFORM_ZEROIZE_ALT */ + /** * \def MBEDTLS_DEPRECATED_WARNING * @@ -302,7 +385,7 @@ /** \} name SECTION: System support */ /** - * \name SECTION: mbed TLS feature support + * \name SECTION: Mbed TLS feature support * * This section sets support for features that are or are not needed * within the modules that are enabled. @@ -326,7 +409,7 @@ /** * \def MBEDTLS_AES_ALT * - * MBEDTLS__MODULE_NAME__ALT: Uncomment a macro to let mbed TLS use your + * MBEDTLS__MODULE_NAME__ALT: Uncomment a macro to let Mbed TLS use your * alternate core implementation of a symmetric crypto, an arithmetic or hash * module (e.g. platform specific assembly optimized implementations). Keep * in mind that the function prototypes should remain the same. @@ -334,7 +417,7 @@ * This replaces the whole module. If you only want to replace one of the * functions, use one of the MBEDTLS__FUNCTION_NAME__ALT flags. * - * Example: In case you uncomment MBEDTLS_AES_ALT, mbed TLS will no longer + * Example: In case you uncomment MBEDTLS_AES_ALT, Mbed TLS will no longer * provide the "struct mbedtls_aes_context" definition and omit the base * function declarations and implementations. "aes_alt.h" will be included * from "aes.h" to include the new function definitions. @@ -342,18 +425,17 @@ * Uncomment a macro to enable alternate implementation of the corresponding * module. * - * \warning MD2, MD4, MD5, ARC4, DES and SHA-1 are considered weak and - * their use constitutes a security risk. If possible, we - * recommend avoiding dependencies on them, and considering - * stronger message digests and ciphers instead. + * \warning MD5, DES and SHA-1 are considered weak and their + * use constitutes a security risk. If possible, we recommend + * avoiding dependencies on them, and considering stronger message + * digests and ciphers instead. * */ #ifdef CONFIG_MBEDTLS_AES_ALT #define MBEDTLS_AES_ALT #endif -/* #define MBEDTLS_ARC4_ALT - * #define MBEDTLS_ARIA_ALT +/* #define MBEDTLS_ARIA_ALT * #define MBEDTLS_BLOWFISH_ALT * #define MBEDTLS_CAMELLIA_ALT * #define MBEDTLS_CCM_ALT @@ -368,8 +450,6 @@ * #define MBEDTLS_ECJPAKE_ALT * #define MBEDTLS_GCM_ALT * #define MBEDTLS_NIST_KW_ALT - * #define MBEDTLS_MD2_ALT - * #define MBEDTLS_MD4_ALT */ #ifdef CONFIG_MBEDTLS_MD5_ALT #define MBEDTLS_MD5_ALT @@ -405,20 +485,18 @@ /** * \def MBEDTLS_SHA256_PROCESS_ALT * - * MBEDTLS__FUNCTION_NAME__ALT: Uncomment a macro to let mbed TLS use you - * alternate core implementation of symmetric crypto or hash function. - * Keep in mind that function prototypes should remain the same. + * MBEDTLS__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use you + * alternate core implementation of symmetric crypto or hash function. Keep + * in mind that function prototypes should remain the same. * - * This replaces only one function. The header file from mbed TLS is still + * This replaces only one function. The header file from Mbed TLS is still * used, in contrast to the MBEDTLS__MODULE_NAME__ALT flags. * - * Example: In case you uncomment MBEDTLS_SHA256_PROCESS_ALT, mbed TLS will + * Example: In case you uncomment MBEDTLS_SHA256_PROCESS_ALT, Mbed TLS will * no longer provide the mbedtls_sha1_process() function, but it will still * provide the other function (using your mbedtls_sha1_process() function) * and the definition of mbedtls_sha1_context, so your implementation of - * mbedtls_sha1_process must be compatible - * - * with this definition. + * mbedtls_sha1_process must be compatible with this definition. * * \note If you use the AES_xxx_ALT macros, then it is recommended to also * set MBEDTLS_AES_ROM_TABLES in order to help the linker @@ -427,25 +505,23 @@ * Uncomment a macro to enable alternate implementation of the corresponding * function. * - * \warning MD2, MD4, MD5, DES and SHA-1 are considered weak and their use + * \warning MD5, DES and SHA-1 are considered weak and their use * constitutes a security risk. If possible, we recommend avoiding * dependencies on them, and considering stronger message digests * and ciphers instead. * * \warning If both MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_DETERMINISTIC * are enabled, then the deterministic ECDH signature functions - * pass the the static HMAC-DRBG as RNG to mbedtls_ecdsa_sign(). + * pass the static HMAC-DRBG as RNG to mbedtls_ecdsa_sign(). * Therefore alternative implementations should use the RNG only - * for generating the ephemeral key and nothing else. + * for generating the ephemeral key and nothing else. If this is + * not possible, then MBEDTLS_ECDSA_DETERMINISTIC should be + * disabled and an alternative implementation should be provided + * for mbedtls_ecdsa_sign_det_ext(). * - * If this is not possible, then MBEDTLS_ECDSA_DETERMINISTIC - * should be disabled and an alternative implementation should - * be provided for mbedtls_ecdsa_sign_det_ext(). */ -/* #define MBEDTLS_MD2_PROCESS_ALT - * #define MBEDTLS_MD4_PROCESS_ALT - * #define MBEDTLS_MD5_PROCESS_ALT +/* #define MBEDTLS_MD5_PROCESS_ALT * #define MBEDTLS_RIPEMD160_PROCESS_ALT * #define MBEDTLS_SHA1_PROCESS_ALT * #define MBEDTLS_SHA256_PROCESS_ALT @@ -505,7 +581,7 @@ * mbedtls_internal_ecp_double_jac() if the group for the operation is * supported by your implementation (i.e. * yourmbedtls_internal_ecp_grp_capable() function returns 1 for this group) - * group is not supported by your implementation, then the original mbed TLS + * group is not supported by your implementation, then the original Mbed TLS * If the implementation of ecp_double_jac() is used instead, unless this * fallback behaviour is disabled by setting MBEDTLS_ECP_NO_FALLBACK * (in which case ecp_double_jac() will return @@ -547,7 +623,7 @@ /** * \def MBEDTLS_ENTROPY_HARDWARE_ALT * - * Uncomment this macro to let mbed TLS use your own implementation of a + * Uncomment this macro to let Mbed TLS use your own implementation of a * hardware entropy collector. * * Your function must be called \c mbedtls_hardware_poll(), have the same @@ -605,6 +681,41 @@ /* #define MBEDTLS_AES_FEWER_TABLES */ +/** + * \def MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH + * + * Use only 128-bit keys in AES operations to save ROM. + * + * Uncomment this macro to remove support for AES operations that use 192- + * or 256-bit keys. + * + * Uncommenting this macro reduces the size of AES code by ~300 bytes + * on v8-M/Thumb2. + * + * Module: library/aes.c + * + * Requires: MBEDTLS_AES_C + */ + +/* #define MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH */ + +/** + * \def MBEDTLS_AES_USE_HARDWARE_ONLY + * + * Disable plain C implementation for AES. + * + * When the plain C implementation is enabled, and an implementation using a + * special CPU feature (such as MBEDTLS_AESCE_C) is also enabled, runtime + * detection will be used to select between them. + * + * If only one implementation is present, runtime detection will not be used. + * This configuration will crash at runtime if running on a CPU without the + * necessary features. It will not build unless at least one of + * MBEDTLS_AESCE_C and/or MBEDTLS_AESNI_C is enabled & present in the build. + */ + +/* #define MBEDTLS_AES_USE_HARDWARE_ONLY */ + /** * \def MBEDTLS_CAMELLIA_SMALL_MEMORY * @@ -742,11 +853,26 @@ /** \def MBEDTLS_CTR_DRBG_USE_128_BIT_KEY * * Uncomment this macro to use a 128-bit key in the CTR_DRBG module. - * By default, CTR_DRBG uses a 256-bit key. + * Without this, CTR_DRBG uses a 256-bit key + * unless \c MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH is set. */ /* #define MBEDTLS_CTR_DRBG_USE_128_BIT_KEY */ +/** + * Enable the verified implementations of ECDH primitives from Project + * Everest (currently only Curve25519). This feature changes the layout of + * ECDH contexts and therefore is a compatibility break for applications that + * access fields of a mbedtls_ecdh_context structure directly. See also + * MBEDTLS_ECDH_LEGACY_CONTEXT in include/mbedtls/ecdh.h. + * + * The Everest code is provided under the Apache 2.0 license only; therefore + * enabling this option is not compatible with taking the library under the + * GPL v2.0-or-later license. + */ + +/* #define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED */ + /** * \def MBEDTLS_ECP_DP_SECP192R1_ENABLED * @@ -869,6 +995,15 @@ #define MBEDTLS_ECP_RESTARTABLE #endif +/** + * Uncomment to enable using new bignum code in the ECC modules. + * + * \warning This is currently experimental, incomplete and therefore should + * not be used in production. + */ + +/* #define MBEDTLS_ECP_WITH_MPI_UINT */ + /** * \def MBEDTLS_ECDSA_DETERMINISTIC * @@ -943,7 +1078,7 @@ * * Enable the ECDHE-PSK based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -1062,7 +1197,9 @@ * * Enable the ECDHE-RSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_RSA_C + * MBEDTLS_PKCS1_V15 * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are @@ -1087,7 +1224,10 @@ * * Enable the ECDHE-ECDSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C, + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and + * PSA_WANT_ALG_ECDSA) + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -1111,7 +1251,10 @@ * * Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and + * PSA_WANT_ALG_ECDSA) + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -1135,7 +1278,9 @@ * * Enable the ECDH-RSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_X509_CRT_PARSE_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_RSA_C + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -1163,10 +1308,15 @@ * Thread v1.0.0 specification; incompatible changes to the specification * might still happen. For this reason, this is disabled by default. * - * Requires: MBEDTLS_ECJPAKE_C - * SHA-256 (via MD if present, or via PSA, see MBEDTLS_ECJPAKE_C) + * Requires: MBEDTLS_ECJPAKE_C or (MBEDTLS_USE_PSA_CRYPTO and + * PSA_WANT_ALG_JPAKE) + * SHA-256 (via MBEDTLS_SHA256_C or a PSA driver) * MBEDTLS_ECP_DP_SECP256R1_ENABLED * + * \warning If SHA-256 is provided only by a PSA driver, you must call + * psa_crypto_init() before the first handshake (even if + * MBEDTLS_USE_PSA_CRYPTO is disabled). + * * This enables the following ciphersuites (if other requisites are * enabled as well): * MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8 @@ -1190,6 +1340,22 @@ #define MBEDTLS_PK_PARSE_EC_EXTENDED #endif +/** + * \def MBEDTLS_PK_PARSE_EC_COMPRESSED + * + * Enable the support for parsing public keys of type Short Weierstrass + * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX) which are using the + * compressed point format. This parsing is done through ECP module's + * functions. + * + * \note As explained in the description of MBEDTLS_ECP_PF_COMPRESSED + * (in ecp.h) the only unsupported curves are MBEDTLS_ECP_DP_SECP224R1 + * and MBEDTLS_ECP_DP_SECP224K1. + */ +#ifdef CONFIG_MBEDTLS_PK_PARSE_EC_COMPRESSED +#define MBEDTLS_PK_PARSE_EC_COMPRESSED +#endif + /** * \def MBEDTLS_ERROR_STRERROR_DUMMY * @@ -1367,19 +1533,16 @@ * * Enable support for PKCS#1 v2.1 encoding. * - * Requires: MBEDTLS_RSA_C and (MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C). - * - * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init() - * before doing any PKCS#1 v2.1 operation. + * Requires: MBEDTLS_RSA_C * - * \warning When building with MBEDTLS_MD_C, all hashes used with this - * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C, - * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by - * this module in builds where MBEDTLS_MD_C is disabled. + * \warning If using a hash that is only provided by PSA drivers, you must + * call psa_crypto_init() before doing any PKCS#1 v2.1 operation. * * This enables support for RSAES-OAEP and RSASSA-PSS operations. */ +#ifdef CONFIG_MBEDTLS_PKCS1_V21 #define MBEDTLS_PKCS1_V21 +#endif /** \def MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS * @@ -1415,19 +1578,6 @@ /* #define MBEDTLS_PSA_CRYPTO_CLIENT */ -/** \def MBEDTLS_PSA_CRYPTO_DRIVERS - * - * Enable support for the experimental PSA crypto driver interface. - * - * Requires: MBEDTLS_PSA_CRYPTO_C - * - * \warning This interface is experimental. We intend to maintain backward - * compatibility with application code that relies on drivers, - * but the driver interfaces may change without notice. - */ - -/* #define MBEDTLS_PSA_CRYPTO_DRIVERS */ - /** \def MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG * * Make the PSA Crypto module use an external random generator provided @@ -1452,8 +1602,8 @@ * ); * ``` * The \c context value is initialized to 0 before the first call. - * The function must fill the \c output buffer with \p output_size bytes - * of random data and set \c *output_length to \p output_size. + * The function must fill the \c output buffer with \c output_size bytes + * of random data and set \c *output_length to \c output_size. * * Requires: MBEDTLS_PSA_CRYPTO_C * @@ -1477,6 +1627,13 @@ * NSPE (Non-Secure Process Environment) and an SPE (Secure Process * Environment). * + * If you enable this option, your build environment must include a header + * file `"crypto_spe.h"` (either in the `psa` subdirectory of the Mbed TLS + * header files, or in another directory on the compiler's include search + * path). Alternatively, your platform may customize the header + * `psa/crypto_platform.h`, in which case it can skip or replace the + * inclusion of `"crypto_spe.h"`. + * * Module: library/psa_crypto.c * Requires: MBEDTLS_PSA_CRYPTO_C * @@ -1484,6 +1641,68 @@ /* #define MBEDTLS_PSA_CRYPTO_SPM */ +/** + * \def MBEDTLS_PSA_KEY_STORE_DYNAMIC + * + * Dynamically resize the PSA key store to accommodate any number of + * volatile keys (until the heap memory is exhausted). + * + * If this option is disabled, the key store has a fixed size + * #MBEDTLS_PSA_KEY_SLOT_COUNT for volatile keys and loaded persistent keys + * together. + * + * This option has no effect when #MBEDTLS_PSA_CRYPTO_C is disabled. + * + * Module: library/psa_crypto.c + * Requires: MBEDTLS_PSA_CRYPTO_C + */ +#ifdef CONFIG_MBEDTLS_PSA_KEY_STORE_DYNAMIC +#define MBEDTLS_PSA_KEY_STORE_DYNAMIC +#endif + +/** + * Uncomment to enable p256-m. This is an alternative implementation of + * key generation, ECDH and (randomized) ECDSA on the curve SECP256R1. + * Compared to the default implementation: + * + * - p256-m has a much smaller code size and RAM footprint. + * - p256-m is only available via the PSA API. This includes the pk module + * when #MBEDTLS_USE_PSA_CRYPTO is enabled. + * - p256-m does not support deterministic ECDSA, EC-JPAKE, custom protocols + * over the core arithmetic, or deterministic derivation of keys. + * + * We recommend enabling this option if your application uses the PSA API + * and the only elliptic curve support it needs is ECDH and ECDSA over + * SECP256R1. + * + * If you enable this option, you do not need to enable any ECC-related + * MBEDTLS_xxx option. You do need to separately request support for the + * cryptographic mechanisms through the PSA API: + * - #MBEDTLS_PSA_CRYPTO_C and #MBEDTLS_PSA_CRYPTO_CONFIG for PSA-based + * configuration; + * - #MBEDTLS_USE_PSA_CRYPTO if you want to use p256-m from PK, X.509 or TLS; + * - #PSA_WANT_ECC_SECP_R1_256; + * - #PSA_WANT_ALG_ECDH and/or #PSA_WANT_ALG_ECDSA as needed; + * - #PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY, + * #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC, + * #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT, + * #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT and/or + * #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE as needed. + * + * \note To benefit from the smaller code size of p256-m, make sure that you + * do not enable any ECC-related option not supported by p256-m: this + * would cause the built-in ECC implementation to be built as well, in + * order to provide the required option. + * Make sure #PSA_WANT_ALG_DETERMINISTIC_ECDSA, #PSA_WANT_ALG_JPAKE and + * #PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE, and curves other than + * SECP256R1 are disabled as they are not supported by this driver. + * Also, avoid defining #MBEDTLS_PK_PARSE_EC_COMPRESSED or + * #MBEDTLS_PK_PARSE_EC_EXTENDED as those currently require a subset of + * the built-in ECC implementation, see docs/driver-only-builds.md. + */ + +/* #define MBEDTLS_PSA_P256M_DRIVER_ENABLED */ + /** * \def MBEDTLS_PSA_INJECT_ENTROPY * @@ -1498,6 +1717,29 @@ /* #define MBEDTLS_PSA_INJECT_ENTROPY */ +/** + * \def MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS + * + * Assume all buffers passed to PSA functions are owned exclusively by the + * PSA function and are not stored in shared memory. + * + * This option may be enabled if all buffers passed to any PSA function + * reside in memory that is accessible only to the PSA function during its + * execution. + * + * This option MUST be disabled whenever buffer arguments are in memory + * shared with an untrusted party, for example where arguments to PSA calls + * are passed across a trust boundary. + * + * \note Enabling this option reduces memory usage and code size. + * + * \note Enabling this option causes overlap of input and output buffers + * not to be supported by PSA functions. + */ +#ifdef CONFIG_MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS +#define MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS +#endif + /** * \def MBEDTLS_RSA_NO_CRT * @@ -1551,13 +1793,12 @@ * \def MBEDTLS_SSL_ALL_ALERT_MESSAGES * * Enable sending of alert messages in case of encountered errors as per RFC. - * If you choose not to send the alert messages, mbed TLS can still - *communicate - * with other servers, only debugging of failures is harder. + * If you choose not to send the alert messages, Mbed TLS can still + * communicate with other servers, only debugging of failures is harder. * * The advantage of not sending alert messages, is that no information is - *given - * about reasons for failures thus preventing adversaries of gaining intel. + * given about reasons for failures thus preventing adversaries of gaining + * intel. * * Enable sending of all alert messages */ @@ -1610,7 +1851,8 @@ * Requires: MBEDTLS_SSL_DTLS_CONNECTION_ID */ #ifdef CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT -#define MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT +#define MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT \ + CONFIG_MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT #endif /** @@ -1748,6 +1990,8 @@ * it has been associated with security issues in the past and is easy to * misuse/misunderstand. * + * Requires: MBEDTLS_SSL_PROTO_TLS1_2 + * * Comment this to disable support for renegotiation. * * \note Even if this option is disabled, both client and server are aware @@ -1779,10 +2023,6 @@ * Enable support for RFC 8449 record_size_limit extension in SSL (TLS 1.3 *only). * - * \warning This extension is currently in development and must NOT be used - *except - * for testing purposes. - * * Requires: MBEDTLS_SSL_PROTO_TLS1_3 * * Uncomment this macro to enable support for the record_size_limit extension @@ -1796,34 +2036,36 @@ * Enable support for TLS 1.2 (and DTLS 1.2 if DTLS is enabled). * * Requires: Without MBEDTLS_USE_PSA_CRYPTO: MBEDTLS_MD_C and - * (MBEDTLS_SHA1_C or MBEDTLS_SHA256_C or MBEDTLS_SHA512_C) + * (MBEDTLS_SHA256_C or MBEDTLS_SHA384_C or + * SHA-256 or SHA-512 provided by a PSA driver) * With MBEDTLS_USE_PSA_CRYPTO: - * PSA_WANT_ALG_SHA_1 or PSA_WANT_ALG_SHA_256 or - * PSA_WANT_ALG_SHA_512 + * PSA_WANT_ALG_SHA_256 or PSA_WANT_ALG_SHA_384 * - * \warning If building with MBEDTLS_USE_PSA_CRYPTO, you must call - * psa_crypto_init() before doing any TLS operations. + * \warning If building with MBEDTLS_USE_PSA_CRYPTO, or if the hash(es) used + * are only provided by PSA drivers, you must call psa_crypto_init() before + * doing any TLS operations. * * Comment this macro to disable support for TLS 1.2 / DTLS 1.2 */ +#ifdef CONFIG_MBEDTLS_SSL_PROTO_TLS1_2 #define MBEDTLS_SSL_PROTO_TLS1_2 +#endif /** * \def MBEDTLS_SSL_PROTO_TLS1_3 * * Enable support for TLS 1.3. * - * \note The support for TLS 1.3 is not comprehensive yet, in particular - * pre-shared keys are not supported. - * See docs/architecture/tls13-support.md for a description of the TLS + * \note See docs/architecture/tls13-support.md for a description of the TLS * 1.3 support that this option enables. * * Requires: MBEDTLS_SSL_KEEP_PEER_CERTIFICATE * Requires: MBEDTLS_PSA_CRYPTO_C * * \note TLS 1.3 uses PSA crypto for cryptographic operations that are - * directly performed by TLS 1.3 code. As a consequence, you must - * call psa_crypto_init() before the first TLS 1.3 handshake. + * directly performed by TLS 1.3 code. As a consequence, when TLS 1.3 + * is enabled, a TLS handshake may call psa_crypto_init(), even + * if it ends up negotiating a different TLS version. * * \note Cryptographic operations performed indirectly via another module * (X.509, PK) or by code shared with TLS 1.2 (record protection, @@ -1832,8 +2074,9 @@ * * Uncomment this macro to enable the support for TLS 1.3. */ - -/* #define MBEDTLS_SSL_PROTO_TLS1_3 */ +#ifdef CONFIG_MBEDTLS_SSL_PROTO_TLS1_3 +#define MBEDTLS_SSL_PROTO_TLS1_3 +#endif /** * \def MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE @@ -1856,8 +2099,9 @@ * effect on the build. * */ - -/* #define MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE */ +#ifdef CONFIG_MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE +#define MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE +#endif /** * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED @@ -1878,8 +2122,12 @@ * * Enable TLS 1.3 ephemeral key exchange mode. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_X509_CRT_PARSE_C, MBEDTLS_ECDSA_C or - * MBEDTLS_PKCS1_V21 + * Requires: PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH + * MBEDTLS_X509_CRT_PARSE_C + * and at least one of: + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and + * PSA_WANT_ALG_ECDSA) + * MBEDTLS_PKCS1_V21 * * Comment to disable support for the ephemeral key exchange mode in TLS 1.3. * If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any @@ -1895,7 +2143,7 @@ * * Enable TLS 1.3 PSK ephemeral key exchange mode. * - * Requires: MBEDTLS_ECDH_C + * Requires: PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH * * Comment to disable support for the PSK ephemeral key exchange mode in * TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not @@ -1915,36 +2163,17 @@ * MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED or * MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED * - * Comment this to disable support for early data. - * If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, - * this option does not have any effect on the build. + * Comment this to disable support for early data. If + * MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any + * effect on the build. * - * This feature is experimental, not completed and thus not ready for - * production. + * \note The maximum amount of early data can be set with + * MBEDTLS_SSL_MAX_EARLY_DATA_SIZE. * */ /* #define MBEDTLS_SSL_EARLY_DATA */ -/** - * \def MBEDTLS_SSL_MAX_EARLY_DATA_SIZE - * - * The default maximum amount of 0-RTT data. See the documentation of - * \c mbedtls_ssl_tls13_conf_max_early_data_size() for more information. - * - * It must be positive and smaller than UINT32_MAX. - * - * If MBEDTLS_SSL_EARLY_DATA is not defined, this default value does not - * have any impact on the build. - * - * This feature is experimental, not completed and thus not ready for - * production. - * - */ -#ifdef CONFIG_MBEDTLS_SSL_MAX_EARLY_DATA_SIZE -#define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE CONFIG_MBEDTLS_SSL_MAX_EARLY_DATA_SIZE -#endif - /** * \def MBEDTLS_SSL_PROTO_DTLS * @@ -2189,28 +2418,38 @@ /** * \def MBEDTLS_USE_PSA_CRYPTO * - * Make the X.509 and TLS library use PSA for cryptographic operations, and - * enable new APIs for using keys handled by PSA Crypto. + * Make the X.509 and TLS libraries use PSA for cryptographic operations as + * much as possible, and enable new APIs for using keys handled by PSA + * Crypto. * * \note Development of this option is currently in progress, and parts of - *Mbed - * TLS's X.509 and TLS modules are not ported to PSA yet. - * However, these parts will still continue to work as usual, - * so enabling this option should not break backwards compatibility. - * - * \note See docs/use-psa-crypto.md for a complete description of what this - * option currently does, and of parts that are not affected by it so far. + * Mbed TLS's X.509 and TLS modules are not ported to PSA yet. However, these + * parts will still continue to work as usual, so enabling this option should + * not break backwards compatibility. * * \warning If you enable this option, you need to call `psa_crypto_init()` - * before calling any function from the SSL/TLS, X.509 or PK modules. + * before calling any function from the SSL/TLS, X.509 or PK modules, except + * for the various mbedtls_xxx_init() functions which can be called at any + * time. + * + * \note An important and desirable effect of this option is that it allows + * PK, X.509 and TLS to take advantage of PSA drivers. For example, enabling + * this option is what allows use of drivers for ECDSA, ECDH and EC J-PAKE in + * those modules. However, note that even with this option disabled, some + * code in PK, X.509, TLS or the crypto library might still use PSA drivers, + * if it can determine it's safe to do so; currently that's the case for + * hashes. + * + * \note See docs/use-psa-crypto.md for a complete description this option. * * Requires: MBEDTLS_PSA_CRYPTO_C. * * Uncomment this to enable internal use of PSA Crypto and new associated *APIs. */ - -/* #define MBEDTLS_USE_PSA_CRYPTO */ +#ifdef CONFIG_MBEDTLS_USE_PSA_CRYPTO +#define MBEDTLS_USE_PSA_CRYPTO +#endif /** * \def MBEDTLS_PSA_CRYPTO_CONFIG @@ -2232,8 +2471,15 @@ * If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies * an alternative header to include instead of include/psa/crypto_config.h. * - * This feature is still experimental and is not ready for production since - * it is not completed. + * \warning This option is experimental, in that the set of `PSA_WANT_XXX` + * symbols is not completely finalized yet, and the configuration + * tooling is not ideally adapted to having two separate + * configuration files. + * Future minor releases of Mbed TLS may make minor changes to those + * symbols, but we will endeavor to provide a transition path. + * Nonetheless, this option is considered mature enough to use in + * production, as long as you accept that you may need to make + * minor changes to psa/crypto_config.h when upgrading Mbed TLS. */ /* #define MBEDTLS_PSA_CRYPTO_CONFIG */ @@ -2295,18 +2541,20 @@ * Enable parsing and verification of X.509 certificates, CRLs and CSRS * signed with RSASSA-PSS (aka PKCS#1 v2.1). * + * Requires: MBEDTLS_PKCS1_V21 + * * Comment this macro to disallow using RSASSA-PSS in certificates. */ #ifdef CONFIG_MBEDTLS_X509_RSASSA_PSS_SUPPORT #define MBEDTLS_X509_RSASSA_PSS_SUPPORT #endif -/** \} name SECTION: mbed TLS feature support */ +/** \} name SECTION: Mbed TLS feature support */ /** - * \name SECTION: mbed TLS modules + * \name SECTION: Mbed TLS modules * - * This section enables or disables entire modules in mbed TLS + * This section enables or disables entire modules in Mbed TLS * \{ */ @@ -2316,7 +2564,7 @@ * Enable AES-NI support on x86-64 or x86-32. * * \note AESNI is only supported with certain compilers and target options: - * - Visual Studio 2013: supported. + * - Visual Studio: supported. * - GCC, x86-64, target not explicitly supporting AESNI: * requires MBEDTLS_HAVE_ASM. * - GCC, x86-32, target not explicitly supporting AESNI: @@ -2347,19 +2595,28 @@ /** * \def MBEDTLS_AESCE_C * - * Enable AES cryptographic extension support on 64-bit Arm. + * Enable AES cryptographic extension support on Armv8. * * Module: library/aesce.c * Caller: library/aes.c * - * Requires: MBEDTLS_HAVE_ASM, MBEDTLS_AES_C + * Requires: MBEDTLS_AES_C * * \warning Runtime detection only works on Linux. For non-Linux operating * system, Armv8-A Cryptographic Extensions must be supported by * the CPU when this option is enabled. * + * \note Minimum compiler versions for this feature when targeting aarch64 + * are Clang 4.0; armclang 6.6; GCC 6.0; or MSVC 2019 version + * 16.11.2. Minimum compiler versions for this feature when + * targeting 32-bit Arm or Thumb are Clang 11.0; armclang 6.20; or + * GCC 6.0. + * + * \note \c CFLAGS must be set to a minimum of \c -march=armv8-a+crypto for + * armclang <= 6.9 + * * This module adds support for the AES Armv8-A Cryptographic Extensions on - *Aarch64 systems. + * Armv8 systems. */ #ifdef CONFIG_MBEDTLS_AESCE_C #define MBEDTLS_AESCE_C @@ -2438,26 +2695,8 @@ * * PEM_PARSE uses AES for decrypting encrypted keys. */ +#ifdef CONFIG_MBEDTLS_AES_C #define MBEDTLS_AES_C - -/** - * \def MBEDTLS_ARC4_C - * - * Enable the ARCFOUR stream cipher. - * - * Module: library/arc4.c - * Caller: library/cipher.c - * - * This module enables the following ciphersuites (if other requisites are - * enabled as well): - * - * \warning ARC4 is considered a weak cipher and its use constitutes a - * security risk. If possible, we recommend avoidng dependencies - * on it, and considering stronger ciphers instead. - * - */ -#ifdef CONFIG_MBEDTLS_ARC4_C -#define MBEDTLS_ARC4_C #endif /** @@ -2472,7 +2711,9 @@ * library/pkcs5.c * library/pkparse.c */ +#ifdef CONFIG_MBEDTLS_ASN1_PARSE_C #define MBEDTLS_ASN1_PARSE_C +#endif /** * \def MBEDTLS_ASN1_WRITE_C @@ -2486,7 +2727,9 @@ * library/x509write_crt.c * library/x509write_csr.c */ +#ifdef CONFIG_MBEDTLS_ASN1_WRITE_C #define MBEDTLS_ASN1_WRITE_C +#endif /** * \def MBEDTLS_BASE64_C @@ -2500,6 +2743,30 @@ */ #define MBEDTLS_BASE64_C +/** + * \def MBEDTLS_BLOCK_CIPHER_NO_DECRYPT + * + * Remove decryption operation for AES, ARIA and Camellia block cipher. + * + * \note This feature is incompatible with insecure block cipher, + * MBEDTLS_DES_C, and cipher modes which always require decryption + * operation, MBEDTLS_CIPHER_MODE_CBC, MBEDTLS_CIPHER_MODE_XTS and + * MBEDTLS_NIST_KW_C. When #MBEDTLS_PSA_CRYPTO_CONFIG is enabled, + * this feature is incompatible with following supported PSA + * equivalence, PSA_WANT_ALG_ECB_NO_PADDING, + * PSA_WANT_ALG_CBC_NO_PADDING, PSA_WANT_ALG_CBC_PKCS7 and + * PSA_WANT_KEY_TYPE_DES. + * + * Module: library/aes.c + * library/aesce.c + * library/aesni.c + * library/aria.c + * library/camellia.c + * library/cipher.c + */ + +/* #define MBEDTLS_BLOCK_CIPHER_NO_DECRYPT */ + /** * \def MBEDTLS_BIGNUM_C * @@ -2700,6 +2967,9 @@ * library/ssl_ciphersuites.c * library/ssl_msg.c * library/ssl_ticket.c (unless MBEDTLS_USE_PSA_CRYPTO is enabled) + * Auto-enabled by: MBEDTLS_PSA_CRYPTO_C depending on which ciphers are + * enabled (see the documentation of that option for + * details). * * Uncomment to enable generic cipher wrappers. */ @@ -2733,6 +3003,16 @@ * The CTR_DRBG generator uses AES-256 by default. * To use AES-128 instead, enable \c MBEDTLS_CTR_DRBG_USE_128_BIT_KEY above. * + * AES support can either be achieved through builtin (MBEDTLS_AES_C) or PSA. + * Builtin is the default option when MBEDTLS_AES_C is defined otherwise PSA + * is used. + * + * \warning When using PSA, the user should call `psa_crypto_init()` before + * using any CTR_DRBG operation (except `mbedtls_ctr_drbg_init()`). + * + * \note AES-128 will be used if \c MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH is + * set. + * * \note To achieve a 256-bit security strength with CTR_DRBG, * you must use AES-256 *and* use sufficient entropy. * See ctr_drbg.h for more details. @@ -2740,7 +3020,9 @@ * Module: library/ctr_drbg.c * Caller: * - * Requires: MBEDTLS_AES_C + * Requires: MBEDTLS_AES_C or + * (PSA_WANT_KEY_TYPE_AES and PSA_WANT_ALG_ECB_NO_PADDING and + * MBEDTLS_PSA_CRYPTO_C) * * This module provides the CTR_DRBG AES random number generator. */ @@ -2860,13 +3142,8 @@ * * Requires: MBEDTLS_ECP_C and either MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C * - * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init() - * before doing any EC J-PAKE operations. - * - * \warning When building with MBEDTLS_MD_C, all hashes used with this - * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C, - * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by - * this module in builds where MBEDTLS_MD_C is disabled. + * \warning If using a hash that is only provided by PSA drivers, you must + * call psa_crypto_init() before doing any EC J-PAKE operations. */ #ifdef CONFIG_MBEDTLS_ECJPAKE_C #define MBEDTLS_ECJPAKE_C @@ -2933,6 +3210,23 @@ #define MBEDTLS_GCM_C #endif +/** + * \def MBEDTLS_GCM_LARGE_TABLE + * + * Enable large pre-computed tables for Galois/Counter Mode (GCM). + * Can significantly increase throughput on systems without GCM hardware + * acceleration (e.g., AESNI, AESCE). + * + * The mbedtls_gcm_context size will increase by 3840 bytes. + * The code size will increase by roughly 344 bytes. + * + * Module: library/gcm.c + * + * Requires: MBEDTLS_GCM_C + */ + +/* #define MBEDTLS_GCM_LARGE_TABLE */ + /** * \def MBEDTLS_HKDF_C * @@ -3020,7 +3314,8 @@ * * Requires: one of: MBEDTLS_MD5_C, MBEDTLS_RIPEMD160_C, MBEDTLS_SHA1_C, * MBEDTLS_SHA224_C, MBEDTLS_SHA256_C, MBEDTLS_SHA384_C, - * MBEDTLS_SHA512_C. + * MBEDTLS_SHA512_C, or MBEDTLS_PSA_CRYPTO_C with at least + * one hash. * Module: library/md.c * Caller: library/constant_time.c * library/ecdsa.c @@ -3043,45 +3338,9 @@ * * Uncomment to enable generic message digest wrappers. */ +#ifdef CONFIG_MBEDTLS_MD_C #define MBEDTLS_MD_C - -/** - * \def MBEDTLS_MD2_C - * - * Enable the MD2 hash algorithm. - * - * Module: library/md2.c - * Caller: - * - * Uncomment to enable support for (rare) MD2-signed X.509 certs. - * - * \warning MD2 is considered a weak message digest and its use constitutes - *a - * security risk. If possible, we recommend avoiding dependencies - *on - * it, and considering stronger message digests instead. - * - */ - -/* #define MBEDTLS_MD2_C */ - -/** - * \def MBEDTLS_MD4_C - * - * Enable the MD4 hash algorithm. - * - * Module: library/md4.c - * Caller: - * - * Uncomment to enable support for (rare) MD4-signed X.509 certs. - * - * \warning MD4 is considered a weak message digest and its use - * constitutes a security risk. If possible, we recommend - * avoiding dependencies on it, and considering stronger - * message digests instead. - */ - -/* #define MBEDTLS_MD4_C */ +#endif /** * \def MBEDTLS_MD5_C @@ -3104,7 +3363,9 @@ * it, and considering stronger message digests instead. * */ +#ifdef CONFIG_MBEDTLS_MD5_C #define MBEDTLS_MD5_C +#endif /** * \def MBEDTLS_MEMORY_BUFFER_ALLOC_C @@ -3116,7 +3377,7 @@ * Module: library/memory_buffer_alloc.c * * Requires: MBEDTLS_PLATFORM_C - * MBEDTLS_PLATFORM_MEMORY (to use it within mbed TLS) + * MBEDTLS_PLATFORM_MEMORY (to use it within Mbed TLS) * * Enable this module to enable the buffer memory allocator. */ @@ -3166,7 +3427,9 @@ * * This modules translates between OIDs and internal values. */ +#ifdef CONFIG_MBEDTLS_OID_C #define MBEDTLS_OID_C +#endif /** * \def MBEDTLS_PADLOCK_C @@ -3197,6 +3460,10 @@ * library/x509_csr.c * * Requires: MBEDTLS_BASE64_C + * optionally MBEDTLS_MD5_C, or PSA Crypto with MD5 (see below) + * + * \warning When parsing password-protected files, if MD5 is provided only by + * a PSA driver, you must call psa_crypto_init() before the first file. * * This modules adds support for decoding / parsing PEM files. */ @@ -3236,7 +3503,9 @@ * * Uncomment to enable generic public key wrappers. */ +#ifdef CONFIG_MBEDTLS_PK_C #define MBEDTLS_PK_C +#endif /** * \def MBEDTLS_PK_PARSE_C @@ -3247,11 +3516,13 @@ * Caller: library/x509_crt.c * library/x509_csr.c * - * Requires: MBEDTLS_PK_C + * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_OID_C, MBEDTLS_PK_C * * Uncomment to enable generic public key parse functions. */ +#ifdef CONFIG_MBEDTLS_PK_PARSE_C #define MBEDTLS_PK_PARSE_C +#endif /** * \def MBEDTLS_PK_WRITE_C @@ -3261,7 +3532,7 @@ * Module: library/pkwrite.c * Caller: library/x509write.c * - * Requires: MBEDTLS_PK_C + * Requires: MBEDTLS_ASN1_WRITE_C, MBEDTLS_OID_C, MBEDTLS_PK_C * * Uncomment to enable generic public key write functions. */ @@ -3276,16 +3547,10 @@ * * Module: library/pkcs5.c * - * Requires: MBEDTLS_CIPHER_C and either MBEDTLS_MD_C or - * MBEDTLS_PSA_CRYPTO_C. - * - * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init() - * before doing any PKCS5 operation. + * Auto-enables: MBEDTLS_MD_C * - * \warning When building with MBEDTLS_MD_C, all hashes used with this - * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C, - * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by - * this module in builds where MBEDTLS_MD_C is disabled. + * \warning If using a hash that is only provided by PSA drivers, you must + * call psa_crypto_init() before doing any PKCS5 operations. * * This module adds support for the PKCS#5 functions. */ @@ -3320,16 +3585,11 @@ * Module: library/pkcs12.c * Caller: library/pkparse.c * - * Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_CIPHER_C and either - * MBEDTLS_MD_C or MBEDTLS_PSA_CRYPTO_C. - * - * \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init() - * before doing any PKCS12 operation. + * Requires: MBEDTLS_ASN1_PARSE_C and either MBEDTLS_MD_C or + * MBEDTLS_PSA_CRYPTO_C. * - * \warning When building with MBEDTLS_MD_C, all hashes used with this - * need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C, - * etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by - * this module in builds where MBEDTLS_MD_C is disabled. + * \warning If using a hash that is only provided by PSA drivers, you must + * call psa_crypto_init() before doing any PKCS12 operations. * * This module enables PKCS#12 functions. */ @@ -3378,11 +3638,12 @@ * * Module: library/psa_crypto.c * - * Requires: MBEDTLS_CIPHER_C, - * either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C, + * Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C, * or MBEDTLS_HMAC_DRBG_C and MBEDTLS_ENTROPY_C, * or MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG. - * + * Auto-enables: MBEDTLS_CIPHER_C if any unauthenticated (ie, non-AEAD) + * cipher is enabled in PSA (unless it's fully accelerated, see + * docs/driver-only-builds.md about that). */ #ifdef CONFIG_MBEDTLS_PSA_CRYPTO_C #define MBEDTLS_PSA_CRYPTO_C @@ -3394,8 +3655,11 @@ * Enable dynamic secure element support in the Platform Security * Architecture cryptography API. * - * \deprecated This feature is deprecated. Please switch to the driver - * interface enabled by #MBEDTLS_PSA_CRYPTO_DRIVERS. + * \deprecated This feature is deprecated. Please switch to the PSA driver + * interface. + * + * \warning This feature is not thread-safe, and should not be used in a + * multi-threaded environment. * * Module: library/psa_crypto_se.c * @@ -3465,7 +3729,9 @@ * * Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C */ +#ifdef CONFIG_MBEDTLS_RSA_C #define MBEDTLS_RSA_C +#endif /** * \def MBEDTLS_SHA1_C @@ -3484,7 +3750,9 @@ * avoiding dependencies on it, and considering stronger * message digests instead. */ +#ifdef CONFIG_MBEDTLS_SHA1_C #define MBEDTLS_SHA1_C +#endif /** * \def MBEDTLS_SHA224_C @@ -3497,7 +3765,9 @@ * * This module adds support for SHA-224. */ +#ifdef CONFIG_MBEDTLS_SHA224_C #define MBEDTLS_SHA224_C +#endif /** * \def MBEDTLS_SHA256_C @@ -3514,54 +3784,94 @@ * This module adds support for SHA-256. * This module is required for the SSL/TLS 1.2 PRF function. */ +#ifdef CONFIG_MBEDTLS_SHA256_C #define MBEDTLS_SHA256_C +#endif /** - * \def MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT + * \def MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT * * Enable acceleration of the SHA-256 and SHA-224 cryptographic hash - * algorithms - * with the ARMv8 cryptographic extensions if they are available at runtime. - * If not, the library will fall back to the C implementation. + * algorithms with the ARMv8 cryptographic extensions if they are available + * at runtime. If not, the library will fall back to the C implementation. * - * \note If MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT is defined when building - * for a non-Aarch64 build it will be silently ignored. + * \note If MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT is defined when + * building for a non-Armv8-A build it will be silently ignored. + * + * \note Minimum compiler versions for this feature are Clang 4.0, + * armclang 6.6 or GCC 6.0. + * + * \note \c CFLAGS must be set to a minimum of \c -march=armv8-a+crypto for + * armclang <= 6.9 * - * \warning MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the - * same time as MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY. + * \note This was previously known as + * MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT. That name is deprecated, but may + * still be used as an alternative form for this option. + * + * \warning MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT cannot be defined at + * the same time as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY. * * Requires: MBEDTLS_SHA256_C. * * Module: library/sha256.c * - * Uncomment to have the library check for the A64 SHA-256 crypto extensions - * and use them if available. + * Uncomment to have the library check for the Armv8-A SHA-256 crypto + * extensions and use them if available. + */ + +/* #define MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT */ + +/** + * \def MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT + * + * \deprecated This is now known as + * MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT. This name is now deprecated, + * but may still be used as an alternative form for this option. */ /* #define MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT */ /** - * \def MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY + * \def MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY * * Enable acceleration of the SHA-256 and SHA-224 cryptographic hash - * algorithms - * with the ARMv8 cryptographic extensions, which must be available at - * runtime or else an illegal instruction fault will occur. + * algorithms with the ARMv8 cryptographic extensions, which must be + * available at runtime or else an illegal instruction fault will occur. * * \note This allows builds with a smaller code size than with - * MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT + * MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT + * + * \note Minimum compiler versions for this feature are Clang 4.0, + * armclang 6.6 or GCC 6.0. + * + * \note \c CFLAGS must be set to a minimum of \c -march=armv8-a+crypto for + * armclang <= 6.9 * - * \warning MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY cannot be defined at the same - * time as MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT. + * \note This was previously known as MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY. + * That name is deprecated, but may still be used as an alternative form for + * this option. + * + * \warning MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY cannot be defined at the + * same time as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_IF_PRESENT. * * Requires: MBEDTLS_SHA256_C. * * Module: library/sha256.c * - * Uncomment to have the library use the A64 SHA-256 crypto extensions + * Uncomment to have the library use the Armv8-A SHA-256 crypto extensions * unconditionally. */ +/* #define MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY */ + +/** + * \def MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY + * + * \deprecated This is now known as MBEDTLS_SHA256_USE_ARMV8_A_CRYPTO_ONLY. + * This name is now deprecated, but may still be used as an alternative form + * for this option. + */ + /* #define MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY */ /** @@ -3599,19 +3909,34 @@ #define MBEDTLS_SHA512_C #endif +/** + * \def MBEDTLS_SHA3_C + * + * Enable the SHA3 cryptographic hash algorithm. + * + * Module: library/sha3.c + * + * This module adds support for SHA3. + */ +#ifdef CONFIG_MBEDTLS_SHA3_C +#define MBEDTLS_SHA3_C +#endif + /** * \def MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT * * Enable acceleration of the SHA-512 and SHA-384 cryptographic hash - *algorithms - * with the ARMv8 cryptographic extensions if they are available at runtime. - * If not, the library will fall back to the C implementation. + * algorithms with the ARMv8 cryptographic extensions if they are available + * at runtime. If not, the library will fall back to the C implementation. * * \note If MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT is defined when building * for a non-Aarch64 build it will be silently ignored. * - * \note The code uses the SHA-512 Neon intrinsics, so requires GCC >= 8 or - * Clang >= 7. + * \note Minimum compiler versions for this feature are Clang 7.0, + * armclang 6.9 or GCC 8.0. + * + * \note \c CFLAGS must be set to a minimum of \c -march=armv8.2-a+sha3 for + * armclang 6.9 * * \warning MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the * same time as MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY. @@ -3631,14 +3956,16 @@ * * Enable acceleration of the SHA-512 and SHA-384 cryptographic hash * algorithms with the ARMv8 cryptographic extensions, which must be - * available at runtime or else an illegal instruction fault will - * occur. + * available at runtime or else an illegal instruction fault will occur. * * \note This allows builds with a smaller code size than with * MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT * - * \note The code uses the SHA-512 Neon intrinsics, so requires GCC >= 8 or - * Clang >= 7. + * \note Minimum compiler versions for this feature are Clang 7.0, + * armclang 6.9 or GCC 8.0. + * + * \note \c CFLAGS must be set to a minimum of \c -march=armv8.2-a+sha3 for + * armclang 6.9 * * \warning MBEDTLS_SHA512_USE_A64_CRYPTO_ONLY cannot be defined at the same * time as MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT. @@ -3744,11 +4071,10 @@ * \def MBEDTLS_THREADING_C * * Enable the threading abstraction layer. - * By default mbed TLS assumes it is used in a non-threaded environment or - * that - * contexts are not shared between threads. If you do intend to use contexts - * between threads, you will need to enable this layer to prevent race - * conditions. See also our Knowledge Base article about threading: + * By default Mbed TLS assumes it is used in a non-threaded environment or + * that contexts are not shared between threads. If you do intend to use + * contexts between threads, you will need to enable this layer to prevent + * race conditions. See also our Knowledge Base article about threading: * https://mbed-tls.readthedocs.io/en/latest/kb/development/ \ * thread-safety-and-multi-threading * @@ -3760,7 +4086,7 @@ * You will have to enable either MBEDTLS_THREADING_ALT or * MBEDTLS_THREADING_PTHREAD. * - * Enable this layer to allow use of mutexes within mbed TLS + * Enable this layer to allow use of mutexes within Mbed TLS */ #ifdef CONFIG_MBEDTLS_THREADING_C #define MBEDTLS_THREADING_C @@ -3825,7 +4151,9 @@ * * This module is required for the X.509 parsing modules. */ +#ifdef CONFIG_MBEDTLS_X509_USE_C #define MBEDTLS_X509_USE_C +#endif /** * \def MBEDTLS_X509_CRT_PARSE_C @@ -3841,7 +4169,9 @@ * * This module is required for X.509 certificate parsing. */ +#ifdef CONFIG_MBEDTLS_X509_CRT_PARSE_C #define MBEDTLS_X509_CRT_PARSE_C +#endif /** * \def MBEDTLS_X509_CRL_PARSE_C @@ -3936,7 +4266,7 @@ #define MBEDTLS_XTEA_C #endif -/** \} name SECTION: mbed TLS modules */ +/** \} name SECTION: Mbed TLS modules */ /** * \name SECTION: General configuration options @@ -4163,7 +4493,7 @@ /*