From 975e74cb1ff74a0b7ecca301c3b8f6bd7d49f491 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 26 Apr 2024 14:18:10 +0200 Subject: 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(+) (limited to 'include') diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h index b3c038d..9c33fae 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 e477c07..a24616a 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 0e4759d..f5334f1 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 3456615..7c3a2d2 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 3a55c3f..6ccb91b 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 39c7b3b..4d8dc9d 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 346c8ae..d12f4d8 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 63fb29e..e2618d1 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 63afc0e..8308ac7 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 332b622..ad71050 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. -- cgit v1.1