From a02c1240063c4115ae3122ac2c4b06dd133e0131 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:03:19 +0100 Subject: [PATCH 01/19] Document MBEDTLS_CONFIG_FILE and MBEDTLS_USER_CONFIG_FILE Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 1c631b5267..4952f0e236 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3088,6 +3088,38 @@ * \{ */ +/* Meta configuration */ +/** + * \def MBEDTLS_CONFIG_FILE + * + * If defined, this is a header which will be included instead of + * `"mbedtls/mbedtls_config.h"`. + * This header file specifies the compile-time configuration of 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, relative + * to a directory on the include search pah. + */ +//#define MBEDTLS_CONFIG_FILE "mbedtls/mbedtls_config.h" + +/** + * \def MBEDTLS_USER_CONFIG_FILE + * + * If defined, this is a header which will be included after + * `"mbedtls/mbedtls_config.h"` or #MBEDTLS_CONFIG_FILE. + * + * 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, relative + * to a directory on the include search pah. + */ +//#define MBEDTLS_USER_CONFIG_FILE "/dev/null" + /* MPI / BIGNUM options */ //#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ //#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ From 750596e6d660a4044ca6d5536b2966932e212331 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:03:55 +0100 Subject: [PATCH 02/19] Improve documentation of MBEDTLS_PSA_CRYPTO_CONFIG Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 4952f0e236..7f2a027472 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1769,8 +1769,15 @@ * This setting allows support for cryptographic mechanisms through the PSA * API to be configured separately from support through the mbedtls API. * - * Uncomment this to enable use of PSA Crypto configuration settings which - * can be found in include/psa/crypto_config.h. + * When this option is disabled, the PSA API exposes the same cryptographic + * mechanism as the `mbedtls_xxx` API configured with `MBEDTLS_XXX` symbols. + * + * When this option is enabled, the PSA API exposes the cryptographic + * mechanisms requested by the `PSA_WANT_XXX` symbols defined in + * include/psa/crypto_config.h. The corresponding `MBEDTLS_XXX` settings are + * automatically enabled if required (i.e. if no PSA driver provides the + * mechanism). You may still freely enable additional `MBEDTLS_XXX` symbols + * in mbedtls_config.h. * * This feature is still experimental and is not ready for production since * it is not completed. From f4c6eb0a4983a34bdcf0c9c27e01a920f63df063 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:10:48 +0100 Subject: [PATCH 03/19] Support alternative MBEDTLS_PSA_CRYPTO_CONFIG_FILE When MBEDTLS_PSA_CRYPTO_CONFIG is enabled, support an alternative file to include instead of "psa/crypto_config.h", and an additional file to include after it. This follows the model of the existing MBEDTLS_{,USER_}CONFIG_FILE. Signed-off-by: Gilles Peskine --- ChangeLog.d/psa_crypto_config_file.txt | 6 +++++ include/mbedtls/config_psa.h | 8 ++++++ include/mbedtls/mbedtls_config.h | 36 ++++++++++++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 ChangeLog.d/psa_crypto_config_file.txt diff --git a/ChangeLog.d/psa_crypto_config_file.txt b/ChangeLog.d/psa_crypto_config_file.txt new file mode 100644 index 0000000000..98c176135e --- /dev/null +++ b/ChangeLog.d/psa_crypto_config_file.txt @@ -0,0 +1,6 @@ +Features + * When MBEDTLS_PSA_CRYPTO_CONFIG is enabled, you may list the PSA crypto + requirements in the file named by the new macro + MBEDTLS_PSA_CRYPTO_CONFIG_FILE instead of the default psa/crypto_config.h. + Furthermore you may name an additional file to include after the main + file with the macro MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE. diff --git a/include/mbedtls/config_psa.h b/include/mbedtls/config_psa.h index 68dda0f395..13e64dd782 100644 --- a/include/mbedtls/config_psa.h +++ b/include/mbedtls/config_psa.h @@ -31,9 +31,17 @@ #define MBEDTLS_CONFIG_PSA_H #if defined(MBEDTLS_PSA_CRYPTO_CONFIG) +#if defined(MBEDTLS_PSA_CRYPTO_CONFIG_FILE) +#include MBEDTLS_PSA_CRYPTO_CONFIG_FILE +#else #include "psa/crypto_config.h" +#endif #endif /* defined(MBEDTLS_PSA_CRYPTO_CONFIG) */ +#if defined(MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE) +#include MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE +#endif + #ifdef __cplusplus extern "C" { #endif diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 7f2a027472..a45598883d 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1779,6 +1779,9 @@ * mechanism). You may still freely enable additional `MBEDTLS_XXX` symbols * in mbedtls_config.h. * + * If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies + * an alternative location to use instead of include/psa/crypto_config.h. + * * This feature is still experimental and is not ready for production since * it is not completed. */ @@ -3127,6 +3130,39 @@ */ //#define MBEDTLS_USER_CONFIG_FILE "/dev/null" +/** + * \def MBEDTLS_PSA_CRYPTO_CONFIG_FILE + * + * If defined, this is a header which will be included instead of + * `"psa/crypto_config.h"`. + * This header file specifies which cryptographic mechanisms are available + * through the PSA API when #MBEDTLS_PSA_CRYPTO_CONFIG is enabled, and + * is not used when #MBEDTLS_PSA_CRYPTO_CONFIG is disabled. + * + * 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, relative + * to a directory on the include search pah. + */ +//#define MBEDTLS_PSA_CRYPTO_CONFIG_FILE "psa/crypto_config.h" + +/** + * \def MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE + * + * If defined, this is a header which will be included after + * `"psa/crypto_config.h"` or #MBEDTLS_PSA_CRYPTO_CONFIG_FILE. + * + * 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, relative + * to a directory on the include search pah. + */ +//#define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null" + /* MPI / BIGNUM options */ //#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ //#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ From 2003c2f455219a0992fce4a80c3bf80a24b5d0fe Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 20:55:57 +0200 Subject: [PATCH 04/19] Simplify build_mbedtls_config_file $CONFIG_H no longer includes check_config.h since Mbed TLS 3.0. Signed-off-by: Gilles Peskine --- tests/scripts/all.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 3aab764bf7..7516307f62 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2477,8 +2477,7 @@ component_build_mbedtls_config_file () { msg "build: make with MBEDTLS_CONFIG_FILE" # ~40s # Use the full config so as to catch a maximum of places where # the check of MBEDTLS_CONFIG_FILE might be missing. - scripts/config.py full - sed 's!"check_config.h"!"mbedtls/check_config.h"!' <"$CONFIG_H" >full_config.h + scripts/config.py -w full_config.h full echo '#error "MBEDTLS_CONFIG_FILE is not working"' >"$CONFIG_H" make CFLAGS="-I '$PWD' -DMBEDTLS_CONFIG_FILE='\"full_config.h\"'" rm -f full_config.h From f4798279c0a08512a134aeeb9446b4516f809edf Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:56:26 +0200 Subject: [PATCH 05/19] Remove obsolete comment mbedtls/mbedtls_config.h (formerly mbedtls/config.h) used to be included directly in many places, so we wanted to test that all of these places allowed the MBEDTLS_CONFIG_FILE override. Now mbedtls/mbedtls_config.h is only included via build_info.h, so this is not relevant anymore. It is no longer particularly useful to test MBEDTLS_CONFIG_FILE with the full config, but it isn't harmful either, so keep it that way. Signed-off-by: Gilles Peskine --- tests/scripts/all.sh | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 7516307f62..64662dc0c4 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2475,8 +2475,6 @@ component_test_gcc_opt () { component_build_mbedtls_config_file () { msg "build: make with MBEDTLS_CONFIG_FILE" # ~40s - # Use the full config so as to catch a maximum of places where - # the check of MBEDTLS_CONFIG_FILE might be missing. scripts/config.py -w full_config.h full echo '#error "MBEDTLS_CONFIG_FILE is not working"' >"$CONFIG_H" make CFLAGS="-I '$PWD' -DMBEDTLS_CONFIG_FILE='\"full_config.h\"'" From e10df779b79b31cc33f22fd1e2e7496d981ea0e0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:06:41 +0200 Subject: [PATCH 06/19] Test MBEDTLS_USER_CONFIG_FILE as such Signed-off-by: Gilles Peskine --- tests/scripts/all.sh | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 64662dc0c4..18e54342af 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2478,7 +2478,17 @@ component_build_mbedtls_config_file () { scripts/config.py -w full_config.h full echo '#error "MBEDTLS_CONFIG_FILE is not working"' >"$CONFIG_H" make CFLAGS="-I '$PWD' -DMBEDTLS_CONFIG_FILE='\"full_config.h\"'" - rm -f full_config.h + programs/test/query_compile_time_config MBEDTLS_NIST_KW_C + make clean + + msg "build: make with MBEDTLS_CONFIG_FILE + MBEDTLS_USER_CONFIG_FILE" + # In the user config, disable one feature (for simplicity, pick a feature + # that nothing else depends on). + echo '#undef MBEDTLS_NIST_KW_C' >user_config.h + make CFLAGS="-I '$PWD' -DMBEDTLS_CONFIG_FILE='\"full_config.h\"' -DMBEDTLS_USER_CONFIG_FILE='\"user_config.h\"'" + not programs/test/query_compile_time_config MBEDTLS_NIST_KW_C + + rm -f user_config.h full_config.h } component_test_m32_o0 () { From 7d904e7127fae576fbd180f1a2269d9da7442261 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:59:14 +0200 Subject: [PATCH 07/19] Test MBEDTLS_PSA_CRYPTO_CONFIG_FILE and MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE Signed-off-by: Gilles Peskine --- tests/scripts/all.sh | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index 18e54342af..a940c604e8 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2491,6 +2491,26 @@ component_build_mbedtls_config_file () { rm -f user_config.h full_config.h } +component_build_psa_config_file () { + msg "build: make with MBEDTLS_PSA_CRYPTO_CONFIG_FILE" # ~40s + scripts/config.py set MBEDTLS_PSA_CRYPTO_CONFIG + cp "$CRYPTO_CONFIG_H" psa_test_config.h + echo '#error "MBEDTLS_PSA_CRYPTO_CONFIG_FILE is not working"' >"$CRYPTO_CONFIG_H" + make CFLAGS="-I '$PWD' -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE='\"psa_test_config.h\"'" + programs/test/query_compile_time_config MBEDTLS_CMAC_C + make clean + + msg "build: make with MBEDTLS_PSA_CRYPTO_CONFIG_FILE + MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE" # ~40s + # In the user config, disable one feature, which will reflect on the + # mbedtls configuration so we can query it with query_compile_time_config. + echo '#undef PSA_WANT_ALG_CMAC' >psa_user_config.h + scripts/config.py unset MBEDTLS_CMAC_C + make CFLAGS="-I '$PWD' -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE='\"psa_test_config.h\"' -DMBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE='\"psa_user_config.h\"'" + not programs/test/query_compile_time_config MBEDTLS_CMAC_C + + rm -f psa_test_config.h psa_user_config.h +} + component_test_m32_o0 () { # Build without optimization, so as to use portable C code (in a 32-bit # build) and not the i386-specific inline assembly. From ba4162a52631c0d3ec342a91a0d8924410b4463a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 11 Apr 2022 17:04:38 +0200 Subject: [PATCH 08/19] Place MBEDTLS_CONFIG_FILE and such into a new section Include this new section in the "full for documentation" (`realfull`) configuration, so that these options are documented in the official documentation build (`scripts/apidoc_full.sh`). Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 20 ++++++++++++++++++-- scripts/config.py | 12 ++++++++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index a45598883d..f4a9e3bddf 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3084,7 +3084,7 @@ /** \} name SECTION: mbed TLS modules */ /** - * \name SECTION: Module configuration options + * \name SECTION: General configuration options * * This section allows for the setting of module specific sizes and * configuration options. The default values are already present in the @@ -3098,7 +3098,6 @@ * \{ */ -/* Meta configuration */ /** * \def MBEDTLS_CONFIG_FILE * @@ -3163,6 +3162,23 @@ */ //#define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null" +/** \} name SECTION: General configuration options */ + +/** + * \name SECTION: Module configuration options + * + * This section allows for the setting of module specific sizes and + * configuration options. The default values are already present in the + * relevant header files and should suffice for the regular use cases. + * + * Our advice is to enable options and change their values here + * only if you have a good reason and know the consequences. + * + * Please check the respective header file for documentation on these + * parameters (to prevent duplicate documentation). + * \{ + */ + /* MPI / BIGNUM options */ //#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ //#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ diff --git a/scripts/config.py b/scripts/config.py index 0ab1e394f0..24c953802b 100755 --- a/scripts/config.py +++ b/scripts/config.py @@ -161,8 +161,16 @@ def is_full_section(section): return section.endswith('support') or section.endswith('modules') def realfull_adapter(_name, active, section): - """Activate all symbols found in the system and feature sections.""" - if not is_full_section(section): + """Activate all symbols found in the global and boolean feature sections. + + This is intended for building the documentation, including the + documentation of settings that are activated by defining an optional + preprocessor macro. + + Do not activate definitions in the section containing symbols that are + supposed to be defined and documented in their own module. + """ + if section == 'Module configuration options': return active return True From 6457ef9b3c2db13babe0588fa9b182560f2f71cc Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 11 Apr 2022 16:42:37 +0200 Subject: [PATCH 09/19] Format literal # in a way that doesn't confuse older Doxygen With Doxygen 1.8.11 (as on Ubuntu 16.04), `#include` doesn't protect the hash character enough, and Doxygen tries to link to something called include. (Doxygen 1.8.17 doesn't have this problem.) Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index f4a9e3bddf..2d73b2abc8 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3105,9 +3105,9 @@ * `"mbedtls/mbedtls_config.h"`. * This header file specifies the compile-time configuration of Mbed TLS. * - * This macro is expanded after an `#include` directive. This is a popular but + * 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. + * with compilers that perform macro expansion on an \#include line. * * The value of this symbol is typically a path in double quotes, relative * to a directory on the include search pah. @@ -3120,9 +3120,9 @@ * If defined, this is a header which will be included after * `"mbedtls/mbedtls_config.h"` or #MBEDTLS_CONFIG_FILE. * - * This macro is expanded after an `#include` directive. This is a popular but + * 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. + * with compilers that perform macro expansion on an \#include line. * * The value of this symbol is typically a path in double quotes, relative * to a directory on the include search pah. @@ -3138,9 +3138,9 @@ * through the PSA API when #MBEDTLS_PSA_CRYPTO_CONFIG is enabled, and * is not used when #MBEDTLS_PSA_CRYPTO_CONFIG is disabled. * - * This macro is expanded after an `#include` directive. This is a popular but + * 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. + * with compilers that perform macro expansion on an \#include line. * * The value of this symbol is typically a path in double quotes, relative * to a directory on the include search pah. @@ -3153,9 +3153,9 @@ * If defined, this is a header which will be included after * `"psa/crypto_config.h"` or #MBEDTLS_PSA_CRYPTO_CONFIG_FILE. * - * This macro is expanded after an `#include` directive. This is a popular but + * 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. + * with compilers that perform macro expansion on an \#include line. * * The value of this symbol is typically a path in double quotes, relative * to a directory on the include search pah. From 611179c3f557128afa24a3cb002dc06c3ab65be4 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:04:48 +0200 Subject: [PATCH 10/19] Fix name mismatch in section end comment Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 2d73b2abc8..efbc81691f 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3460,4 +3460,4 @@ */ //#define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED -/** \} name SECTION: Customisation configuration options */ +/** \} name SECTION: Module configuration options */ From d5793ce27352c10db1ffed5973d8046ee51001e1 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:05:10 +0200 Subject: [PATCH 11/19] Document the section "General configuration options" Replace the copypasta that was there. Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index efbc81691f..f608b63cef 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3086,15 +3086,9 @@ /** * \name SECTION: General configuration options * - * This section allows for the setting of module specific sizes and - * configuration options. The default values are already present in the - * relevant header files and should suffice for the regular use cases. + * This section contains Mbed TLS build settings that are not associated + * with a particular module. * - * Our advice is to enable options and change their values here - * only if you have a good reason and know the consequences. - * - * Please check the respective header file for documentation on these - * parameters (to prevent duplicate documentation). * \{ */ From 3f49cc14e760db7e4207f27814b9bd717b397678 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:21:16 +0200 Subject: [PATCH 12/19] Clarify the "duplicate documentation" remark This remark is intended for maintainers, not for users. It should not have been in the Doxygen typeset part. Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index f608b63cef..229b432533 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3167,11 +3167,15 @@ * * Our advice is to enable options and change their values here * only if you have a good reason and know the consequences. - * - * Please check the respective header file for documentation on these - * parameters (to prevent duplicate documentation). * \{ */ +/* The Doxygen documentation here is used when a user comments out a + * setting and runs doxygen themselves. On the other hand, when we typeset + * the full documentation including disabled settings, the documentation + * in specific modules' header files is used if present. When editing this + * file, make sure that each option is documented in exactly one place, + * plus optionally a same-line Doxygen comment here if there is a Doxygen + * comment in the specific module. */ /* MPI / BIGNUM options */ //#define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum window size used. */ From f68f43a42ee00adf0f19080f228e64b302fe6a05 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:22:20 +0200 Subject: [PATCH 13/19] State explicitly USER config files can modify the default config Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 229b432533..a91807bd7c 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3113,6 +3113,8 @@ * * If defined, this is a header which will be included after * `"mbedtls/mbedtls_config.h"` or #MBEDTLS_CONFIG_FILE. + * This allows you to modify the default configuration, including the ability + * to undefine options that are enabled by default. * * 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 @@ -3146,6 +3148,8 @@ * * If defined, this is a header which will be included after * `"psa/crypto_config.h"` or #MBEDTLS_PSA_CRYPTO_CONFIG_FILE. + * This allows you to modify the default configuration, including the ability + * to undefine options that are enabled by default. * * 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 From db0421b0733de472852ff51a4f91a3be295e142e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:22:49 +0200 Subject: [PATCH 14/19] More precise explanation of MBEDTLS_PSA_CRYPTO_CONFIG disabled Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index a91807bd7c..e40da0e295 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1769,8 +1769,9 @@ * This setting allows support for cryptographic mechanisms through the PSA * API to be configured separately from support through the mbedtls API. * - * When this option is disabled, the PSA API exposes the same cryptographic - * mechanism as the `mbedtls_xxx` API configured with `MBEDTLS_XXX` symbols. + * When this option is disabled, the PSA API exposes the cryptographic + * mechanisms that can be implemented on top of the `mbedtls_xxx` API + * configured with `MBEDTLS_XXX` symbols. * * When this option is enabled, the PSA API exposes the cryptographic * mechanisms requested by the `PSA_WANT_XXX` symbols defined in From 45e680e651d887140e576218d821f809e8f5e537 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:23:21 +0200 Subject: [PATCH 15/19] Explain why we check that a certain feature is enabled Signed-off-by: Gilles Peskine --- tests/scripts/all.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh index a940c604e8..ce7207ea2c 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2478,6 +2478,7 @@ component_build_mbedtls_config_file () { scripts/config.py -w full_config.h full echo '#error "MBEDTLS_CONFIG_FILE is not working"' >"$CONFIG_H" make CFLAGS="-I '$PWD' -DMBEDTLS_CONFIG_FILE='\"full_config.h\"'" + # Make sure this feature is enabled. We'll disable it in the next phase. programs/test/query_compile_time_config MBEDTLS_NIST_KW_C make clean @@ -2497,6 +2498,7 @@ component_build_psa_config_file () { cp "$CRYPTO_CONFIG_H" psa_test_config.h echo '#error "MBEDTLS_PSA_CRYPTO_CONFIG_FILE is not working"' >"$CRYPTO_CONFIG_H" make CFLAGS="-I '$PWD' -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE='\"psa_test_config.h\"'" + # Make sure this feature is enabled. We'll disable it in the next phase. programs/test/query_compile_time_config MBEDTLS_CMAC_C make clean From 0c4db1f20d1467e5100cfe05f2c48da1beba21c5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:44:01 +0200 Subject: [PATCH 16/19] Wording improvement Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index e40da0e295..1cb38eb866 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1781,7 +1781,7 @@ * in mbedtls_config.h. * * If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies - * an alternative location to use instead of include/psa/crypto_config.h. + * 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. From 58ffcba9d4a93aa80f2c3dbff8f169046f8475eb Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:44:16 +0200 Subject: [PATCH 17/19] Make it explicit that an absolute path is also ok Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 1cb38eb866..c170d4fc46 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3104,8 +3104,8 @@ * 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, relative - * to a directory on the include search pah. + * 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_CONFIG_FILE "mbedtls/mbedtls_config.h" @@ -3121,8 +3121,8 @@ * 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, relative - * to a directory on the include search pah. + * 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_USER_CONFIG_FILE "/dev/null" @@ -3139,8 +3139,8 @@ * 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, relative - * to a directory on the include search pah. + * 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_CONFIG_FILE "psa/crypto_config.h" @@ -3156,8 +3156,8 @@ * 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, relative - * to a directory on the include search pah. + * 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_USER_CONFIG_FILE "/dev/null" From 5dc8a0ac5a119953cf423aa5fc763172cd54422c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:46:06 +0200 Subject: [PATCH 18/19] Wording improvement Signed-off-by: Gilles Peskine --- ChangeLog.d/psa_crypto_config_file.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ChangeLog.d/psa_crypto_config_file.txt b/ChangeLog.d/psa_crypto_config_file.txt index 98c176135e..d42651d938 100644 --- a/ChangeLog.d/psa_crypto_config_file.txt +++ b/ChangeLog.d/psa_crypto_config_file.txt @@ -1,6 +1,6 @@ Features * When MBEDTLS_PSA_CRYPTO_CONFIG is enabled, you may list the PSA crypto - requirements in the file named by the new macro + feature requirements in the file named by the new macro MBEDTLS_PSA_CRYPTO_CONFIG_FILE instead of the default psa/crypto_config.h. Furthermore you may name an additional file to include after the main file with the macro MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE. From efffd6410a07fe4b0e7e2b156c370e2f9a847aa8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 26 Apr 2022 18:13:01 +0200 Subject: [PATCH 19/19] Note that MBEDTLS_CONFIG_FILE can't be defined inside the config file Signed-off-by: Gilles Peskine --- include/mbedtls/mbedtls_config.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index c170d4fc46..be5b8b0fa2 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3099,6 +3099,9 @@ * If defined, this is a header which will be included instead of * `"mbedtls/mbedtls_config.h"`. * This header file specifies the compile-time configuration of Mbed TLS. + * Unlike other configuration options, this one must be defined on the + * compiler command line: a definition in `mbedtls_config.h` would have + * no effect. * * 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