mbedtls
mbedtls copied to clipboard
Mbed-TLS
Document the need to call psa_crypto_init for TLS 1.3
It isn't obvious that you need to call psa_crypto_init() in application code before starting a TLS 1.3 handshake, so document it.
Also document this on common functions for when MBEDTLS_USE_PSA_CRYPTO is enabled. (It's already mentioned in the documentation for MBEDTLS_USE_PSA_CRYPTO itself, but users who're writing the application code and didn't write the configuration might not think of looking there.) I do not try to be exhaustive, just the common non-obvious cases (basically anything that calls PK parsing, and SSL handshake setup).
Could we also make sure that if the user fails to call psa_crypto_init then the error code returned is one that, when they look it up, will tell them that they should have called psa_crypto_init?
It looks like psa_ssl_status_to_mbedtls currently converts PSA_ERROR_BAD_STATE to MBEDTLS_ERR_SSL_INTERNAL_ERROR, which would perhaps make sense if it were the Mbed TLS's code's responsibility to call psa_crypto_init, but even in that case a more specific error code would be helpful.
Could we also make sure that if the user fails to call psa_crypto_init then the error code returned is one that, when they look it up, will tell them that they should have called psa_crypto_init?
Sounds difficult. PSA_CRYPTO_BAD_STATE indicates a coding error somewhere. In this specific case it's in the application code, but in most cases, when TLS code is calling PSA crypto, if PSA crypto returns BAD_STATE, it would be because the TLS code has done something wrong.
For TLS, I suppose we could have mbedtls_ssl_setup do a specific check and return a new error code.
Anyway I'm not going to do that in this PR, which is only documentation. So please file a new issue if you really want this.
Rebased to handle a conflict with #6283 which partly tackled the same topic, but mostly made complementary changes.
It would be nice to have a backport for relevant parts, unless you prefer otherwise.
2.28 is very different: TLS 1.3 doesn't use PSA, and pk with USE_PSA_CRYPTO only uses PSA for ECDSA verification. So I'll make a conceptual backport, but it'll share almost no code. There's no particular reason to synchronize it with this PR (since it's just documentation), so I'm going ahead and merging, and I'll make an independent 2.28 PR.
The kind-of-backport is up: https://github.com/Mbed-TLS/mbedtls/pull/7223