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>
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