Simplify platform interfaces

[gilles-peskine-arm]

The portability layer in Mbed TLS is complex. The goal of this issue is to simplify it. This will require a major redesign that can only be done in a major release (I don't think it's possible to get anywhere without API changes).

As of Mbed TLS 3.x, the portability layer consists of:

• The ability to substitute some standard C functions such as printf and calloc for which Mbed TLS goes through wrappers mbedtls_xxx. This is done by defining MBEDTLS_PLATFORM_xxx symbols in the configuration, plus other steps if necessary: including additional headers, linking with additional libraries, assigning to function pointers in an initialization function. For some of those mbedtls_xxx symbols, the configuration is done by making it a macro that expands to some different name (or, in principle, more generally, any C expression that evaluates to a function pointer). For other mbedtls_xxx symbols, the configuration is done by providing a function pointer which may be changeable at runtime. For some of the mbedtls_xxx symbols, both mechanisms are available. This can get quite complicated; the worst is calloc/free customization (and that documentation doesn't even document all the edge cases).

• Functionality that's only implemented on Unix-like systems (sometimes only some of those) and on Windows. On other systems, you have to disable the built-in mechanisms or replace a library module with your own. This includes:

  • The net_sockets module, which implements the input-output interface that the TLS stack talks with. On non-supported systems, you have to pass your own functions to mbedtls_ssl_set_bio.
  • Obtaining entropy from the system in entropy_poll.c. On non-supported systems, you have to enable MBEDTLS_NO_PLATFORM_ENTROPY (to disable the internal interface that lacks an implementation) and MBEDTLS_HARDWARE_POLL (to provide your own implementation).
  • The timing module, which is only used in sample programs and test code. Those sample/test programs can only be built on supported systems.
  • The storage layer for PSA persistent keys, which can be either an implementation of the PSA ITS interface or MBEDTLS_PSA_ITS_FILE_C.

• Interfaces to cryptographic engines, which come in several flavors:

  • Compile-time substitution with ALT interfaces — scheduled for removal in 4.0.
  • Runtime dispatch with ALT (RSA only) — scheduled for removal in 4.0.
  • Ad hoc compilation options for AESNI, AESCE and VIA Padlock.
  • PSA drivers — the mechanism we want to use going forward.
  • Ad hoc PSA functions that are meant to replace things for which there isn't a proper driver interface yet: MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS, MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.

I think cryptographic engines and platform configuration are different beasts, and we already have a plan for cryptographic engines, which is PSA drivers. So this issue is about the platform interfaces that aren't related to cryptography.

Ideally, it should be possible to integrate Mbed TLS into an embedded OS by providing a custom my_platform.h and my_platform.o, which implement all the features Mbed TLS needs that are related to the OS: malloc, printf, sockets, filesystem, etc. We would provide versions of these files for Unix-like systems and for Windows, and embedded OS/BSP maintainers can write versions for their platform.

[gilles-peskine-arm]

Example of why we need this: #8490 — User confusion and errors in the documentation because MBEDTLS_PLATFORM_ZEROIZE_ALT doesn't behave like the others — most MBEDTLS_PLATFORM_xxx_ALT macros are the name of a function to use instead of the default, but MBEDTLS_PLATFORM_ZEROIZE_ALT is instead a boolean that says not to link the default function, so that users have to provide their own with the standard name.

[mschulz-at-hilscher]

Would it be possible to call the C11 Annex K bounds checking interface of standard libary functions as required by https://wiki.sei.cmu.edu/confluence/display/c/STR07-C.+Use+the+bounds-checking+interfaces+for+string+manipulation?

[gilles-peskine-arm]

@mschulz-at-hilscher Most platforms don't have Annex K functions, so they aren't an option for us.

In any case, we prefer to rely on static analysis over runtime detection: it's safer (if we do static analysis right, which could definitely be improved), and less code size.