psa-api icon indicating copy to clipboard operation
psa-api copied to clipboard

Add extended key creation functions for non-default production methods

Open athoelke opened this issue 1 year ago • 5 comments

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() and psa_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

athoelke avatar Mar 28 '24 16:03 athoelke

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.

athoelke avatar Apr 09 '24 09:04 athoelke

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.

athoelke avatar May 10 '24 15:05 athoelke

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.

athoelke avatar May 14 '24 10:05 athoelke

Some ideas (including considered and discarded ones) for alternative function names:

  • psa_generate_key_extended() or psa_generate_key_extra() - unabbreviated versions of psa_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() or psa_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() or psa_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 after psa_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 a 6 suffix, which does not create the obvious association between the two APIs.

athoelke avatar May 14 '24 13:05 athoelke

Rebased to sync with main.

athoelke avatar Jul 30 '24 16:07 athoelke