Remove discussions of MBEDTLS_USE_PSA_CRYPTO in API documentation #9781
Conversation
MBEDTLS_USE_PSA_CRYPTO is now always enabled we need to update the documentation accordingly. Signed-off-by: Janos Follath <[email protected]>
MBEDTLS_USE_PSA_CRYPTO is now always enabled we need to update the documentation accordingly. Signed-off-by: Janos Follath <[email protected]>
MBEDTLS_USE_PSA_CRYPTO is now always enabled we need to update the documentation accordingly. Signed-off-by: Janos Follath <[email protected]>
MBEDTLS_USE_PSA_CRYPTO is now always enabled we need to update the documentation accordingly. Signed-off-by: Janos Follath <[email protected]>
yanesca
added
enhancement
needs-review
There was a problem hiding this comment.
This mostly looks good, and I'm satisfied with completeness for the subtask “API documentation”. There are a few problems in mbedtls_config.h. There are conflicts with #9771, so it would be better to wait until that is merged for rework and re-review.
| * - p256-m is only available via the PSA API. This includes the pk module | ||
| * when #MBEDTLS_USE_PSA_CRYPTO is enabled. | ||
| * - p256-m is only available via the PSA API. This includes the pk module. |
There was a problem hiding this comment.
Partly preexisting: the readme says that these files are “taken verbatim”. But we seem to be now partially adapting the files to 4.0.
There was a problem hiding this comment.
As discussed in Slack, we do need to change this file, so please update the readme to say that this is currently not a verbatim copy, but a preview of how TFM should be adapted for 4.0.
| * \note When this option is enabled, restartable operations in PK, X.509 | ||
| * and TLS (see above) are not using PSA. On the other hand, ECDH | ||
| * computations in TLS are using PSA, and are not restartable. These | ||
| * are temporary limitations that should be lifted in the future. |
There was a problem hiding this comment.
Minor: there is only one limitation now.
| * \note When this option is enabled, restartable operations in PK, X.509 | ||
| * and TLS (see above) are not using PSA. On the other hand, ECDH | ||
| * computations in TLS are using PSA, and are not restartable. These | ||
| * are temporary limitations that should be lifted in the future. |
There was a problem hiding this comment.
Partly preexisting: “should be lifted in the future” should have a link to an issue. That gives a way for users to track progress and express interest. We didn't seem to have an issue yet, so I've filed one: #9784.
| * \warning If building with MBEDTLS_USE_PSA_CRYPTO, or if the hash(es) used | ||
| * are only provided by PSA drivers, you must call psa_crypto_init() before | ||
| * doing any TLS operations. | ||
| * \warning You must call psa_crypto_init() before doing any TLS operations. |
There was a problem hiding this comment.
Given that this now applies to all protocol versions, shouldn't we move this note to MBEDTLS_SSL_CLI_C and MBEDTLS_SSL_SRV_C? (Or just MBEDTLS_SSL_TLS_C, but that option should go away and just be implied by CLI || SRV.)
| @@ -1644,7 +1622,7 @@ | |||
| * Requires: PSA_WANT_ALG_ECDH or PSA_WANT_ALG_FFDH | |||
| * MBEDTLS_X509_CRT_PARSE_C | |||
| * and at least one of: | |||
| * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) | |||
| * MBEDTLS_ECDSA_C or PSA_WANT_ALG_ECDSA | |||
There was a problem hiding this comment.
With the removal of non-PSA-config that's happening in parallel, MBEDTLS_ECDSA_C is becoming irrelevant.
| @@ -853,8 +850,8 @@ | |||
| * | |||
| * Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS. | |||
| * | |||
| * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) | |||
| * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) | |||
| * Requires: MBEDTLS_ECDH_C or PSA_WANT_ALG_ECDH | |||
There was a problem hiding this comment.
Partly preexisting (in many places in this file): this isn't quite right, and it wasn't right in 3.6 either. When MBEDTLS_USE_PSA_CRYPTO is enabled and MBEDTLS_PSA_CRYPTO_CONFIG is enabled (i.e. the only thing that will remain in 4.0), defining MBEDTLS_ECDH_C does not automatically enable ECDH in PSA, so here the requirement is on PSA_WANT_ALG_ECDH only.
In 3.6, this would be correct, although not necessarily the most helpful way to put it:
(!MBEDTLS_USE_PSA_CRYPTO and MBEDTLS_ECDH_C) or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH)
It's not the most helpful way because if MBEDTLS_PSA_CRYPTO_CONFIG is disabled, which is the case by default, then enabling MBEDTLS_ECDH_C works regardless of MBEDTLS_USE_PSA_CRYPTO.
In some cases where there's a direct correspondence between legacy and PSA mechanisms, we have a rule that the PSA mechanism will always be enabled if the legacy mechanism is (unless PSA is completely disabled). This is done in config_adjust_psa_superset_legacy.h. But we only do this for hashes and curves, not for things like ECC/RSA algorithms.
Given that the removal of MBEDTLS_PSA_CRYPTO_CONFIG is happening in parallel (https://github.com/Mbed-TLS/mbedtls/pull/9771/files#r1848889790), I think it would be best to not try to get those statements exactly right on either side, because then we'd have a lot of conflicts. Rather, I propose to file a task to fix these requirement statements once both #9781 and #9771 are merged.
gilles-peskine-arm
added
needs-work
needs-preceding-pr
Description
Remove discussions of MBEDTLS_USE_PSA_CRYPTO in API documentation. Resolves partially #9632.
Conflicts with #9771.
PR checklist
Please remove the segment/s on either side of the | symbol as appropriate, and add any relevant link/s to the end of the line.
If the provided content is part of the present PR remove the # symbol.