From 781f734bb6732c1e81062c830c54410162dcf2f1 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:03:19 +0100 Subject: [PATCH 01/21] Document MBEDTLS_CONFIG_FILE and MBEDTLS_USER_CONFIG_FILE Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index a93e38a8d..5e2931115 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3624,6 +3624,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 528343513c9e16cd0ee5f086122ab8924cec66e2 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:03:55 +0100 Subject: [PATCH 02/21] Improve documentation of MBEDTLS_PSA_CRYPTO_CONFIG Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 5e2931115..2bb161062 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2167,8 +2167,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. * * If you enable this option and write your own configuration file, you must * include mbedtls/config_psa.h in your configuration file. The default From 7e2a91fcb6fde9e952a48afbb32a623b89ed5ed6 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 16 Mar 2022 17:10:48 +0100 Subject: [PATCH 03/21] 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.h | 36 ++++++++++++++++++++++++++ include/mbedtls/config_psa.h | 8 ++++++ 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 000000000..98c176135 --- /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.h b/include/mbedtls/config.h index 2bb161062..81fc4c5f0 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2177,6 +2177,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. + * * If you enable this option and write your own configuration file, you must * include mbedtls/config_psa.h in your configuration file. The default * provided mbedtls/config.h contains the necessary inclusion. @@ -3663,6 +3666,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. */ diff --git a/include/mbedtls/config_psa.h b/include/mbedtls/config_psa.h index 5609fa64a..4c3808842 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 From 6af9dc9c59020ee66b6787070d3a4098696af321 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 20:55:57 +0200 Subject: [PATCH 04/21] 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 6677b20b8..96189ce20 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2624,8 +2624,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 78e5288a944981b44b6fd9304127fc4abf50ca89 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:56:26 +0200 Subject: [PATCH 05/21] 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 96189ce20..00197579e 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2622,8 +2622,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 036a9bb92b5942ad5c507746a6a665eba39a8df8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:06:41 +0200 Subject: [PATCH 06/21] 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 00197579e..aebb48305 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2625,7 +2625,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 690a2ef13c12bb1916d4524f7b08c79eb6fe8e28 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 7 Apr 2022 21:59:14 +0200 Subject: [PATCH 07/21] 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 aebb48305..27aeb8c3b 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2638,6 +2638,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 86198d71e3f2d0684b4261e9c40baab7f3cff7a0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 11 Apr 2022 17:04:38 +0200 Subject: [PATCH 08/21] 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/config.h | 20 ++++++++++++++++++-- scripts/config.py | 12 ++++++++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 81fc4c5f0..bf28de5fb 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3620,7 +3620,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 @@ -3634,7 +3634,6 @@ * \{ */ -/* Meta configuration */ /** * \def MBEDTLS_CONFIG_FILE * @@ -3699,6 +3698,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 ded77854e..19b60e1b5 100755 --- a/scripts/config.py +++ b/scripts/config.py @@ -152,8 +152,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 d742baa13489cb183d0a65d465f79ca1e5c146c5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 11 Apr 2022 16:42:37 +0200 Subject: [PATCH 09/21] 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/config.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index bf28de5fb..f8e9882f7 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3641,9 +3641,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. @@ -3656,9 +3656,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. @@ -3674,9 +3674,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. @@ -3689,9 +3689,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 1341e214622f0dc4fccb338b1dbb115b58063d30 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:04:48 +0200 Subject: [PATCH 10/21] Fix name mismatch in section end comment Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index f8e9882f7..54501b108 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -4102,7 +4102,7 @@ */ //#define MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED -/** \} name SECTION: Customisation configuration options */ +/** \} name SECTION: Module configuration options */ /* Target and application specific configurations * From 726652648e407add7ab1d53d32934f70c9b4611f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:05:10 +0200 Subject: [PATCH 11/21] Document the section "General configuration options" Replace the copypasta that was there. Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 54501b108..8b781a0ee 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3622,15 +3622,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 25496d0858015f62587473b13a8c25bdaf504aa6 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:21:16 +0200 Subject: [PATCH 12/21] 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/config.h | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 8b781a0ee..2d2c67af0 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3703,11 +3703,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 99e075bf15ca9455ff7a7cef8de938b08a8bce66 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:22:20 +0200 Subject: [PATCH 13/21] State explicitly USER config files can modify the default config Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 2d2c67af0..37337d504 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3649,6 +3649,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 @@ -3682,6 +3684,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 33665c480029d63d297405ee56633a948c666c54 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:22:49 +0200 Subject: [PATCH 14/21] More precise explanation of MBEDTLS_PSA_CRYPTO_CONFIG disabled Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 37337d504..009ed0665 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2167,8 +2167,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 932b30ba65336f3a4dfae90314f1993e16d35eb5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Apr 2022 23:23:21 +0200 Subject: [PATCH 15/21] 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 27aeb8c3b..e4ab85cc7 100755 --- a/tests/scripts/all.sh +++ b/tests/scripts/all.sh @@ -2625,6 +2625,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 @@ -2644,6 +2645,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 8a5577508ea46f4611e9a1ed5cfd718e63d062f8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:44:01 +0200 Subject: [PATCH 16/21] Wording improvement Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 009ed0665..75df65b63 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2179,7 +2179,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. * * If you enable this option and write your own configuration file, you must * include mbedtls/config_psa.h in your configuration file. The default From 29e89bb44820310736f6df863d22fcfc8d0683af Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:44:16 +0200 Subject: [PATCH 17/21] Make it explicit that an absolute path is also ok Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 75df65b63..c27a9d190 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3640,8 +3640,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" @@ -3657,8 +3657,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" @@ -3675,8 +3675,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" @@ -3692,8 +3692,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 46cc5fd3212ccd598ff86ff5a36bd76e917aa188 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 14 Apr 2022 12:46:06 +0200 Subject: [PATCH 18/21] 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 98c176135..d42651d93 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 db7d0d9bef7affc20790b8535cc4754506a96c4c Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 15 Apr 2022 10:57:20 +0200 Subject: [PATCH 19/21] Update query_config Signed-off-by: Gilles Peskine --- programs/test/query_config.c | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/programs/test/query_config.c b/programs/test/query_config.c index 10b01dd6c..331310165 100644 --- a/programs/test/query_config.c +++ b/programs/test/query_config.c @@ -2320,6 +2320,38 @@ int query_config( const char *config ) } #endif /* MBEDTLS_XTEA_C */ +#if defined(MBEDTLS_CONFIG_FILE) + if( strcmp( "MBEDTLS_CONFIG_FILE", config ) == 0 ) + { + MACRO_EXPANSION_TO_STR( MBEDTLS_CONFIG_FILE ); + return( 0 ); + } +#endif /* MBEDTLS_CONFIG_FILE */ + +#if defined(MBEDTLS_USER_CONFIG_FILE) + if( strcmp( "MBEDTLS_USER_CONFIG_FILE", config ) == 0 ) + { + MACRO_EXPANSION_TO_STR( MBEDTLS_USER_CONFIG_FILE ); + return( 0 ); + } +#endif /* MBEDTLS_USER_CONFIG_FILE */ + +#if defined(MBEDTLS_PSA_CRYPTO_CONFIG_FILE) + if( strcmp( "MBEDTLS_PSA_CRYPTO_CONFIG_FILE", config ) == 0 ) + { + MACRO_EXPANSION_TO_STR( MBEDTLS_PSA_CRYPTO_CONFIG_FILE ); + return( 0 ); + } +#endif /* MBEDTLS_PSA_CRYPTO_CONFIG_FILE */ + +#if defined(MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE) + if( strcmp( "MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE", config ) == 0 ) + { + MACRO_EXPANSION_TO_STR( MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE ); + return( 0 ); + } +#endif /* MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE */ + #if defined(MBEDTLS_MPI_WINDOW_SIZE) if( strcmp( "MBEDTLS_MPI_WINDOW_SIZE", config ) == 0 ) { @@ -3946,6 +3978,22 @@ void list_config( void ) OUTPUT_MACRO_NAME_VALUE(MBEDTLS_XTEA_C); #endif /* MBEDTLS_XTEA_C */ +#if defined(MBEDTLS_CONFIG_FILE) + OUTPUT_MACRO_NAME_VALUE(MBEDTLS_CONFIG_FILE); +#endif /* MBEDTLS_CONFIG_FILE */ + +#if defined(MBEDTLS_USER_CONFIG_FILE) + OUTPUT_MACRO_NAME_VALUE(MBEDTLS_USER_CONFIG_FILE); +#endif /* MBEDTLS_USER_CONFIG_FILE */ + +#if defined(MBEDTLS_PSA_CRYPTO_CONFIG_FILE) + OUTPUT_MACRO_NAME_VALUE(MBEDTLS_PSA_CRYPTO_CONFIG_FILE); +#endif /* MBEDTLS_PSA_CRYPTO_CONFIG_FILE */ + +#if defined(MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE) + OUTPUT_MACRO_NAME_VALUE(MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE); +#endif /* MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE */ + #if defined(MBEDTLS_MPI_WINDOW_SIZE) OUTPUT_MACRO_NAME_VALUE(MBEDTLS_MPI_WINDOW_SIZE); #endif /* MBEDTLS_MPI_WINDOW_SIZE */ From 8290976801107fad1865124d8aedae8b6adef5c5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 26 Apr 2022 18:10:11 +0200 Subject: [PATCH 20/21] Fix references to mbedtls_config.h These were a mistake when backporting the change from the development branch, where mbedtls/config.h has been renamed to mbedtls/mbedtls_config.h. Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index c27a9d190..41e98217e 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2176,7 +2176,7 @@ * 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. + * in config.h. * * If the symbol #MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies * an alternative header to include instead of include/psa/crypto_config.h. @@ -3633,7 +3633,7 @@ * \def MBEDTLS_CONFIG_FILE * * If defined, this is a header which will be included instead of - * `"mbedtls/mbedtls_config.h"`. + * `"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 @@ -3643,13 +3643,13 @@ * 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" +//#define MBEDTLS_CONFIG_FILE "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. + * `"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. * From 238f976ad1ec87539adb09f08c9d63c8726ed9e0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 26 Apr 2022 18:13:01 +0200 Subject: [PATCH 21/21] Note that MBEDTLS_CONFIG_FILE can't be defined inside the config file Signed-off-by: Gilles Peskine --- include/mbedtls/config.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 41e98217e..3ffb1e2e1 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -3635,6 +3635,8 @@ * If defined, this is a header which will be included instead of * `"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 `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