Update PSA transition guide for TF-PSA-Crypto 1.0 #472
No reviewers
Labels
No labels
api-break
approved
bug
component-docs
component-platform
component-test
dependencies
deprecation
DO-NOT-MERGE
enhancement
good first issue
help wanted
needs-adoption
needs-backports
needs-ci
needs-design-approval
needs-info
needs-preceding-pr
needs-review
needs-reviewer
needs-work
priority-high
priority-low
priority-medium
priority-scheduled
priority-very-high
resolved-after-1.1
single-reviewer
size-l
size-m
size-optimisation
size-s
size-xs
No milestone
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
gh-Mbed-TLS/TF-PSA-Crypto!472
Loading…
Reference in a new issue
No description provided.
Delete branch "psa-transition-guide-20250630"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Update the PSA transition guide for TF-PSA-Crypto 1.0. There is not a lot to change, since we already had most of the pieces in place in 3.6. In this PR:
Note that links are still pointing to the 3.6 documentation, since we don't have TF-PSA-Crypto on readthedocs yet. For new functions, I linked to the source of the header file that describes it.
PR checklist
Currently the
pkg-configpackage to use PSA crypto ismbedcryptois that expected to change?I completed my first pass. I only reviewed what changed - so far I didn't check if other things should be changed as well.
@ -4,9 +4,7 @@Minor: "has replaced A to B" -> s/to/with/ I think?
@ -23,3 +21,3 @@**Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) is available online. Mbed TLS implements a large subset of the specification which is documented in the [`psa/crypto*.h` headers](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto_8h/).**Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) is available online. TF-PSA-Crypto implements a large subset of the specification which is documented in the [`psa/crypto*.h` headers](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto_8h/).Wrong thing copy-pasted in
[Mbed TLS issues](here).@ -41,24 +39,35 @@ Then use the [summary of API modules](#summary-of-api-modules), the table of con* Mbed TLS 2.15.0 (Nov 2018): first release with a draft implementation of the PSA API.Minor: the release will happen in October.
TODO
@ -204,7 +211,6 @@ For example, the following configuration enables hashing with SHA-256, AEAD with#define PSA_WANT_ALG_GCM 1Nice trick! A few commits ago I was starting to think we should provide some helper... well there it is :)
Minor: s/transition/migration/?
I believe we now pass a
mbedtls_pk_sigalg_type_tvalue.@ -1292,3 +1300,3 @@The PSA API does not provide direct access to the exponentiation primitive as with `mbedtls_rsa_public` and `mbedtls_rsa_private`. If you need an RSA-based mechanism that is not supported by the PSA API, please [submit an issue on GitHub](https://github.com/ARM-software/psa-api/issues) so that we can extend the API to support it.The PSA API does not support constructing RSA keys progressively from numbers with `mbedtls_rsa_import` or `mbedtls_rsa_import_raw` followed by `mbedtls_rsa_complete`. See “[Importing a PK key by wrapping](#importing-a-pk-key-by-wrapping)”.The PSA API does not support constructing RSA keys progressively from numbers, like the legacy functions `mbedtls_rsa_import`, `mbedtls_rsa_import_raw` and `mbedtls_rsa_complete`. You will need to construct the standard ASN.1 representation and call `psa_import_key()` (see “[Creating keys for asymmetric cryptography](#creating-keys-for-asymmetric-cryptography)”).Minor: s/transition/migration/ for consistency?
Sorry, I have no idea about that and this is not related to the document under review here. Please file a new issue, or maybe it's related to https://github.com/Mbed-TLS/mbedtls/issues/10395.
This looks essentially good to me. I have a couple of questions and have suggested some rewording where I felt it could improve comprehension.
@ -23,3 +21,3 @@**Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) is available online. Mbed TLS implements a large subset of the specification which is documented in the [`psa/crypto*.h` headers](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto_8h/).**Reference**: The [PSA Crypto API specification](https://arm-software.github.io/psa-api/crypto/) is available online. TF-PSA-Crypto implements a large subset of the specification which is documented in the [`psa/crypto*.h` headers](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/crypto_8h/).Comment not about this line but about line 22: "Mbed TLS implements a large subset ..." -> "TF-PSA-Crypto implements ..." ?
@ -41,24 +39,35 @@ Then use the [summary of API modules](#summary-of-api-modules), the table of con* Mbed TLS 2.15.0 (Nov 2018): first release with a draft implementation of the PSA API.I don’t really understand the meaning of the sentence “As an exception, it's safe to use the same content in the TF-PSA-Crypto configuration and in the Mbed TLS configuration.” Could you clarify?
I am not sure what you mean here.
@ -69,10 +78,14 @@ The PSA subsystem has an internal random generator. As a consequence, you do not"Most of the new APIs suggested in this document", you mean suggested as replacements for the legacy APIs?
@ -136,44 +148,37 @@ Note that a key consumes a key store entry, which is distinct from heap memory,| `md.h` | `mbedtls_md_` | [Hashes and MAC](#hashes-and-mac) |@ -204,7 +211,6 @@ For example, the following configuration enables hashing with SHA-256, AEAD with#define PSA_WANT_ALG_GCM 1Limited to 3.6? Should work with 3.x I'd say.
I think this is too much details for this document.
Why do we have less here? Because it is about the new legacy API?
@ -69,10 +78,14 @@ The PSA subsystem has an internal random generator. As a consequence, you do notI mean APIs that this document suggests that the reader uses, which indeed are replacements for legacy APIs since that's the purpose of the document. I'm not sure how else to formulate that.
Sorry, I don't understand why “for” would be better than “to” here.
@ -204,7 +211,6 @@ For example, the following configuration enables hashing with SHA-256, AEAD with#define PSA_WANT_ALG_GCM 1I would recommend 3.6 because we fixed some bugs over the course of 3.x. We can't prevent people from trying it with older 3.x, but I'd rather not recommend it.
Where else would you put it?
Yes.
mbedtls_pk_check_pairstill exists, but the RSA/ECP functions no longer do.I understand that we expect to add new PSA APIs to support DRBG mechanisms and in that context I would use "for" but I am not an English native speaker thus if you think they are equivalent here, that's fine by me.
It feels odd to provide users with a way to deal with the output of
query_compile_time_config, so I would just remove it. But if you prefer to keep that's fine by me.Perhaps keep the sed invocation (as a user, I think I'd appreciate being able to just copy-paste it), but also provide a description of what it does in plain English for the benefit of user of platforms without sed?
Good compromise, thanks.
LGTM, thanks.
LGTM!
Rebased again to try and pass the CI. No content change.
The rebase preserved GitHub approvals, so I'll go ahead and queue this for merging. There's a 3.6 backport, but it isn't release-critical, unlike this 1.0 PR.