Merge pull request #9146 from gilles-peskine-arm/config-headers-do-not-include-3.6
Backport 3.6: Document check-config.h and *adjust*.h as internal headers
diff --git a/ChangeLog.d/check-config.txt b/ChangeLog.d/check-config.txt
new file mode 100644
index 0000000..8570a11
--- /dev/null
+++ b/ChangeLog.d/check-config.txt
@@ -0,0 +1,9 @@
+Changes
+ * Warn if mbedtls/check_config.h is included manually, as this can
+ lead to spurious errors. Error if a *adjust*.h header is included
+ manually, as this can lead to silently inconsistent configurations,
+ potentially resulting in buffer overflows.
+ When migrating from Mbed TLS 2.x, if you had a custom config.h that
+ included check_config.h, remove this inclusion from the Mbed TLS 3.x
+ configuration file (renamed to mbedtls_config.h). This change was made
+ in Mbed TLS 3.0, but was not announced in a changelog entry at the time.
diff --git a/include/mbedtls/build_info.h b/include/mbedtls/build_info.h
index eab167f..cf38f90 100644
--- a/include/mbedtls/build_info.h
+++ b/include/mbedtls/build_info.h
@@ -101,6 +101,13 @@
#define inline __inline
#endif
+#if defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Something went wrong: MBEDTLS_CONFIG_FILES_READ defined before reading the config files!"
+#endif
+#if defined(MBEDTLS_CONFIG_IS_FINALIZED)
+#error "Something went wrong: MBEDTLS_CONFIG_IS_FINALIZED defined before reading the config files!"
+#endif
+
/* X.509, TLS and non-PSA crypto configuration */
#if !defined(MBEDTLS_CONFIG_FILE)
#include "mbedtls/mbedtls_config.h"
@@ -135,6 +142,12 @@
#endif
#endif /* defined(MBEDTLS_PSA_CRYPTO_CONFIG) */
+/* Indicate that all configuration files have been read.
+ * It is now time to adjust the configuration (follow through on dependencies,
+ * make PSA and legacy crypto consistent, etc.).
+ */
+#define MBEDTLS_CONFIG_FILES_READ
+
/* Auto-enable MBEDTLS_CTR_DRBG_USE_128_BIT_KEY if
* MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTH and MBEDTLS_CTR_DRBG_C defined
* to ensure a 128-bit key size in CTR_DRBG.
@@ -169,8 +182,13 @@
#include "mbedtls/config_adjust_ssl.h"
-/* Make sure all configuration symbols are set before including check_config.h,
- * even the ones that are calculated programmatically. */
+/* Indicate that all configuration symbols are set,
+ * even the ones that are calculated programmatically.
+ * It is now safe to query the configuration (to check it, to size buffers,
+ * etc.).
+ */
+#define MBEDTLS_CONFIG_IS_FINALIZED
+
#include "mbedtls/check_config.h"
#endif /* MBEDTLS_BUILD_INFO_H */
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index b3c038d..67a05f8 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
@@ -12,6 +19,13 @@
#define MBEDTLS_CHECK_CONFIG_H
/* *INDENT-OFF* */
+
+#if !defined(MBEDTLS_CONFIG_IS_FINALIZED)
+#warning "Do not include mbedtls/check_config.h manually! " \
+ "This may cause spurious errors. " \
+ "It is included automatically at the right point since Mbed TLS 3.0."
+#endif /* !MBEDTLS_CONFIG_IS_FINALIZED */
+
/*
* We assume CHAR_BIT is 8 in many places. In practice, this is true on our
* target platforms, so not an issue, but let's just be extra sure.
diff --git a/include/mbedtls/config_adjust_legacy_crypto.h b/include/mbedtls/config_adjust_legacy_crypto.h
index e477c07..8541161 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
@@ -22,6 +24,14 @@
#ifndef MBEDTLS_CONFIG_ADJUST_LEGACY_CRYPTO_H
#define MBEDTLS_CONFIG_ADJUST_LEGACY_CRYPTO_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/* Ideally, we'd set those as defaults in mbedtls_config.h, but
* putting an #ifdef _WIN32 in mbedtls_config.h would confuse config.py.
*
diff --git a/include/mbedtls/config_adjust_legacy_from_psa.h b/include/mbedtls/config_adjust_legacy_from_psa.h
index 0e4759d..04bdae6 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
@@ -16,6 +18,14 @@
#ifndef MBEDTLS_CONFIG_ADJUST_LEGACY_FROM_PSA_H
#define MBEDTLS_CONFIG_ADJUST_LEGACY_FROM_PSA_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/* Define appropriate ACCEL macros for the p256-m driver.
* In the future, those should be generated from the drivers JSON description.
*/
diff --git a/include/mbedtls/config_adjust_psa_from_legacy.h b/include/mbedtls/config_adjust_psa_from_legacy.h
index 3456615..14ca146 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
@@ -18,6 +20,14 @@
#ifndef MBEDTLS_CONFIG_ADJUST_PSA_FROM_LEGACY_H
#define MBEDTLS_CONFIG_ADJUST_PSA_FROM_LEGACY_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/*
* Ensure PSA_WANT_* defines are setup properly if MBEDTLS_PSA_CRYPTO_CONFIG
* is not defined
diff --git a/include/mbedtls/config_adjust_psa_superset_legacy.h b/include/mbedtls/config_adjust_psa_superset_legacy.h
index 3a55c3f..ef65cce 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
@@ -17,6 +19,14 @@
#ifndef MBEDTLS_CONFIG_ADJUST_PSA_SUPERSET_LEGACY_H
#define MBEDTLS_CONFIG_ADJUST_PSA_SUPERSET_LEGACY_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/****************************************************************/
/* Hashes that are built in are also enabled in PSA.
* This simplifies dependency declarations especially
diff --git a/include/mbedtls/config_adjust_ssl.h b/include/mbedtls/config_adjust_ssl.h
index 39c7b3b..309524a 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
@@ -22,6 +24,14 @@
#ifndef MBEDTLS_CONFIG_ADJUST_SSL_H
#define MBEDTLS_CONFIG_ADJUST_SSL_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/* The following blocks make it easier to disable all of TLS,
* or of TLS 1.2 or 1.3 or DTLS, without having to manually disable all
* key exchanges, options and extensions related to them. */
diff --git a/include/mbedtls/config_adjust_x509.h b/include/mbedtls/config_adjust_x509.h
index 346c8ae..c063251 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
@@ -22,4 +24,12 @@
#ifndef MBEDTLS_CONFIG_ADJUST_X509_H
#define MBEDTLS_CONFIG_ADJUST_X509_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include mbedtls/config_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
#endif /* MBEDTLS_CONFIG_ADJUST_X509_H */
diff --git a/include/psa/crypto_adjust_auto_enabled.h b/include/psa/crypto_adjust_auto_enabled.h
index 63fb29e..3a2af15 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.
*/
@@ -13,6 +15,14 @@
#ifndef PSA_CRYPTO_ADJUST_AUTO_ENABLED_H
#define PSA_CRYPTO_ADJUST_AUTO_ENABLED_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include psa/crypto_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
#define PSA_WANT_KEY_TYPE_DERIVE 1
#define PSA_WANT_KEY_TYPE_PASSWORD 1
#define PSA_WANT_KEY_TYPE_PASSWORD_HASH 1
diff --git a/include/psa/crypto_adjust_config_dependencies.h b/include/psa/crypto_adjust_config_dependencies.h
index 5a22205..92e9c4d 100644
--- a/include/psa/crypto_adjust_config_dependencies.h
+++ b/include/psa/crypto_adjust_config_dependencies.h
@@ -18,6 +18,14 @@
#ifndef PSA_CRYPTO_ADJUST_CONFIG_DEPENDENCIES_H
#define PSA_CRYPTO_ADJUST_CONFIG_DEPENDENCIES_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include psa/crypto_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
#if (defined(PSA_WANT_ALG_TLS12_PRF) && \
!defined(MBEDTLS_PSA_ACCEL_ALG_TLS12_PRF)) || \
(defined(PSA_WANT_ALG_TLS12_PSK_TO_MS) && \
diff --git a/include/psa/crypto_adjust_config_key_pair_types.h b/include/psa/crypto_adjust_config_key_pair_types.h
index 63afc0e..cec39e0 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.
@@ -19,6 +21,14 @@
#ifndef PSA_CRYPTO_ADJUST_KEYPAIR_TYPES_H
#define PSA_CRYPTO_ADJUST_KEYPAIR_TYPES_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include psa/crypto_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/*****************************************************************
* ANYTHING -> BASIC
****************************************************************/
diff --git a/include/psa/crypto_adjust_config_synonyms.h b/include/psa/crypto_adjust_config_synonyms.h
index 332b622..54b116f 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.
@@ -14,6 +16,14 @@
#ifndef PSA_CRYPTO_ADJUST_CONFIG_SYNONYMS_H
#define PSA_CRYPTO_ADJUST_CONFIG_SYNONYMS_H
+#if !defined(MBEDTLS_CONFIG_FILES_READ)
+#error "Do not include psa/crypto_adjust_*.h manually! This can lead to problems, " \
+ "up to and including runtime errors such as buffer overflows. " \
+ "If you're trying to fix a complaint from check_config.h, just remove " \
+ "it from your configuration file: since Mbed TLS 3.0, it is included " \
+ "automatically at the right point."
+#endif /* */
+
/****************************************************************/
/* De facto synonyms */
/****************************************************************/