Add extended key creation functions for non-default production methods
This change has been adopted from Mbed TLS: https://github.com/Mbed-TLS/mbedtls/pull/8815, with changes to make it compatible with C++ compilation.
- Add extended key generation and derivation functions,
psa_generate_key_ext()andpsa_key_derivation_output_key_ext(), that accept additional parameters to control the key creation process. - Define a key production parameter to select a non-default exponent for RSA key generation.
Notes:
- The alternative key generation method is described with the relevant key type (RSA), instead of where the production parameter structure type is defined (the approach in the Mbed TLS change).
Fixes #167
For now - marked this as a draft PR. Some rework of the API is required.
It turns out that the variable-sized structure definition is not strictly legal in C++, and inclusion and use from C++ is an expected use case for the Crypto API.
Updated in line with the proposal in https://github.com/ARM-software/psa-api/issues/167#issuecomment-2104602992.
This is force-pushed to remove the uneccessary changes to the buffer parameter conventions. The changes between the earlier API in the PR are visible in the single commit https://github.com/ARM-software/psa-api/pull/194/commits/db30ef60edd97497d0766ad789dac5ee2af72c08.
To support migration for applications using the beta version of this API in Mbed TLS, we need to consider if we can use a different function name for these new APIs.
Some ideas (including considered and discarded ones) for alternative function names:
-
psa_generate_key_extended()orpsa_generate_key_extra()- unabbreviated versions ofpsa_generate_key_ext(), but this neither follows a recognised pattern of using_ext()in other APIs, nor inform the reader what the extended call adds to the original function. -
psa_generate_key_custom()orpsa_generate_custom_key()(the latter reads better, but a list of function names is less well ordered) - reflecting the customisation/parameterisation provided by the extra parameters. -
psa_generate_key_parameterized()orpsa_generate_parameterized_key()(the latter reads better, and also sorts immediately after the original function) - a bit longer, but better reflecting parameterisation provided by the extra parameters. -
psa_generate_key_with_parameters()- literally does what it says, but is this a too close to writing prose as a function name?
Rejected ideas
-
psa_generate_key_new()- never a good idea to call an API 'new'. One day it won't be new anymore. -
psa_generate_key_2()- this is a second 'generate key' function (or is it the third afterpsa_generate_key_ext()?), but that does not inform a reader/developer what makes it different. -
psa_generate_key5()- prefix the overloaded versions with the number of parameters. A pattern used elsewhere. However, the function name does not help the reader understand what is different, and the extended key derivation function would have a6suffix, which does not create the obvious association between the two APIs.
Rebased to sync with main.