diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index b9e12bb6f3..2d03f73118 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -2,6 +2,11 @@
  * \file psa/crypto_extra.h
  *
  * \brief PSA cryptography module: Mbed TLS vendor extensions
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
+ * This file is reserved for vendor-specific definitions.
  */
 /*
  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
diff --git a/include/psa/crypto_platform.h b/include/psa/crypto_platform.h
index 7aabd1bc07..9af320d1e9 100644
--- a/include/psa/crypto_platform.h
+++ b/include/psa/crypto_platform.h
@@ -2,6 +2,16 @@
  * \file psa/crypto_platform.h
  *
  * \brief PSA cryptography module: Mbed TLS platfom definitions
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
+ * This file contains platform-dependent type definitions.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, implementers should take care to ensure that
+ * the definitions that are exposed to applications match what the
+ * module implements.
  */
 /*
  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index f4d2cd8399..80b2f9d621 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -3,12 +3,20 @@
  *
  * \brief PSA cryptography module: Mbed TLS buffer size macros
  *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
  * This file contains the definitions of macros that are useful to
  * compute buffer sizes. The signatures and semantics of these macros
  * are standardized, but the definitions are not, because they depend on
  * the available algorithms and, in some cases, on permitted tolerances
  * on buffer sizes.
  *
+ * In implementations with isolation between the application and the
+ * cryptography module, implementers should take care to ensure that
+ * the definitions that are exposed to applications match what the
+ * module implements.
+ *
  * Macros that compute sizes whose values do not depend on the
  * implementation are in crypto.h.
  */
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index 1935f90994..b981f23c75 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -2,6 +2,16 @@
  * \file psa/crypto_struct.h
  *
  * \brief PSA cryptography module: Mbed TLS structured type implementations
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
+ * This file contains the definitions of some data structures with
+ * implementation-specific definitions.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, it is expected that the front-end and the back-end
+ * would have different versions of this file.
  */
 /*
  *  Copyright (C) 2018, ARM Limited, All Rights Reserved