From 9fe1c699a8a73a528878f3072c5ee127a3928f84 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 2 Jan 2024 13:16:31 +0100 Subject: [PATCH] Clarify PSA-to-PK copy intent Signed-off-by: Gilles Peskine --- docs/architecture/psa-migration/psa-legacy-bridges.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/architecture/psa-migration/psa-legacy-bridges.md b/docs/architecture/psa-migration/psa-legacy-bridges.md index 0c3e05a650..064b7d2788 100644 --- a/docs/architecture/psa-migration/psa-legacy-bridges.md +++ b/docs/architecture/psa-migration/psa-legacy-bridges.md @@ -290,9 +290,10 @@ int mbedtls_pk_copy_from_psa(mbedtls_svc_key_id_t key_id, * `pk` must be initialized, but not set up. * It is an error if the key is neither a key pair nor a public key. * It is an error if the key is not exportable. -* The resulting pk object has a transparent type, not `MBEDTLS_PK_OPAQUE`. +* The resulting pk object has a transparent type, not `MBEDTLS_PK_OPAQUE`. That's `MBEDTLS_PK_RSA` for RSA keys (since pk objects don't use `MBEDTLS_PK_RSASSA_PSS)` as a type, and `MBEDTLS_PK_ECKEY` for ECC keys (following the example of pkparse). * Once this function returns, the pk object is completely independent of the PSA key. * Calling `mbedtls_pk_sign`, `mbedtls_pk_verify`, `mbedtls_pk_encrypt`, `mbedtls_pk_decrypt` on the resulting pk context will perform an algorithm that is compatible with the PSA key's primary algorithm policy (`psa_get_key_algorithm`), but with no restriction on the hash (as if the policy had `PSA_ALG_ANY_HASH` instead of a specific hash, and with `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` merged with `PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)`). For ECDSA, the choice of deterministic vs randomized will be based on the compile-time setting `MBEDTLS_ECDSA_DETERMINISTIC`, like `mbedtls_pk_sign` today. + * The primary intent of this requirement is to allow an application to switch to PSA for creating the key material (for example to benefit from a PSA accelerator driver, or to start using a secure element), without modifying the code that consumes the key. For RSA keys, the PSA primary algorithm policy is how one conveys the same information as RSA key padding information in the legacy API. [ACTION] Convey this in the documentation. * [OPEN] How do we distinguish between signature-only and encryption-only RSA keys? Do we just allow both (e.g. a PSS key gets generalized into a PSS/OAEP key)? * [OPEN] What about `mbedtls_pk_sign_ext` and `mbedtls_pk_verify_ext`?