From 993c2492426ab49a0644afa2e38cfe52dab6a504 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 13 Nov 2020 22:45:13 +0100 Subject: [PATCH] Add a section explaining the uses of PSA_WANT_xxx PSA_WANT_xxx is useful regardless of how the symbols are defined: explicitly (with MBEDTLS_PSA_CRYPTO_CONFIG) or implicitly (without MBEDTLS_PSA_CRYPTO_CONFIG). Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 1f4fef3e9..383bf5f00 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/05 09:50:28 GMT" +Time-stamp: "2020/11/13 21:45:08 GMT" ## Introduction @@ -68,6 +68,14 @@ A PSA crypto configuration symbol is a C preprocessor symbol whose name starts w * If the symbol is defined to a preprocessor expression with the value `1`, the corresponding feature is included. * If the symbol is defined with a different value, the behavior is currently undefined and reserved for future use. +#### Configuration symbol usage + +The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptogrraphic mechanism, including: + +* In Mbed TLS test code. +* In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable. +* In application code that provides additional features based on crypto capabilities, for example additional key parsing and formatting functions, or cipher suite availability for network protocols. + #### Configuration symbol semantics If a feature is not requested for inclusion in the PSA crypto configuration file, it may still be included in the build, either because the feature has been requested in some other way, or because the library does not support the exclusion of this feature. Mbed TLS should make a best effort to support the exclusion of all features, but in some cases this may be judged too much effort for too little benefit.