From 975e74cb1ff74a0b7ecca301c3b8f6bd7d49f491 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Fri, 26 Apr 2024 14:18:10 +0200
Subject: [PATCH 1/8] 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 <Gilles.Peskine@arm.com>
---
 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 b3c038dd2..9c33faeb9 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 e477c0796..a24616a5a 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 0e4759de7..f5334f157 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 345661594..7c3a2d235 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 3a55c3f6e..6ccb91bec 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 39c7b3b11..4d8dc9dfa 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 346c8ae6d..d12f4d82b 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 63fb29e85..e2618d15d 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 63afc0e40..8308ac759 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 332b622c9..ad71050ef 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.

From fef877f51f562acd23ed46c1cb70b783c13432f3 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Fri, 26 Apr 2024 14:25:22 +0200
Subject: [PATCH 2/8] Belated changelog entry for not including check_config.h

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 ChangeLog.d/check-config.txt | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 ChangeLog.d/check-config.txt

diff --git a/ChangeLog.d/check-config.txt b/ChangeLog.d/check-config.txt
new file mode 100644
index 000000000..86723e090
--- /dev/null
+++ b/ChangeLog.d/check-config.txt
@@ -0,0 +1,6 @@
+Changes
+   * Explicitly state that mbedtls/check_config.h must not be included manually.
+     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.

From d33eb55cce2f6f8110f6e23fe6fb31e23e67fa2f Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 16 May 2024 14:44:15 +0200
Subject: [PATCH 3/8] Macros to indicate the finalization level of the
 configuration

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/build_info.h | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/include/mbedtls/build_info.h b/include/mbedtls/build_info.h
index eab167f38..e13e236d4 100644
--- a/include/mbedtls/build_info.h
+++ b/include/mbedtls/build_info.h
@@ -101,6 +101,9 @@
 #define inline __inline
 #endif
 
+#undef MBEDTLS_CONFIG_FILES_READ
+#undef MBEDTLS_CONFIG_IS_FINALIZED
+
 /* X.509, TLS and non-PSA crypto configuration */
 #if !defined(MBEDTLS_CONFIG_FILE)
 #include "mbedtls/mbedtls_config.h"
@@ -135,6 +138,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 +178,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 */

From 0b8ece6beb97b6b82783bce2da7a0a3c50b5fb2a Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 16 May 2024 14:46:09 +0200
Subject: [PATCH 4/8] Error out if *adjust* headers are included manually

Some projects using Mbed TLS have migrated their configuration
file (config.h -> mbedtls_config.h, or MBEDTLS_CONFIG_FILE) from Mbed TLS
2.x, and kept including check_config.h. This is unnecessary since Mbed TLS
3.0, and increasingly in 3.x it may report spurious errors because the
configuration adjustments have not been done yet. This has led some
projects to include configuration adjustment headers manually, but only
partially or in the wrong order, which can result in silent inconsistencies.
Error out if this happens, with a message mentioning check_config.h since
that's the likely root cause.

```
perl -i -pe '$name = $ARGV; $name =~ s!include/!!; $name =~ s!_adjust_.*!_adjust_*.h!; $_ .= "\n#if !defined(MBEDTLS_CONFIG_FILES_READ)\n#error \"Do not include $name manually! This can lead to problems, \" \\\n    \"up to and including runtime errors such as buffer overflows. \" \\\n    \"If you're trying to fix a complaint from check_config.h, just remove it \" \\\n    \"from your configuration file: since Mbed TLS 3.0, it is included \" \\\n    \"automatically at the right time.\"\n#endif /* !MBEDTLS_CONFIG_FILES_READ */\n" if /^#define .*_H$/' include/*/*adjust*.h
```

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/config_adjust_legacy_crypto.h       | 8 ++++++++
 include/mbedtls/config_adjust_legacy_from_psa.h     | 8 ++++++++
 include/mbedtls/config_adjust_psa_from_legacy.h     | 8 ++++++++
 include/mbedtls/config_adjust_psa_superset_legacy.h | 8 ++++++++
 include/mbedtls/config_adjust_ssl.h                 | 8 ++++++++
 include/mbedtls/config_adjust_x509.h                | 8 ++++++++
 include/psa/crypto_adjust_auto_enabled.h            | 8 ++++++++
 include/psa/crypto_adjust_config_dependencies.h     | 8 ++++++++
 include/psa/crypto_adjust_config_key_pair_types.h   | 8 ++++++++
 include/psa/crypto_adjust_config_synonyms.h         | 8 ++++++++
 10 files changed, 80 insertions(+)

diff --git a/include/mbedtls/config_adjust_legacy_crypto.h b/include/mbedtls/config_adjust_legacy_crypto.h
index a24616a5a..1d1b29ec5 100644
--- a/include/mbedtls/config_adjust_legacy_crypto.h
+++ b/include/mbedtls/config_adjust_legacy_crypto.h
@@ -24,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 time."
+#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 f5334f157..c8e4d03a4 100644
--- a/include/mbedtls/config_adjust_legacy_from_psa.h
+++ b/include/mbedtls/config_adjust_legacy_from_psa.h
@@ -18,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 time."
+#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 7c3a2d235..3495f67bf 100644
--- a/include/mbedtls/config_adjust_psa_from_legacy.h
+++ b/include/mbedtls/config_adjust_psa_from_legacy.h
@@ -20,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 time."
+#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 6ccb91bec..0cbad256a 100644
--- a/include/mbedtls/config_adjust_psa_superset_legacy.h
+++ b/include/mbedtls/config_adjust_psa_superset_legacy.h
@@ -19,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 time."
+#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 4d8dc9dfa..8c824661f 100644
--- a/include/mbedtls/config_adjust_ssl.h
+++ b/include/mbedtls/config_adjust_ssl.h
@@ -24,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 time."
+#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 d12f4d82b..3c95ce404 100644
--- a/include/mbedtls/config_adjust_x509.h
+++ b/include/mbedtls/config_adjust_x509.h
@@ -24,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 time."
+#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 e2618d15d..59eb4f66c 100644
--- a/include/psa/crypto_adjust_auto_enabled.h
+++ b/include/psa/crypto_adjust_auto_enabled.h
@@ -15,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 time."
+#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 5a22205bf..b63770fe9 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 time."
+#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 8308ac759..76a965448 100644
--- a/include/psa/crypto_adjust_config_key_pair_types.h
+++ b/include/psa/crypto_adjust_config_key_pair_types.h
@@ -21,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 time."
+#endif /* */
+
 /*****************************************************************
  * ANYTHING -> BASIC
  ****************************************************************/
diff --git a/include/psa/crypto_adjust_config_synonyms.h b/include/psa/crypto_adjust_config_synonyms.h
index ad71050ef..d92ca1150 100644
--- a/include/psa/crypto_adjust_config_synonyms.h
+++ b/include/psa/crypto_adjust_config_synonyms.h
@@ -16,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 time."
+#endif /* */
+
 /****************************************************************/
 /* De facto synonyms */
 /****************************************************************/

From 690fb5e0b0ee0921ccfe7d5e8c5bb96b06a8106b Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 16 May 2024 14:54:04 +0200
Subject: [PATCH 5/8] Warn if mbedtls_config.h is included manually

Some projects using Mbed TLS have migrated their configuration
file (config.h -> mbedtls_config.h, or MBEDTLS_CONFIG_FILE) from Mbed TLS
2.x, and kept including check_config.h. This is unnecessary since Mbed TLS
3.0, and increasingly in 3.x it may report spurious errors because the
configuration adjustments have not been done yet.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/check_config.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index 9c33faeb9..67a05f83b 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -19,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.

From d2f191adb0022a6d09880f6f4cb78b0b5b3c8402 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 16 May 2024 14:57:03 +0200
Subject: [PATCH 6/8] Document that there is now an error for dangerous
 inclusions

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 ChangeLog.d/check-config.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/ChangeLog.d/check-config.txt b/ChangeLog.d/check-config.txt
index 86723e090..8570a1175 100644
--- a/ChangeLog.d/check-config.txt
+++ b/ChangeLog.d/check-config.txt
@@ -1,5 +1,8 @@
 Changes
-   * Explicitly state that mbedtls/check_config.h must not be included manually.
+   * 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

From 9df7806b370727d7c453ba9a0959f6b4b6176216 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 29 May 2024 09:33:04 +0200
Subject: [PATCH 7/8] Tweak wording

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 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_dependencies.h     | 2 +-
 include/psa/crypto_adjust_config_key_pair_types.h   | 2 +-
 include/psa/crypto_adjust_config_synonyms.h         | 2 +-
 10 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/include/mbedtls/config_adjust_legacy_crypto.h b/include/mbedtls/config_adjust_legacy_crypto.h
index 1d1b29ec5..854116190 100644
--- a/include/mbedtls/config_adjust_legacy_crypto.h
+++ b/include/mbedtls/config_adjust_legacy_crypto.h
@@ -29,7 +29,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /* Ideally, we'd set those as defaults in mbedtls_config.h, but
diff --git a/include/mbedtls/config_adjust_legacy_from_psa.h b/include/mbedtls/config_adjust_legacy_from_psa.h
index c8e4d03a4..04bdae61b 100644
--- a/include/mbedtls/config_adjust_legacy_from_psa.h
+++ b/include/mbedtls/config_adjust_legacy_from_psa.h
@@ -23,7 +23,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /* Define appropriate ACCEL macros for the p256-m driver.
diff --git a/include/mbedtls/config_adjust_psa_from_legacy.h b/include/mbedtls/config_adjust_psa_from_legacy.h
index 3495f67bf..14ca14696 100644
--- a/include/mbedtls/config_adjust_psa_from_legacy.h
+++ b/include/mbedtls/config_adjust_psa_from_legacy.h
@@ -25,7 +25,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /*
diff --git a/include/mbedtls/config_adjust_psa_superset_legacy.h b/include/mbedtls/config_adjust_psa_superset_legacy.h
index 0cbad256a..ef65cce0d 100644
--- a/include/mbedtls/config_adjust_psa_superset_legacy.h
+++ b/include/mbedtls/config_adjust_psa_superset_legacy.h
@@ -24,7 +24,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /****************************************************************/
diff --git a/include/mbedtls/config_adjust_ssl.h b/include/mbedtls/config_adjust_ssl.h
index 8c824661f..309524a06 100644
--- a/include/mbedtls/config_adjust_ssl.h
+++ b/include/mbedtls/config_adjust_ssl.h
@@ -29,7 +29,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /* The following blocks make it easier to disable all of TLS,
diff --git a/include/mbedtls/config_adjust_x509.h b/include/mbedtls/config_adjust_x509.h
index 3c95ce404..c063251b0 100644
--- a/include/mbedtls/config_adjust_x509.h
+++ b/include/mbedtls/config_adjust_x509.h
@@ -29,7 +29,7 @@
     "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 time."
+    "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 59eb4f66c..3a2af1518 100644
--- a/include/psa/crypto_adjust_auto_enabled.h
+++ b/include/psa/crypto_adjust_auto_enabled.h
@@ -20,7 +20,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 #define PSA_WANT_KEY_TYPE_DERIVE 1
diff --git a/include/psa/crypto_adjust_config_dependencies.h b/include/psa/crypto_adjust_config_dependencies.h
index b63770fe9..92e9c4de2 100644
--- a/include/psa/crypto_adjust_config_dependencies.h
+++ b/include/psa/crypto_adjust_config_dependencies.h
@@ -23,7 +23,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 #if (defined(PSA_WANT_ALG_TLS12_PRF) && \
diff --git a/include/psa/crypto_adjust_config_key_pair_types.h b/include/psa/crypto_adjust_config_key_pair_types.h
index 76a965448..cec39e01c 100644
--- a/include/psa/crypto_adjust_config_key_pair_types.h
+++ b/include/psa/crypto_adjust_config_key_pair_types.h
@@ -26,7 +26,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /*****************************************************************
diff --git a/include/psa/crypto_adjust_config_synonyms.h b/include/psa/crypto_adjust_config_synonyms.h
index d92ca1150..54b116f43 100644
--- a/include/psa/crypto_adjust_config_synonyms.h
+++ b/include/psa/crypto_adjust_config_synonyms.h
@@ -21,7 +21,7 @@
     "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 time."
+    "automatically at the right point."
 #endif /* */
 
 /****************************************************************/

From c8d45cd3fc499b6f1a544ba8786678e6f597d30f Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Wed, 29 May 2024 09:34:20 +0200
Subject: [PATCH 8/8] Error on unexpectedly defined symbols

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
---
 include/mbedtls/build_info.h | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/include/mbedtls/build_info.h b/include/mbedtls/build_info.h
index e13e236d4..cf38f9098 100644
--- a/include/mbedtls/build_info.h
+++ b/include/mbedtls/build_info.h
@@ -101,8 +101,12 @@
 #define inline __inline
 #endif
 
-#undef MBEDTLS_CONFIG_FILES_READ
-#undef MBEDTLS_CONFIG_IS_FINALIZED
+#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)