From e0ec8f5348717d33bcef5bb745ba301b9128daee 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 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.

From 06972c6ae46f459ffecfec2410c1fa56f1905929 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 0000000000..86723e0907
--- /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 a4e97fc954867781b880b1a0602b6fccf3df9d19 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 eab167f383..e13e236d45 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 66b2742a6cac0c7bf3796c0b2cd3cde258bbb6a8 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 a24616a5a0..1d1b29ec55 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 f5334f1574..c8e4d03a4d 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 7c3a2d2359..3495f67bf6 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 6ccb91becd..0cbad256ac 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 4d8dc9dfac..8c824661f7 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 d12f4d82bc..3c95ce4047 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 e2618d15dc..59eb4f66c3 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 5a22205bf3..b63770fe99 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 8308ac759e..76a9654487 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 ad71050ef2..d92ca1150b 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 f948e2fa52397c90c52dc1706b63df08aab6f0c8 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 9c33faeb9a..67a05f83b8 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 99cb19ad00874b726d1ed19ef4b2767a6c5583b3 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 86723e0907..8570a11757 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 d53779995f91aaab1c9c457f4cd9f629ce0d9295 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 1d1b29ec55..854116190e 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 c8e4d03a4d..04bdae61bb 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 3495f67bf6..14ca14696f 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 0cbad256ac..ef65cce0d9 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 8c824661f7..309524a06a 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 3c95ce4047..c063251b0f 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 59eb4f66c3..3a2af15180 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 b63770fe99..92e9c4de28 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 76a9654487..cec39e01ce 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 d92ca1150b..54b116f434 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 bd61fdfd6b8cc679c6ada980e85580a497b82e3b 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 e13e236d45..cf38f90981 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)