From c2147ed33ac39164b91e9449c7e097956703124c Mon Sep 17 00:00:00 2001 From: Longhaox Lee Date: Thu, 13 Nov 2025 15:04:28 +0800 Subject: [PATCH 1/3] CryptoPkg: EDK2 code update for Mbedtls 3.6.5. 1. mbedtls_config.h header sync with 3.6.5 . 2. Implement mbedtls_ms_time() Get time in milliseconds. 3. Covert some CRT library to EDK Implement and CRT defined. 4. Added and remove file to sync. REF: https://github.com/tianocore/edk2/issues/11605 Signed-off-by: Longhaox Lee --- .../Pk/CryptPkcs7Internal.h | 1 + .../SysCall/ConstantTimeClock.c | 8 + .../SysCall/TimerWrapper.c | 42 + .../SysCall/UnitTestHostCrtWrapper.c | 8 + CryptoPkg/Library/Include/CrtLibSupport.h | 33 + CryptoPkg/Library/MbedTlsLib/EcSm2Null.c | 24 + .../Include/mbedtls/mbedtls_config.h | 1145 +++++++++++++---- CryptoPkg/Library/MbedTlsLib/MbedTlsLib.inf | 10 +- .../Library/MbedTlsLib/MbedTlsLibFull.inf | 11 +- 9 files changed, 998 insertions(+), 284 deletions(-) Index: edk2/CryptoPkg/Library/BaseCryptLibMbedTls/Pk/CryptPkcs7Internal.h =================================================================== --- edk2.orig/CryptoPkg/Library/BaseCryptLibMbedTls/Pk/CryptPkcs7Internal.h +++ edk2/CryptoPkg/Library/BaseCryptLibMbedTls/Pk/CryptPkcs7Internal.h @@ -18,6 +18,7 @@ SPDX-License-Identifier: BSD-2-Clause-Pa #include "mbedtls/asn1.h" #include "mbedtls/asn1write.h" #include "mbedtls/x509.h" +#include "x509_internal.h" #include "mbedtls/x509_crt.h" /// Index: edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/ConstantTimeClock.c =================================================================== --- edk2.orig/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/ConstantTimeClock.c +++ edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/ConstantTimeClock.c @@ -77,3 +77,11 @@ gettimeofday ( tv->tv_usec = 0; return 0; } + +ms_time_t +mbedtls_ms_time ( + void + ) +{ + return 0; +} Index: edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/TimerWrapper.c =================================================================== --- edk2.orig/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/TimerWrapper.c +++ edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/TimerWrapper.c @@ -191,3 +191,45 @@ gettimeofday ( tv->tv_usec = 0; return 0; } + +ms_time_t +mbedtls_ms_time ( + void + ) +{ + EFI_STATUS Status; + EFI_TIME Time; + ms_time_t CalTime; + UINTN Year; + + // + // Get the current time and date information + // + Status = gRT->GetTime (&Time, NULL); + if (EFI_ERROR (Status) || (Time.Year < 1970)) { + return 0; + } + + // + // Years Handling + // UTime should now be set to 00:00:00 on Jan 1 of the current year. + // + for (Year = 1970, CalTime = 0; Year != Time.Year; Year++) { + CalTime = CalTime + (time_t)(CumulativeDays[IsLeap (Year)][13] * SECSPERDAY); + } + + // + // Add in number of seconds for current Month, Day, Hour, Minute, Seconds, and TimeZone adjustment + // + CalTime = CalTime + + (time_t)((Time.TimeZone != EFI_UNSPECIFIED_TIMEZONE) ? (Time.TimeZone * 60) : 0) + + (time_t)(CumulativeDays[IsLeap (Time.Year)][Time.Month] * SECSPERDAY) + + (time_t)(((Time.Day > 0) ? Time.Day - 1 : 0) * SECSPERDAY) + + (time_t)(Time.Hour * SECSPERHOUR) + + (time_t)(Time.Minute * 60) + + (time_t)Time.Second; + + CalTime = CalTime*1000 + (ms_time_t)(Time.Nanosecond/1000000); + + return CalTime; +} Index: edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/UnitTestHostCrtWrapper.c =================================================================== --- edk2.orig/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/UnitTestHostCrtWrapper.c +++ edk2/CryptoPkg/Library/BaseCryptLibMbedTls/SysCall/UnitTestHostCrtWrapper.c @@ -61,3 +61,11 @@ getegid ( } int errno = 0; + +ms_time_t +mbedtls_ms_time ( + void + ) +{ + return 0; +} Index: edk2/CryptoPkg/Library/Include/CrtLibSupport.h =================================================================== --- edk2.orig/CryptoPkg/Library/Include/CrtLibSupport.h +++ edk2/CryptoPkg/Library/Include/CrtLibSupport.h @@ -102,6 +102,7 @@ typedef UINTN intptr_t; typedef INTN ptrdiff_t; typedef INTN ssize_t; typedef INT64 time_t; +typedef UINT64 ms_time_t; typedef UINT8 __uint8_t; typedef UINT8 sa_family_t; typedef UINT8 u_char; @@ -444,4 +445,36 @@ strcat ( #define offsetof(type, member) OFFSET_OF(type,member) #define atoi(nptr) AsciiStrDecimalToUintn(nptr) +#ifndef _BYTESWAP_DEFINED +#define _BYTESWAP_DEFINED +#define _byteswap_ushort SwapBytes16 +#define _byteswap_ulong SwapBytes32 +#define _byteswap_uint64 SwapBytes64 +#endif + +#ifndef SecureZeroMemory +#define SecureZeroMemory(ptr, sz) memset((ptr), 0, (sz)) +#endif + +#ifndef INT64_MAX +#define INT64_MAX 0x7FFFFFFFFFFFFFFFL +#define INT64_MIN (-0x7FFFFFFFFFFFFFFFL - 1) +#endif + +#ifndef INT16_MAX +#define INT16_MIN (-32768) +#define INT16_MAX (32767) +#define UINT16_MAX (65535) +#endif + +#ifndef UINT64_MAX +#define UINT64_MAX 0xFFFFFFFFFFFFFFFFUL +#endif + +#undef UINTPTR_MAX +#if (UINT_MAX > 0xFFFFFFFFUL) +#define UINTPTR_MAX 0xFFFFFFFFFFFFFFFFUL +#else +#define UINTPTR_MAX 0xFFFFFFFFUL +#endif #endif Index: edk2/CryptoPkg/Library/MbedTlsLib/EcSm2Null.c =================================================================== --- edk2.orig/CryptoPkg/Library/MbedTlsLib/EcSm2Null.c +++ edk2/CryptoPkg/Library/MbedTlsLib/EcSm2Null.c @@ -493,3 +493,27 @@ mbedtls_ecdsa_sign ( ASSERT (FALSE); return -1; } + +int +mbedtls_ecp_write_key_ext ( + const mbedtls_ecp_keypair *key, + size_t *olen, + unsigned char *buf, + size_t buflen + ) +{ + ASSERT (FALSE); + return -1; +} + +int +mbedtls_ecp_read_key ( + mbedtls_ecp_group_id grp_id, + mbedtls_ecp_keypair *key, + const unsigned char *buf, + size_t buflen + ) +{ + ASSERT (FALSE); + return -1; +} Index: edk2/CryptoPkg/Library/MbedTlsLib/Include/mbedtls/mbedtls_config.h =================================================================== --- edk2.orig/CryptoPkg/Library/MbedTlsLib/Include/mbedtls/mbedtls_config.h +++ edk2/CryptoPkg/Library/MbedTlsLib/Include/mbedtls/mbedtls_config.h @@ -30,11 +30,15 @@ * Requires support for asm() in compiler. * * Used in: + * library/aesni.h * library/aria.c * library/bn_mul.h + * library/constant_time.c + * library/padlock.h * * Required by: - * MBEDTLS_AESNI_C + * MBEDTLS_AESCE_C + * MBEDTLS_AESNI_C (on some platforms) * MBEDTLS_PADLOCK_C * * Comment to disable the use of assembly code. @@ -146,19 +150,51 @@ * * 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 now 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. @@ -187,10 +223,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. * @@ -216,6 +252,49 @@ // #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 @@ -247,7 +326,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. @@ -270,7 +349,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. @@ -278,7 +357,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. @@ -326,14 +405,14 @@ /** * \def MBEDTLS_SHA256_PROCESS_ALT * - * MBEDTLS__FUNCTION_NAME__ALT: Uncomment a macro to let mbed TLS use you + * 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 @@ -383,11 +462,11 @@ * * Expose a part of the internal interface of the Elliptic Curve Point module. * - * MBEDTLS_ECP__FUNCTION_NAME__ALT: Uncomment a macro to let mbed TLS use your + * MBEDTLS_ECP__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use your * alternative core implementation of elliptic curve arithmetic. Keep in mind * that function prototypes should remain the same. * - * This partially replaces one function. The header file from mbed TLS is still + * This partially replaces one function. The header file from Mbed TLS is still * used, in contrast to the MBEDTLS_ECP_ALT flag. The original implementation * is still present and it is used for group structures not supported by the * alternative. @@ -411,11 +490,11 @@ * implement optimized set up and tear down instructions. * * Example: In case you set MBEDTLS_ECP_INTERNAL_ALT and - * MBEDTLS_ECP_DOUBLE_JAC_ALT, mbed TLS will still provide the ecp_double_jac() + * MBEDTLS_ECP_DOUBLE_JAC_ALT, Mbed TLS will still provide the ecp_double_jac() * function, but will use your mbedtls_internal_ecp_double_jac() if the group * for the operation is supported by your implementation (i.e. your * mbedtls_internal_ecp_grp_capable() function returns 1 for this group). If the - * group is not supported by your implementation, then the original mbed TLS + * group is not supported by your implementation, then the original Mbed TLS * 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 MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE). @@ -446,7 +525,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 @@ -495,11 +574,41 @@ * depends on the system and memory details. * * This option is independent of \c MBEDTLS_AES_ROM_TABLES. - * */ // #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 + +/* + * 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 * * Use less ROM for the Camellia implementation (saves about 768 bytes). @@ -617,11 +726,24 @@ /** \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 * * MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve @@ -672,15 +794,54 @@ * This is useful in non-threaded environments if you want to avoid blocking * for too long on ECC (and, hence, X.509 or SSL/TLS) operations. * - * Uncomment this macro to enable restartable ECC computations. + * This option: + * - Adds xxx_restartable() variants of existing operations in the + * following modules, with corresponding restart context types: + * - ECP (for Short Weierstrass curves only): scalar multiplication (mul), + * linear combination (muladd); + * - ECDSA: signature generation & verification; + * - PK: signature generation & verification; + * - X509: certificate chain verification. + * - Adds mbedtls_ecdh_enable_restart() in the ECDH module. + * - Changes the behaviour of TLS 1.2 clients (not servers) when using the + * ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC + * computations restartable: + * - ECDH operations from the key exchange, only for Short Weierstrass + * curves, only when MBEDTLS_USE_PSA_CRYPTO is not enabled. + * - verification of the server's key exchange signature; + * - verification of the server's certificate chain; + * - generation of the client's signature if client authentication is used, + * with an ECC key/certificate. + * + * \note In the cases above, the usual SSL/TLS functions, such as + * mbedtls_ssl_handshake(), can now return + * MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS. + * + * \note When this option and MBEDTLS_USE_PSA_CRYPTO are both enabled, + * restartable operations in PK, X.509 and TLS (see above) are not + * using PSA. On the other hand, ECDH computations in TLS are using + * PSA, and are not restartable. These are temporary limitations that + * should be lifted in the future. * * \note This option only works with the default software implementation of * elliptic curve functionality. It is incompatible with * MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT. + * + * Requires: MBEDTLS_ECP_C + * + * Uncomment this macro to enable restartable ECC computations. */ #define MBEDTLS_ECP_RESTARTABLE /** + * 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 * * Enable deterministic ECDSA (RFC 6979). @@ -748,7 +909,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): @@ -846,7 +1007,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 @@ -869,7 +1032,9 @@ * * 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): @@ -891,7 +1056,9 @@ * * 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): @@ -913,7 +1080,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): @@ -939,10 +1108,14 @@ * 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 @@ -964,6 +1137,19 @@ // #define MBEDTLS_PK_PARSE_EC_EXTENDED /** + * \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. + */ +#define MBEDTLS_PK_PARSE_EC_COMPRESSED + +/** * \def MBEDTLS_ERROR_STRERROR_DUMMY * * Enable a dummy error function to make use of mbedtls_strerror() in @@ -1123,15 +1309,10 @@ * * 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. */ @@ -1169,18 +1350,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 @@ -1227,6 +1396,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 * @@ -1234,6 +1410,64 @@ // #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 + */ +#define MBEDTLS_PSA_KEY_STORE_DYNAMIC + +/** + * 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 * * Enable support for entropy injection at first boot. This feature is @@ -1247,6 +1481,26 @@ // #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. + */ +// #define MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS + +/** * \def MBEDTLS_RSA_NO_CRT * * Do not use the Chinese Remainder Theorem @@ -1358,9 +1612,50 @@ * module to perform private key operations instead of performing the * operation inside the library. * + * Requires: MBEDTLS_X509_CRT_PARSE_C */ // #define MBEDTLS_SSL_ASYNC_PRIVATE +/** \def MBEDTLS_SSL_CLI_ALLOW_WEAK_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME + * + * In TLS clients, when a client authenticates a server through its + * certificate, the client normally checks three things: + * - the certificate chain must be valid; + * - the chain must start from a trusted CA; + * - the certificate must cover the server name that is expected by the client. + * + * Omitting any of these checks is generally insecure, and can allow a + * malicious server to impersonate a legitimate server. + * + * The third check may be safely skipped in some unusual scenarios, + * such as networks where eavesdropping is a risk but not active attacks, + * or a private PKI where the client equally trusts all servers that are + * accredited by the root CA. + * + * You should call mbedtls_ssl_set_hostname() with the expected server name + * before starting a TLS handshake on a client (unless the client is + * set up to only use PSK-based authentication, which does not rely on the + * host name). This configuration option controls what happens if a TLS client + * is configured with the authentication mode #MBEDTLS_SSL_VERIFY_REQUIRED + * (default), certificate authentication is enabled and the client does not + * call mbedtls_ssl_set_hostname(): + * + * - If this option is unset (default), the connection attempt is aborted + * with the error #MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME. + * - If this option is set, the TLS library does not check the server name + * that the certificate is valid for. This is the historical behavior + * of Mbed TLS, but may be insecure as explained above. + * + * Enable this option for strict backward compatibility if you have + * determined that it is secure in the scenario where you are using + * Mbed TLS. + * + * \deprecated This option exists only for backward compatibility and will + * be removed in the next major version of Mbed TLS. + * + */ +// #define MBEDTLS_SSL_CLI_ALLOW_WEAK_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME + /** * \def MBEDTLS_SSL_CONTEXT_SERIALIZATION * @@ -1463,6 +1758,20 @@ #define MBEDTLS_SSL_KEEP_PEER_CERTIFICATE /** + * \def MBEDTLS_SSL_KEYING_MATERIAL_EXPORT + * + * When this option is enabled, the client and server can extract additional + * shared symmetric keys after an SSL handshake using the function + * mbedtls_ssl_export_keying_material(). + * + * The process for deriving the keys is specified in RFC 5705 for TLS 1.2 and + * in RFC 8446, Section 7.5, for TLS 1.3. + * + * Comment this macro to disable mbedtls_ssl_export_keying_material(). + */ +#define MBEDTLS_SSL_KEYING_MATERIAL_EXPORT + +/** * \def MBEDTLS_SSL_RENEGOTIATION * * Enable support for TLS renegotiation. @@ -1473,6 +1782,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 @@ -1494,18 +1805,30 @@ #define MBEDTLS_SSL_MAX_FRAGMENT_LENGTH /** + * \def MBEDTLS_SSL_RECORD_SIZE_LIMIT + * + * Enable support for RFC 8449 record_size_limit extension in SSL (TLS 1.3 only). + * + * Requires: MBEDTLS_SSL_PROTO_TLS1_3 + * + * Uncomment this macro to enable support for the record_size_limit extension + */ +// #define MBEDTLS_SSL_RECORD_SIZE_LIMIT + +/** * \def MBEDTLS_SSL_PROTO_TLS1_2 * * 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 */ @@ -1516,19 +1839,26 @@ * * 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: even though TLS 1.3 depends on PSA Crypto, and uses it unconditionally - * for most operations, if you want it to only use PSA for all crypto - * operations, you need to also enable MBEDTLS_USE_PSA_CRYPTO; otherwise X.509 - * operations, and functions that are common with TLS 1.2 (record protection, - * running handshake hash) will still use non-PSA crypto. + * \note TLS 1.3 uses PSA crypto for cryptographic operations that are + * 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, + * running handshake hash) only use PSA crypto if + * #MBEDTLS_USE_PSA_CRYPTO is enabled. + * + * \note In multithreaded applications, you must also enable + * #MBEDTLS_THREADING_C, even if individual TLS contexts are not + * shared between threads, unless only one thread ever calls + * TLS functions. * * Uncomment this macro to enable the support for TLS 1.3. */ @@ -1573,8 +1903,11 @@ * * 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 @@ -1588,7 +1921,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 @@ -1598,80 +1931,24 @@ #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED /** - * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE + * \def MBEDTLS_SSL_EARLY_DATA * - * Maximum time difference in milliseconds tolerated between the age of a - * ticket from the server and client point of view. - * From the client point of view, the age of a ticket is the time difference - * between the time when the client proposes to the server to use the ticket - * (time of writing of the Pre-Shared Key Extension including the ticket) and - * the time the client received the ticket from the server. - * From the server point of view, the age of a ticket is the time difference - * between the time when the server receives a proposition from the client - * to use the ticket and the time when the ticket was created by the server. - * The server age is expected to be always greater than the client one and - * MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE defines the - * maximum difference tolerated for the server to accept the ticket. - * This is not used in TLS 1.2. - * - */ -#define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000 - -/** - * \def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH + * Enable support for RFC 8446 TLS 1.3 early data. * - * Size in bytes of a ticket nonce. This is not used in TLS 1.2. + * Requires: MBEDTLS_SSL_SESSION_TICKETS and either + * MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED or + * MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED * - * This must be less than 256. - */ -#define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32 - -/** - * \def MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS + * 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. * - * Default number of NewSessionTicket messages to be sent by a TLS 1.3 server - * after handshake completion. This is not used in TLS 1.2 and relevant only if - * the MBEDTLS_SSL_SESSION_TICKETS option is enabled. + * \note The maximum amount of early data can be set with + * MBEDTLS_SSL_MAX_EARLY_DATA_SIZE. * */ -#define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1 - -/** -* \def MBEDTLS_SSL_EARLY_DATA -* -* Enable support for RFC 8446 TLS 1.3 early data. -* -* Requires: MBEDTLS_SSL_SESSION_TICKETS and either -* 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. -* -* This feature is experimental, not completed and thus not ready for -* production. -* -*/ // #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. - * - */ -#define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE 1024 - -/** * \def MBEDTLS_SSL_PROTO_DTLS * * Enable support for DTLS (all available versions). @@ -1889,22 +2166,32 @@ /** * \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. - * * \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. + * + * \warning In multithreaded applications, you must also enable + * #MBEDTLS_THREADING_C, unless only one thread ever calls PSA functions + * (`psa_xxx()`), including indirect calls through SSL/TLS, X.509 or PK. + * + * \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. - * Conflicts with: MBEDTLS_ECP_RESTARTABLE * * Uncomment this to enable internal use of PSA Crypto and new associated APIs. */ @@ -1930,8 +2217,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 @@ -1963,6 +2257,8 @@ * See the documentation of `mbedtls_x509_crt_verify_with_ca_cb()` and * `mbedtls_ssl_conf_ca_cb()` for more information. * + * Requires: MBEDTLS_X509_CRT_PARSE_C + * * Uncomment to enable trusted certificate callbacks. */ // #define MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK @@ -1984,33 +2280,80 @@ * 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. */ #define MBEDTLS_X509_RSASSA_PSS_SUPPORT -/** \} 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 * \{ */ /** * \def MBEDTLS_AESNI_C * - * Enable AES-NI support on x86-64. + * Enable AES-NI support on x86-64 or x86-32. + * + * \note AESNI is only supported with certain compilers and target options: + * - Visual Studio: supported + * - GCC, x86-64, target not explicitly supporting AESNI: + * requires MBEDTLS_HAVE_ASM. + * - GCC, x86-32, target not explicitly supporting AESNI: + * not supported. + * - GCC, x86-64 or x86-32, target supporting AESNI: supported. + * For this assembly-less implementation, you must currently compile + * `library/aesni.c` and `library/aes.c` with machine options to enable + * SSE2 and AESNI instructions: `gcc -msse2 -maes -mpclmul` or + * `clang -maes -mpclmul`. + * - Non-x86 targets: this option is silently ignored. + * - Other compilers: this option is silently ignored. + * + * \note + * Above, "GCC" includes compatible compilers such as Clang. + * The limitations on target support are likely to be relaxed in the future. * * Module: library/aesni.c * Caller: library/aes.c * - * Requires: MBEDTLS_HAVE_ASM + * Requires: MBEDTLS_HAVE_ASM (on some platforms, see note) * - * This modules adds support for the AES-NI instructions on x86-64 + * This modules adds support for the AES-NI instructions on x86. */ + // #define MBEDTLS_AESNI_C /** + * \def MBEDTLS_AESCE_C + * + * Enable AES cryptographic extension support on Armv8. + * + * Module: library/aesce.c + * Caller: library/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 Armv8 systems. + */ +#define MBEDTLS_AESCE_C + +/** * \def MBEDTLS_AES_C * * Enable the AES block cipher. @@ -2126,6 +2469,28 @@ #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 * * Enable the multi-precision integer library. @@ -2304,6 +2669,8 @@ * 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. */ @@ -2334,6 +2701,15 @@ * 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. @@ -2341,7 +2717,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. */ @@ -2373,7 +2751,7 @@ * * PEM_PARSE uses DES/3DES for decrypting encrypted keys. * - * \warning DES is considered a weak cipher and its use constitutes a + * \warning DES/3DES are considered weak ciphers and their use constitutes a * security risk. We recommend considering stronger ciphers instead. */ // #define MBEDTLS_DES_C @@ -2452,13 +2830,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. */ // #define MBEDTLS_ECJPAKE_C @@ -2518,6 +2891,22 @@ #define MBEDTLS_GCM_C /** + * \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 * * Enable the HKDF algorithm (RFC 5869). @@ -2588,11 +2977,12 @@ /** * \def MBEDTLS_MD_C * - * Enable the generic message digest layer. + * Enable the generic layer for message digest (hashing) and HMAC. * * 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 @@ -2723,6 +3113,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. */ @@ -2771,7 +3165,7 @@ * 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. */ @@ -2785,7 +3179,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. */ @@ -2798,15 +3192,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. */ @@ -2815,11 +3204,7 @@ /** * \def MBEDTLS_PKCS7_C * - * This feature is a work in progress and not ready for production. Testing and - * validation is incomplete, and handling of malformed inputs may not be robust. - * The API may change. - * - * Enable PKCS7 core for using PKCS7 formatted signatures. + * Enable PKCS #7 core for using PKCS #7-formatted signatures. * RFC Link - https://tools.ietf.org/html/rfc2315 * * Module: library/pkcs7.c @@ -2828,7 +3213,7 @@ * MBEDTLS_X509_CRT_PARSE_C MBEDTLS_X509_CRL_PARSE_C, * MBEDTLS_BIGNUM_C, MBEDTLS_MD_C * - * This module is required for the PKCS7 parsing modules. + * This module is required for the PKCS #7 parsing modules. */ #define MBEDTLS_PKCS7_C @@ -2841,20 +3226,15 @@ * 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. */ -// #define MBEDTLS_PKCS12_C +#define MBEDTLS_PKCS12_C /** * \def MBEDTLS_PLATFORM_C @@ -2889,15 +3269,27 @@ /** * \def MBEDTLS_PSA_CRYPTO_C * - * Enable the Platform Security Architecture cryptography API. + * Enable the Platform Security Architecture (PSA) cryptography API. + * + * \note In multithreaded applications, you must enable #MBEDTLS_THREADING_C, + * unless only one thread ever calls `psa_xxx()` functions. + * That includes indirect calls, such as: + * - performing a TLS handshake if support for TLS 1.3 is enabled; + * - using a TLS 1.3 connection; + * - indirect calls from PK, X.509 or SSL functions when + * #MBEDTLS_USE_PSA_CRYPTO is enabled; + * - indirect calls to calculate a hash when #MBEDTLS_MD_C is disabled; + * - any other call to a function that requires calling psa_crypto_init() + * beforehand. * * 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). */ // #define MBEDTLS_PSA_CRYPTO_C @@ -2907,8 +3299,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 * @@ -2943,6 +3338,26 @@ // #define MBEDTLS_PSA_ITS_FILE_C /** + * \def MBEDTLS_PSA_STATIC_KEY_SLOTS + * + * Statically preallocate memory to store keys' material in PSA instead + * of allocating it dynamically when required. This allows builds without a + * heap, if none of the enabled cryptographic implementations or other features + * require it. + * This feature affects both volatile and persistent keys which means that + * it's not possible to persistently store a key which is larger than + * #MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE. + * + * \note This feature comes with a (potentially) higher RAM usage since: + * - All the key slots are allocated no matter if they are used or not. + * - Each key buffer's length is #MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE bytes. + * + * Requires: MBEDTLS_PSA_CRYPTO_C + * + */ +// #define MBEDTLS_PSA_STATIC_KEY_SLOTS + +/** * \def MBEDTLS_RIPEMD160_C * * Enable the RIPEMD-160 hash algorithm. @@ -2997,9 +3412,6 @@ * * Enable the SHA-224 cryptographic hash algorithm. * - * Requires: MBEDTLS_SHA256_C. The library does not currently support enabling - * SHA-224 without SHA-256. - * * Module: library/sha256.c * Caller: library/md.c * library/ssl_cookie.c @@ -3013,9 +3425,6 @@ * * Enable the SHA-256 cryptographic hash algorithm. * - * Requires: MBEDTLS_SHA224_C. The library does not currently support enabling - * SHA-256 without SHA-224. - * * Module: library/sha256.c * Caller: library/entropy.c * library/md.c @@ -3029,53 +3438,85 @@ #define MBEDTLS_SHA256_C /** - * \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. * - * \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 The code uses Neon intrinsics, so \c CFLAGS must be set to a minimum - * of \c -march=armv8-a+crypto. + * \note Minimum compiler versions for this feature are Clang 4.0, + * armclang 6.6 or GCC 6.0. * - * \warning MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT cannot be defined at the - * same time as MBEDTLS_SHA256_USE_A64_CRYPTO_ONLY. + * \note \c CFLAGS must be set to a minimum of \c -march=armv8-a+crypto for + * armclang <= 6.9 + * + * \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 + * 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. * * \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 * - * \note The code uses Neon intrinsics, so \c CFLAGS must be set to a minimum - * of \c -march=armv8-a+crypto. + * \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_A64_CRYPTO_ONLY cannot be defined at the same - * time as MBEDTLS_SHA256_USE_A64_CRYPTO_IF_PRESENT. + * \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 /** @@ -3083,8 +3524,6 @@ * * Enable the SHA-384 cryptographic hash algorithm. * - * Requires: MBEDTLS_SHA512_C - * * Module: library/sha512.c * Caller: library/md.c * library/psa_crypto_hash.c @@ -3112,6 +3551,17 @@ #define MBEDTLS_SHA512_C /** + * \def MBEDTLS_SHA3_C + * + * Enable the SHA3 cryptographic hash algorithm. + * + * Module: library/sha3.c + * + * This module adds support for SHA3. + */ +#define MBEDTLS_SHA3_C + +/** * \def MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT * * Enable acceleration of the SHA-512 and SHA-384 cryptographic hash algorithms @@ -3121,10 +3571,11 @@ * \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, and \c CFLAGS must be set to a minimum of - * \c -march=armv8.2-a+sha3. An optimisation level of \c -O3 generates the - * fastest code. + * \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. @@ -3148,10 +3599,11 @@ * \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, and \c CFLAGS must be set to a minimum of - * \c -march=armv8.2-a+sha3. An optimisation level of \c -O3 generates the - * fastest code. + * \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. @@ -3248,10 +3700,38 @@ * \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 + * + * Traditionally, 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: + * conditions. + * + * The PSA subsystem has an implicit shared context. Therefore, you must + * enable this option if more than one thread may use any part of + * Mbed TLS that is implemented on top of the PSA subsystem. + * + * You must enable this option in multithreaded applications where more than + * one thread performs any of the following operations: + * + * - Any call to a PSA function (`psa_xxx()`). + * - Any call to a TLS, X.509 or PK function (`mbedtls_ssl_xxx()`, + * `mbedtls_x509_xxx()`, `mbedtls_pkcs7_xxx()`, `mbedtls_pk_xxx()`) + * if `MBEDTLS_USE_PSA_CRYPTO` is enabled (regardless of whether individual + * TLS, X.509 or PK contexts are shared between threads). + * - A TLS 1.3 connection, regardless of the compile-time configuration. + * - Any library feature that calculates a hash, if `MBEDTLS_MD_C` is disabled. + * As an exception, algorithm-specific low-level modules do not require + * threading protection unless the contexts are shared between threads. + * - Any library feature that performs symmetric encryption or decryption, + * if `MBEDTLS_CIPHER_C` is disabled. + * As an exception, algorithm-specific low-level modules do not require + * threading protection unless the contexts are shared between threads. + * - Any use of a cryptographic context if the same context is used in + * multiple threads. + * - Any call to a function where the documentation specifies that + * psa_crypto_init() must be called prior to that function. + * + * See also our Knowledge Base article about threading: * https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading * * Module: library/threading.c @@ -3408,7 +3888,7 @@ */ #define MBEDTLS_X509_CSR_WRITE_C -/** \} name SECTION: mbed TLS modules */ +/** \} name SECTION: Mbed TLS modules */ /** * \name SECTION: General configuration options @@ -3490,6 +3970,53 @@ */ // #define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null" +/** + * \def MBEDTLS_PSA_CRYPTO_PLATFORM_FILE + * + * If defined, this is a header which will be included instead of + * `"psa/crypto_platform.h"`. This file should declare the same identifiers + * as the one in Mbed TLS, but with definitions adapted to the platform on + * which the library code will run. + * + * \note The required content of this header can vary from one version of + * Mbed TLS to the next. Integrators who provide an alternative file + * should review the changes in the original file whenever they + * upgrade Mbed TLS. + * + * This macro is expanded after an \#include directive. This is a popular but + * non-standard feature of the C language, so this feature is only available + * with compilers that perform macro expansion on an \#include line. + * + * The value of this symbol is typically a path in double quotes, either + * absolute or relative to a directory on the include search path. + */ +// #define MBEDTLS_PSA_CRYPTO_PLATFORM_FILE "psa/crypto_platform_alt.h" + +/** + * \def MBEDTLS_PSA_CRYPTO_STRUCT_FILE + * + * If defined, this is a header which will be included instead of + * `"psa/crypto_struct.h"`. This file should declare the same identifiers + * as the one in Mbed TLS, but with definitions adapted to the environment + * in which the library code will run. The typical use for this feature + * is to provide alternative type definitions on the client side in + * client-server integrations of PSA crypto, where operation structures + * contain handles instead of cryptographic data. + * + * \note The required content of this header can vary from one version of + * Mbed TLS to the next. Integrators who provide an alternative file + * should review the changes in the original file whenever they + * upgrade Mbed TLS. + * + * This macro is expanded after an \#include directive. This is a popular but + * non-standard feature of the C language, so this feature is only available + * with compilers that perform macro expansion on an \#include line. + * + * The value of this symbol is typically a path in double quotes, either + * absolute or relative to a directory on the include search path. + */ +// #define MBEDTLS_PSA_CRYPTO_STRUCT_FILE "psa/crypto_struct_alt.h" + /** \} name SECTION: General configuration options */ /** @@ -3542,8 +4069,29 @@ /* Platform options */ // #define MBEDTLS_PLATFORM_STD_MEM_HDR /**< Header to include if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS is defined. Don't define if no header is needed. */ -// #define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< Default allocator to use, can be undefined */ -// #define MBEDTLS_PLATFORM_STD_FREE free /**< Default free to use, can be undefined */ + +/** \def MBEDTLS_PLATFORM_STD_CALLOC + * + * Default allocator to use, can be undefined. + * It must initialize the allocated buffer memory to zeroes. + * The size of the buffer is the product of the two parameters. + * The calloc function returns either a null pointer or a pointer to the allocated space. + * If the product is 0, the function may either return NULL or a valid pointer to an array of size 0 which is a valid input to the deallocation function. + * An uninitialized #MBEDTLS_PLATFORM_STD_CALLOC always fails, returning a null pointer. + * See the description of #MBEDTLS_PLATFORM_MEMORY for more details. + * The corresponding deallocation function is #MBEDTLS_PLATFORM_STD_FREE. + */ +// #define MBEDTLS_PLATFORM_STD_CALLOC calloc + +/** \def MBEDTLS_PLATFORM_STD_FREE + * + * Default free to use, can be undefined. + * NULL is a valid parameter, and the function must do nothing. + * A non-null parameter will always be a pointer previously returned by #MBEDTLS_PLATFORM_STD_CALLOC and not yet freed. + * An uninitialized #MBEDTLS_PLATFORM_STD_FREE does not do anything. + * See the description of #MBEDTLS_PLATFORM_MEMORY for more details (same principles as for MBEDTLS_PLATFORM_STD_CALLOC apply). + */ +// #define MBEDTLS_PLATFORM_STD_FREE free // #define MBEDTLS_PLATFORM_STD_SETBUF setbuf /**< Default setbuf to use, can be undefined */ // #define MBEDTLS_PLATFORM_STD_EXIT exit /**< Default exit to use, can be undefined */ // #define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */ @@ -3557,10 +4105,10 @@ // #define MBEDTLS_PLATFORM_STD_NV_SEED_WRITE mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */ // #define MBEDTLS_PLATFORM_STD_NV_SEED_FILE "seedfile" /**< Seed file to read/write with default implementation */ -/* To Use Function Macros MBEDTLS_PLATFORM_C must be enabled */ +/* To use the following function macros, MBEDTLS_PLATFORM_C must be enabled. */ /* MBEDTLS_PLATFORM_XXX_MACRO and MBEDTLS_PLATFORM_XXX_ALT cannot both be defined */ -// #define MBEDTLS_PLATFORM_CALLOC_MACRO calloc /**< Default allocator macro to use, can be undefined */ -// #define MBEDTLS_PLATFORM_FREE_MACRO free /**< Default free macro to use, can be undefined */ +// #define MBEDTLS_PLATFORM_CALLOC_MACRO calloc /**< Default allocator macro to use, can be undefined. See MBEDTLS_PLATFORM_STD_CALLOC for requirements. */ +// #define MBEDTLS_PLATFORM_FREE_MACRO free /**< Default free macro to use, can be undefined. See MBEDTLS_PLATFORM_STD_FREE for requirements. */ // #define MBEDTLS_PLATFORM_EXIT_MACRO exit /**< Default exit macro to use, can be undefined */ // #define MBEDTLS_PLATFORM_SETBUF_MACRO setbuf /**< Default setbuf macro to use, can be undefined */ // #define MBEDTLS_PLATFORM_TIME_MACRO time /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */ @@ -3572,6 +4120,8 @@ // #define MBEDTLS_PLATFORM_VSNPRINTF_MACRO vsnprintf /**< Default vsnprintf macro to use, can be undefined */ // #define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO mbedtls_platform_std_nv_seed_read /**< Default nv_seed_read function to use, can be undefined */ // #define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */ +#define MBEDTLS_PLATFORM_MS_TIME_TYPE_MACRO ms_time_t // #define MBEDTLS_PLATFORM_MS_TIME_TYPE_MACRO int64_t /**< Default milliseconds time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled. It must be signed, and at least 64 bits. If it is changed from the default, MBEDTLS_PRINTF_MS_TIME must be updated to match.*/ +// #define MBEDTLS_PRINTF_MS_TIME PRId64 /**< Default fmt for printf. That's avoid compiler warning if mbedtls_ms_time_t is redefined */ extern int my_printf ( @@ -3636,25 +4186,57 @@ mbedtls_free ( * Use HMAC_DRBG with the specified hash algorithm for HMAC_DRBG for the * PSA crypto subsystem. * - * If this option is unset: - * - If CTR_DRBG is available, the PSA subsystem uses it rather than HMAC_DRBG. - * - Otherwise, the PSA subsystem uses HMAC_DRBG with either - * #MBEDTLS_MD_SHA512 or #MBEDTLS_MD_SHA256 based on availability and - * on unspecified heuristics. + * If this option is unset, the library chooses a hash (currently between + * #MBEDTLS_MD_SHA512 and #MBEDTLS_MD_SHA256) based on availability and + * unspecified heuristics. + * + * \note The PSA crypto subsystem uses the first available mechanism amongst + * the following: + * - #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG if enabled; + * - Entropy from #MBEDTLS_ENTROPY_C plus CTR_DRBG with AES + * if #MBEDTLS_CTR_DRBG_C is enabled; + * - Entropy from #MBEDTLS_ENTROPY_C plus HMAC_DRBG. + * + * A future version may reevaluate the prioritization of DRBG mechanisms. */ // #define MBEDTLS_PSA_HMAC_DRBG_MD_TYPE MBEDTLS_MD_SHA256 /** \def MBEDTLS_PSA_KEY_SLOT_COUNT - * Restrict the PSA library to supporting a maximum amount of simultaneously - * loaded keys. A loaded key is a key stored by the PSA Crypto core as a - * volatile key, or a persistent key which is loaded temporarily by the - * library as part of a crypto operation in flight. * - * If this option is unset, the library will fall back to a default value of - * 32 keys. + * When #MBEDTLS_PSA_KEY_STORE_DYNAMIC is disabled, + * the maximum amount of PSA keys simultaneously in memory. This counts all + * volatile keys, plus loaded persistent keys. + * + * When #MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled, + * the maximum number of loaded persistent keys. + * + * Currently, persistent keys do not need to be loaded all the time while + * a multipart operation is in progress, only while the operation is being + * set up. This may change in future versions of the library. + * + * Currently, the library traverses of the whole table on each access to a + * persistent key. Therefore large values may cause poor performance. + * + * This option has no effect when #MBEDTLS_PSA_CRYPTO_C is disabled. */ // #define MBEDTLS_PSA_KEY_SLOT_COUNT 32 +/** + * \def MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE + * + * Define the size (in bytes) of each static key buffer when + * #MBEDTLS_PSA_STATIC_KEY_SLOTS is set. If not + * explicitly defined then it's automatically guessed from available PSA keys + * enabled in the build through PSA_WANT_xxx symbols. + * If required by the application this parameter can be set to higher values + * in order to store larger objects (ex: raw keys), but please note that this + * will increase RAM usage. + */ +// #define MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE 256 + +/* RSA OPTIONS */ +// #define MBEDTLS_RSA_GEN_KEY_MIN_BITS 1024 /**< Minimum RSA key size that can be generated in bits (Minimum possible value is 128 bits) */ + /* SSL Cache options */ // #define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT 86400 /**< 1 day */ // #define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES 50 /**< Maximum entries in cache */ @@ -3749,7 +4331,7 @@ mbedtls_free ( */ // #define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768 -// #define MBEDTLS_PSK_MAX_LEN 32 /**< Max size of TLS pre-shared keys, in bytes (default 256 bits) */ +// #define MBEDTLS_PSK_MAX_LEN 32 /**< Max size of TLS pre-shared keys, in bytes (default 256 or 384 bits) */ // #define MBEDTLS_SSL_COOKIE_TIMEOUT 60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */ /** @@ -3766,57 +4348,64 @@ mbedtls_free ( */ // #define MBEDTLS_SSL_CIPHERSUITES MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 -/* X509 options */ -// #define MBEDTLS_X509_MAX_INTERMEDIATE_CA 8 /**< Maximum number of intermediate CAs in a verification chain. */ -// #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 /**< Maximum length of a path/filename string in bytes including the null terminator character ('\0'). */ +/** + * \def MBEDTLS_SSL_MAX_EARLY_DATA_SIZE + * + * The default maximum amount of 0-RTT data. See the documentation of + * \c mbedtls_ssl_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. + */ +// #define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE 1024 /** - * Uncomment the macro to let mbed TLS use your alternate implementation of - * mbedtls_platform_zeroize(). This replaces the default implementation in - * platform_util.c. + * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE * - * mbedtls_platform_zeroize() is a widely used function across the library to - * zero a block of memory. The implementation is expected to be secure in the - * sense that it has been written to prevent the compiler from removing calls - * to mbedtls_platform_zeroize() as part of redundant code elimination - * optimizations. However, it is difficult to guarantee that calls to - * mbedtls_platform_zeroize() will not be optimized by the compiler as older - * versions of the C language standards do not provide a secure implementation - * of memset(). Therefore, MBEDTLS_PLATFORM_ZEROIZE_ALT enables users to - * configure their own implementation of mbedtls_platform_zeroize(), for - * example by using directives specific to their compiler, features from newer - * C standards (e.g using memset_s() in C11) or calling a secure memset() from - * their system (e.g explicit_bzero() in BSD). + * Maximum allowed ticket age difference in milliseconds tolerated between + * server and client. Default value is 6000. This is not used in TLS 1.2. + * + * - The client ticket age is the time difference between the time when the + * client proposes to the server to use the ticket and the time the client + * received the ticket from the server. + * - The server ticket age is the time difference between the time when the + * server receives a proposition from the client to use the ticket and the + * time when the ticket was created by the server. + * + * The ages might be different due to the client and server clocks not running + * at the same pace. The typical accuracy of an RTC crystal is ±100 to ±20 parts + * per million (360 to 72 milliseconds per hour). Default tolerance window is + * 6s, thus in the worst case clients and servers must sync up their system time + * every 6000/360/2~=8 hours. + * + * See section 8.3 of the TLS 1.3 specification(RFC 8446) for more information. */ -// #define MBEDTLS_PLATFORM_ZEROIZE_ALT +// #define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000 /** - * 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. + * \def MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH * - * 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. + * Size in bytes of a ticket nonce. This is not used in TLS 1.2. + * + * This must be less than 256. */ -// #define MBEDTLS_PLATFORM_GMTIME_R_ALT +// #define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32 /** - * 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. + * \def MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS + * + * Default number of NewSessionTicket messages to be sent by a TLS 1.3 server + * after handshake completion. This is not used in TLS 1.2 and relevant only if + * the MBEDTLS_SSL_SESSION_TICKETS option is enabled. + * */ -// #define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED +// #define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1 + +/* X509 options */ +// #define MBEDTLS_X509_MAX_INTERMEDIATE_CA 8 /**< Maximum number of intermediate CAs in a verification chain. */ +// #define MBEDTLS_X509_MAX_FILE_PATH_LEN 512 /**< Maximum length of a path/filename string in bytes including the null terminator character ('\0'). */ /** \} name SECTION: Module configuration options */ Index: edk2/CryptoPkg/Library/MbedTlsLib/MbedTlsLib.inf =================================================================== --- edk2.orig/CryptoPkg/Library/MbedTlsLib/MbedTlsLib.inf +++ edk2/CryptoPkg/Library/MbedTlsLib/MbedTlsLib.inf @@ -50,7 +50,8 @@ mbedtls/library/ssl_client.c mbedtls/library/ssl_debug_helpers_generated.c mbedtls/library/rsa_alt_helpers.c - mbedtls/library/hash_info.c + mbedtls/library/pk_ecc.c + mbedtls/library/x509write.c mbedtls/library/bignum_core.c mbedtls/library/constant_time.c mbedtls/library/memory_buffer_alloc.c @@ -68,6 +69,7 @@ mbedtls/library/ripemd160.c mbedtls/library/rsa.c mbedtls/library/sha1.c + mbedtls/library/sha3.c mbedtls/library/sha256.c mbedtls/library/sha512.c mbedtls/library/ssl_cache.c @@ -107,9 +109,11 @@ # warning C4245: '=': conversion from 'int' to 'mbedtls_mpi_uint', signed/unsigned mismatch # warning C4310: cast truncates constant value # warning C4204: nonstandard extension used + # warning C4389: '==': signed/unsigned mismatch + # /U_WIN32 : Avoid redfineded with WIN API # - MSFT:*_*_IA32_CC_FLAGS = /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 - MSFT:*_*_X64_CC_FLAGS = /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 + MSFT:*_*_IA32_CC_FLAGS = /U_WIN32 /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 /wd4389 + MSFT:*_*_X64_CC_FLAGS = /U_WIN32 /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 /wd4389 # # Disable following Visual Studio 2015 compiler warnings brought by mbedtls source, Index: edk2/CryptoPkg/Library/MbedTlsLib/MbedTlsLibFull.inf =================================================================== --- edk2.orig/CryptoPkg/Library/MbedTlsLib/MbedTlsLibFull.inf +++ edk2/CryptoPkg/Library/MbedTlsLib/MbedTlsLibFull.inf @@ -54,7 +54,8 @@ mbedtls/library/ssl_client.c mbedtls/library/ssl_debug_helpers_generated.c mbedtls/library/rsa_alt_helpers.c - mbedtls/library/hash_info.c + mbedtls/library/pk_ecc.c + mbedtls/library/x509write.c mbedtls/library/bignum_core.c mbedtls/library/constant_time.c mbedtls/library/memory_buffer_alloc.c @@ -72,6 +73,7 @@ mbedtls/library/ripemd160.c mbedtls/library/rsa.c mbedtls/library/sha1.c + mbedtls/library/sha3.c mbedtls/library/sha256.c mbedtls/library/sha512.c mbedtls/library/ssl_cache.c @@ -111,9 +113,12 @@ # warning C4245: '=': conversion from 'int' to 'mbedtls_mpi_uint', signed/unsigned mismatch # warning C4310: cast truncates constant value # warning C4204: nonstandard extension used + # warning C4389: signed/unsigned mismatch + # /U_WIN32 : Avoid redfineded with WIN API # - MSFT:*_*_IA32_CC_FLAGS = /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 - MSFT:*_*_X64_CC_FLAGS = /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 + MSFT:*_*_IA32_CC_FLAGS = /U_WIN32 /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 /wd4389 + MSFT:*_*_X64_CC_FLAGS = /U_WIN32 /DEFI32 /wd4244 /wd4132 /wd4245 /wd4310 /wd4204 /wd4389 + # # Disable following Visual Studio 2015 compiler warnings brought by mbedtls source,