From e0ec8f5348717d33bcef5bb745ba301b9128daee Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 26 Apr 2024 14:18:10 +0200 Subject: [PATCH] Document check-config.h and *adjust*.h as internal headers Including *adjust*.h directly is likely to cause them to be applied at the wrong time, resulting in an invalid or unintended configuration. Including check_config.h at the wrong time is likely to cause spurious errors. Signed-off-by: Gilles Peskine --- include/mbedtls/check_config.h | 7 +++++++ include/mbedtls/config_adjust_legacy_crypto.h | 2 ++ include/mbedtls/config_adjust_legacy_from_psa.h | 2 ++ include/mbedtls/config_adjust_psa_from_legacy.h | 2 ++ include/mbedtls/config_adjust_psa_superset_legacy.h | 2 ++ include/mbedtls/config_adjust_ssl.h | 2 ++ include/mbedtls/config_adjust_x509.h | 2 ++ include/psa/crypto_adjust_auto_enabled.h | 2 ++ include/psa/crypto_adjust_config_key_pair_types.h | 2 ++ include/psa/crypto_adjust_config_synonyms.h | 2 ++ 10 files changed, 25 insertions(+) diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h index b3c038dd2e..9c33faeb9a 100644 --- a/include/mbedtls/check_config.h +++ b/include/mbedtls/check_config.h @@ -2,6 +2,13 @@ * \file check_config.h * * \brief Consistency checks for configuration options + * + * This is an internal header. Do not include it directly. + * + * This header is included automatically by all public Mbed TLS headers + * (via mbedtls/build_info.h). Do not include it directly in a configuration + * file such as mbedtls/mbedtls_config.h or #MBEDTLS_USER_CONFIG_FILE! + * It would run at the wrong time due to missing derived symbols. */ /* * Copyright The Mbed TLS Contributors diff --git a/include/mbedtls/config_adjust_legacy_crypto.h b/include/mbedtls/config_adjust_legacy_crypto.h index e477c0796a..a24616a5a0 100644 --- a/include/mbedtls/config_adjust_legacy_crypto.h +++ b/include/mbedtls/config_adjust_legacy_crypto.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_legacy_crypto.h * \brief Adjust legacy configuration configuration * + * This is an internal header. Do not include it directly. + * * Automatically enable certain dependencies. Generally, MBEDLTS_xxx * configurations need to be explicitly enabled by the user: enabling * MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a diff --git a/include/mbedtls/config_adjust_legacy_from_psa.h b/include/mbedtls/config_adjust_legacy_from_psa.h index 0e4759de74..f5334f1574 100644 --- a/include/mbedtls/config_adjust_legacy_from_psa.h +++ b/include/mbedtls/config_adjust_legacy_from_psa.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_legacy_from_psa.h * \brief Adjust PSA configuration: activate legacy implementations * + * This is an internal header. Do not include it directly. + * * When MBEDTLS_PSA_CRYPTO_CONFIG is enabled, activate legacy implementations * of cryptographic mechanisms as needed to fulfill the needs of the PSA * configuration. Generally speaking, we activate a legacy mechanism if diff --git a/include/mbedtls/config_adjust_psa_from_legacy.h b/include/mbedtls/config_adjust_psa_from_legacy.h index 3456615943..7c3a2d2359 100644 --- a/include/mbedtls/config_adjust_psa_from_legacy.h +++ b/include/mbedtls/config_adjust_psa_from_legacy.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_psa_from_legacy.h * \brief Adjust PSA configuration: construct PSA configuration from legacy * + * This is an internal header. Do not include it directly. + * * When MBEDTLS_PSA_CRYPTO_CONFIG is disabled, we automatically enable * cryptographic mechanisms through the PSA interface when the corresponding * legacy mechanism is enabled. In many cases, this just enables the PSA diff --git a/include/mbedtls/config_adjust_psa_superset_legacy.h b/include/mbedtls/config_adjust_psa_superset_legacy.h index 3a55c3f6e1..6ccb91becd 100644 --- a/include/mbedtls/config_adjust_psa_superset_legacy.h +++ b/include/mbedtls/config_adjust_psa_superset_legacy.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_psa_superset_legacy.h * \brief Adjust PSA configuration: automatic enablement from legacy * + * This is an internal header. Do not include it directly. + * * To simplify some edge cases, we automatically enable certain cryptographic * mechanisms in the PSA API if they are enabled in the legacy API. The general * idea is that if legacy module M uses mechanism A internally, and A has diff --git a/include/mbedtls/config_adjust_ssl.h b/include/mbedtls/config_adjust_ssl.h index 39c7b3b117..4d8dc9dfac 100644 --- a/include/mbedtls/config_adjust_ssl.h +++ b/include/mbedtls/config_adjust_ssl.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_ssl.h * \brief Adjust TLS configuration * + * This is an internal header. Do not include it directly. + * * Automatically enable certain dependencies. Generally, MBEDLTS_xxx * configurations need to be explicitly enabled by the user: enabling * MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a diff --git a/include/mbedtls/config_adjust_x509.h b/include/mbedtls/config_adjust_x509.h index 346c8ae6d5..d12f4d82bc 100644 --- a/include/mbedtls/config_adjust_x509.h +++ b/include/mbedtls/config_adjust_x509.h @@ -2,6 +2,8 @@ * \file mbedtls/config_adjust_x509.h * \brief Adjust X.509 configuration * + * This is an internal header. Do not include it directly. + * * Automatically enable certain dependencies. Generally, MBEDLTS_xxx * configurations need to be explicitly enabled by the user: enabling * MBEDTLS_xxx_A but not MBEDTLS_xxx_B when A requires B results in a diff --git a/include/psa/crypto_adjust_auto_enabled.h b/include/psa/crypto_adjust_auto_enabled.h index 63fb29e85b..e2618d15dc 100644 --- a/include/psa/crypto_adjust_auto_enabled.h +++ b/include/psa/crypto_adjust_auto_enabled.h @@ -2,6 +2,8 @@ * \file psa/crypto_adjust_auto_enabled.h * \brief Adjust PSA configuration: enable always-on features * + * This is an internal header. Do not include it directly. + * * Always enable certain features which require a negligible amount of code * to implement, to avoid some edge cases in the configuration combinatorics. */ diff --git a/include/psa/crypto_adjust_config_key_pair_types.h b/include/psa/crypto_adjust_config_key_pair_types.h index 63afc0e402..8308ac759e 100644 --- a/include/psa/crypto_adjust_config_key_pair_types.h +++ b/include/psa/crypto_adjust_config_key_pair_types.h @@ -2,6 +2,8 @@ * \file psa/crypto_adjust_config_key_pair_types.h * \brief Adjust PSA configuration for key pair types. * + * This is an internal header. Do not include it directly. + * * See docs/proposed/psa-conditional-inclusion-c.md. * - Support non-basic operations in a keypair type implicitly enables basic * support for that keypair type. diff --git a/include/psa/crypto_adjust_config_synonyms.h b/include/psa/crypto_adjust_config_synonyms.h index 332b622c9b..ad71050ef2 100644 --- a/include/psa/crypto_adjust_config_synonyms.h +++ b/include/psa/crypto_adjust_config_synonyms.h @@ -2,6 +2,8 @@ * \file psa/crypto_adjust_config_synonyms.h * \brief Adjust PSA configuration: enable quasi-synonyms * + * This is an internal header. Do not include it directly. + * * When two features require almost the same code, we automatically enable * both when either one is requested, to reduce the combinatorics of * possible configurations.