Hello,
The API of Mbed TLS is what is documented at https://mbed-tls.readthedocs.io/projects/api/en/v3.6.0/
(or whatever version you're using). Undocumented symbols are not
part of the API, even if they leak because C doesn't enforce many
abstraction boundaries.
In practice, there there are a few symbols (mostly macros and enum
constants) that aren't documented, but are evidently necessary to
use certain documented functions. You can consider them to be part
of the API. I consider the omission of necessary symbols in the
documentation to be documentation bugs, please feel free to report
them as such on our GitHub.
Any function that is not documented in a public header, is just an
internal function which may change or disappear without notice. The
internal functions are not made private and have no name mangling
because doing these things is toolchain-specific, and we don't have
any linker-specific code in our builds scripts. This is not a matter
of principle, it's just that we've never spent the time to do this
linker-specific work (which would have to work without breaking the
build on other toolchains).
Regarding MPI functions specifically, only the “classic” MPI layer
in mbedtls/mpi.h is a public API. The other layers are for internal
use only and we do not intend to expose them as a stable API.
(Mainly because we want to be able to change those functions when we
do security updates to improve side channel resistance in asymmetric
crypto.)
Best regards,
--
Gilles Peskine
Mbed TLS developer
On 26/04/2024 15:37, Zaki, Ahmed via
mbed-tls wrote:
Hi, I am trying
to identify the API available by looking up exported symbols from the built shared libraries libmbedcrypto.so ,libmbedtls.so and libmbedx509.so. I noticed that many of the exported functions are not documented here
https://mbed-tls.readthedocs.io/projects/api/en/development/
. My question really is, are those functions exported through the shared libraries intended to be so ? For example, function mbedtls_mpi_core_add does not seem to be part of the API but it is exported. Is this intentional ? It's not uncommon that functions
would be exported but not part of the API, I just wanted to get some clarification if possible regarding the reasons for doing so in the case of MbedTLS. Thanks Ahmed