From b1176f2583407bb80838f8760e0824eae50cc0fb Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 22 Feb 2023 22:07:28 +0100 Subject: [PATCH] Allow alternative names for overridden PSA headers Integrators of Mbed TLS may override the header files "psa/crypto_platform.h" and "psa/crypto_struct.h" by overwriting the files or by placing alternative versions earlier in the include file search path. These two methods are sometimes inconvenient, so allow a third method which doesn't require overwriting files or having a precise order for the include path: integrators can now specify alternative names for the headers. Signed-off-by: Gilles Peskine --- ChangeLog.d/psa-alt-headers.txt | 4 +++ include/mbedtls/mbedtls_config.h | 47 ++++++++++++++++++++++++++++++++ include/psa/crypto.h | 8 ++++++ include/psa/crypto_types.h | 4 +++ 4 files changed, 63 insertions(+) create mode 100644 ChangeLog.d/psa-alt-headers.txt diff --git a/ChangeLog.d/psa-alt-headers.txt b/ChangeLog.d/psa-alt-headers.txt new file mode 100644 index 0000000000..95556290a5 --- /dev/null +++ b/ChangeLog.d/psa-alt-headers.txt @@ -0,0 +1,4 @@ +Features + * The configuration macros MBEDTLS_PSA_CRYPTO_PLATFORM_FILE and + MBEDTLS_PSA_CRYPTO_STRUCT_FILE specify alternative locations for + the headers "psa/crypto_platform.h" and "psa/crypto_struct.h". diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 9ae51c964a..f596417ffa 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -3537,6 +3537,53 @@ */ //#define MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE "/dev/null" +/** + * \def MBEDTLS_PSA_CRYPTO_PLATFORM_FILE + * + * If defined, this is a header which will be included instead of + * `"psa/crypto_platform.h"`. This file should declare the same identifiers + * as the one in Mbed TLS, but with definitions adapted to the platform on + * which the library code will run. + * + * \note The required content of this header can vary from one version of + * Mbed TLS to the next. Integrators who provide an alternative file + * should review the changes in the original file whenever they + * upgrade Mbed TLS. + * + * This macro is expanded after an \#include directive. This is a popular but + * non-standard feature of the C language, so this feature is only available + * with compilers that perform macro expansion on an \#include line. + * + * The value of this symbol is typically a path in double quotes, either + * absolute or relative to a directory on the include search path. + */ +//#define MBEDTLS_PSA_CRYPTO_PLATFORM_FILE "psa/crypto_platform_alt.h" + +/** + * \def MBEDTLS_PSA_CRYPTO_STRUCT_FILE + * + * If defined, this is a header which will be included instead of + * `"psa/crypto_struct.h"`. This file should declare the same identifiers + * as the one in Mbed TLS, but with definitions adapted to the environment + * in which the library code will run. The typical use for this feature + * is to provide alternative type definitions on the client side in + * client-server integrations of PSA crypto, where operation structures + * contain handles instead of cryptographic data. + * + * \note The required content of this header can vary from one version of + * Mbed TLS to the next. Integrators who provide an alternative file + * should review the changes in the original file whenever they + * upgrade Mbed TLS. + * + * This macro is expanded after an \#include directive. This is a popular but + * non-standard feature of the C language, so this feature is only available + * with compilers that perform macro expansion on an \#include line. + * + * The value of this symbol is typically a path in double quotes, either + * absolute or relative to a directory on the include search path. + */ +//#define MBEDTLS_PSA_CRYPTO_STRUCT_FILE "psa/crypto_struct_alt.h" + /** \} name SECTION: General configuration options */ /** diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 80bf5c9690..bd544224d4 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -22,7 +22,11 @@ #ifndef PSA_CRYPTO_H #define PSA_CRYPTO_H +#if defined(MBEDTLS_PSA_CRYPTO_PLATFORM_FILE) +#include MBEDTLS_PSA_CRYPTO_PLATFORM_FILE +#else #include "crypto_platform.h" +#endif #include @@ -4677,7 +4681,11 @@ psa_status_t psa_verify_hash_abort( /* The file "crypto_struct.h" contains definitions for * implementation-specific structs that are declared above. */ +#if defined(MBEDTLS_PSA_CRYPTO_STRUCT_FILE) +#include MBEDTLS_PSA_CRYPTO_STRUCT_FILE +#else #include "crypto_struct.h" +#endif /* The file "crypto_extra.h" contains vendor-specific definitions. This * can include vendor-defined algorithms, extra functions, etc. */ diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index 95bf32fd98..dd4d4fca3d 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -34,7 +34,11 @@ #define PSA_CRYPTO_TYPES_H #include "mbedtls/private_access.h" +#if defined(MBEDTLS_PSA_CRYPTO_PLATFORM_FILE) +#include MBEDTLS_PSA_CRYPTO_PLATFORM_FILE +#else #include "crypto_platform.h" +#endif /* If MBEDTLS_PSA_CRYPTO_C is defined, make sure MBEDTLS_PSA_CRYPTO_CLIENT * is defined as well to include all PSA code.