Document compilation guards for stacks

[gilles-peskine-arm]

As a developer of Mbed TLS, I want to know which dependencies to put on test cases so that my tests compile in all desired configurations.

For example:

• Can I parse an RSA key with mbedtls_pk_parse_key?
• Can I use mbedtls_pk_sign with MBEDTLS_PK_ECDSA and MBEDTLS_MD_SHA256?
• Is SHA-384 supported as the TLS 1.2 PRF algorithm?

This used to be simple: look up the required functions or features (algorithms, TLS extensions, …) in mbedtls_config.h (formerly config.h). Then we added the PSA API, whose mechanisms are gated by symbols in include/psa/crypto_config.h. Still simple. But over the course of Mbed TLS 3.x, through the “driver-only” work, we have grown dual support for two crypto stacks, with two configuration mechanisms. So the question “how do I tell whether algorithm A is supported through function F?” can sometimes be hard to answer. The relevant macros may be defined in include/*/*adjust*.h or various include/mbedtls/*.h.

The goal of this issue is to document macros such as MBEDTLS_MD_CAN_SHA256, MBEDTLS_ECP_LIGHT, MBEDTLS_PK_HAVE_ECC_KEYS, MBEDTLS_PK_USE_PSA_EC_DATA, MBEDTLS_PK_CAN_ECDSA_VERIFY, etc. in a way that makes it reasonably easy to go from the intended meaning to the correct macro. Most of the macros are documented where they're defined, but if you don't already know the macro name, that doesn't really help.

This documentation is primarily intended for Mbed TLS maintainers. It would also be useful for maintainers of third-party code that needs to be compatible with all or most Mbed TLS configurations. This documentation is relevant for Mbed TLS 3.x, not 2.28 (no “driver-only” so you just check for legacy algorithms) nor 4.x (no non-PSA configurations so you just check PSA_WANT).