yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Rename "key generation method" to "key production parameters"

Browse source 
"Key generation method" was misleading since it also applies to key
derivation. Change "key generation" to "key production", which we aren't
using yet and has roughly the right intuition. Change "method" to
"parameters" which there seems to be a slight preference for. Discussion
thread: https://github.com/Mbed-TLS/mbedtls/pull/8815#discussion_r1486524295

Identifiers renamed:
psa_key_generation_method_t → psa_key_production_parameters_t
psa_key_generation_method_s → psa_key_production_parameters_s
PSA_KEY_GENERATION_METHOD_INIT → PSA_KEY_PRODUCTION_PARAMETERS_INIT
method → params
method_data_length → params_data_length
default_method → default_production_parameters
psa_key_generation_method_is_default → psa_key_production_parameters_are_default
setup_key_generation_method → setup_key_production_parameters
key_generation_method_init → key_production_parameters_init

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2024-02-20 12:31:24 +01:00
parent e7a7013910
commit 092ce51c47
8 changed files with 113 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
include/psa/crypto.h
View file

@ -3703,8 +3703,8 @@ psa_status_t psa_key_derivation_output_bytes(
*
* \note This function is equivalent to calling
* psa_key_derivation_output_key_ext()
* with the method #PSA_KEY_GENERATION_METHOD_INIT and
* `method_data_length == 0` (i.e. `method->data` is empty).
* with the production parameters #PSA_KEY_PRODUCTION_PARAMETERS_INIT
* and `params_data_length == 0` (i.e. `params->data` is empty).
*
* \param[in] attributes The attributes for the new key.
* If the key type to be created is
@ -3759,11 +3759,13 @@ psa_status_t psa_key_derivation_output_key(
psa_key_derivation_operation_t *operation,
mbedtls_svc_key_id_t *key);
/** Derive a key from an ongoing key derivation operation with a custom method.
/** Derive a key from an ongoing key derivation operation with custom
* production parameters.
*
* See the description of psa_key_derivation_out_key() for the operation of
* this function with the default method.
* Mbed TLS currently does not currently support any non-default methods.
* this function with the default production parameters.
* Mbed TLS currently does not currently support any non-default production
* parameters.
*
* \note This function is experimental and may change in future minor
* versions of Mbed TLS.
@ -3774,16 +3776,16 @@ psa_status_t psa_key_derivation_output_key(
* the policy must be the same as in the current
* operation.
* \param[in,out] operation The key derivation operation object to read from.
* \param[in] method Customization parameters for the key derivation.
* When this is #PSA_KEY_GENERATION_METHOD_INIT
* with \p method_data_length = 0,
* \param[in] params Customization parameters for the key derivation.
* When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT
* with \p params_data_length = 0,
* this function is equivalent to
* psa_key_derivation_output_key().
* Mbed TLS currently only supports the default
* method, i.e. #PSA_KEY_GENERATION_METHOD_INIT,
* method, i.e. #PSA_KEY_PRODUCTION_PARAMETERS_INIT,
* for all key types.
* \param method_data_length
* Length of `method.data` in bytes.
* \param params_data_length
* Length of `params->data` in bytes.
* \param[out] key On success, an identifier for the newly created
* key. For persistent keys, this is the key
* identifier defined in \p attributes.
@ -3829,8 +3831,8 @@ psa_status_t psa_key_derivation_output_key(
psa_status_t psa_key_derivation_output_key_ext(
const psa_key_attributes_t *attributes,
psa_key_derivation_operation_t *operation,
const psa_key_generation_method_t *method,
size_t method_data_length,
const psa_key_production_parameters_t *params,
size_t params_data_length,
mbedtls_svc_key_id_t *key);
/** Compare output data from a key derivation operation to an expected value.
@ -4088,8 +4090,8 @@ psa_status_t psa_generate_random(uint8_t *output,
* attributes.
*
* \note This function is equivalent to calling psa_generate_key_ext()
* with the method #PSA_KEY_GENERATION_METHOD_INIT and
* `method_data_length == 0` (i.e. `method->data` is empty).
* with the production parameters #PSA_KEY_PRODUCTION_PARAMETERS_INIT
* and `params_data_length == 0` (i.e. `params->data` is empty).
*
* \param[in] attributes The attributes for the new key.
* \param[out] key On success, an identifier for the newly created
@ -4124,12 +4126,12 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
mbedtls_svc_key_id_t *key);
/**
* \brief Generate a key or key pair using a custom method.
* \brief Generate a key or key pair using custom production parameters.
*
* See the description of psa_generate_key() for the operation of this
* function with the default method. In addition, this function supports
* the following non-default methods, described in more detail in the
* documentation of ::psa_key_generation_method_t:
* function with the default production parameters. In addition, this function
* supports the following production customizations, described in more detail
* in the documentation of ::psa_key_production_parameters_t:
*
* - RSA keys: generation with a custom public exponent.
*
@ -4137,13 +4139,13 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
* versions of Mbed TLS.
*
* \param[in] attributes The attributes for the new key.
* \param[in] method Customization parameters for the key generation.
* When this is #PSA_KEY_GENERATION_METHOD_INIT
* with \p method_data_length = 0,
* \param[in] params Customization parameters for the key generation.
* When this is #PSA_KEY_PRODUCTION_PARAMETERS_INIT
* with \p params_data_length = 0,
* this function is equivalent to
* psa_key_generation_output_key().
* \param method_data_length
* Length of `method.data` in bytes.
* \param params_data_length
* Length of `params->data` in bytes.
* \param[out] key On success, an identifier for the newly created
* key. For persistent keys, this is the key
* identifier defined in \p attributes.
@ -4173,8 +4175,8 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
* results in this error code.
*/
psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes,
const psa_key_generation_method_t *method,
size_t method_data_length,
const psa_key_production_parameters_t *params,
size_t params_data_length,
mbedtls_svc_key_id_t *key);
/**@}*/

10
include/psa/crypto_struct.h
View file

@ -223,21 +223,21 @@ static inline struct psa_key_derivation_s psa_key_derivation_operation_init(
return v;
}
struct psa_key_generation_method_s {
struct psa_key_production_parameters_s {
/* Future versions may add other fields in this structure. */
uint32_t flags;
uint8_t data[];
};
/** The default method for key generation or key derivation.
/** The default production parameters for key generation or key derivation.
*
* Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext()
* with `method=PSA_KEY_GENERATION_METHOD_INIT` and
* `method_data_length == 0` is equivalent to
* with `params=PSA_KEY_PRODUCTION_PARAMETERS_INIT` and
* `params_data_length == 0` is equivalent to
* calling psa_generate_key() or psa_key_derivation_output_key()
* respectively.
*/
#define PSA_KEY_GENERATION_METHOD_INIT { 0 }
#define PSA_KEY_PRODUCTION_PARAMETERS_INIT { 0 }
struct psa_key_policy_s {
psa_key_usage_t MBEDTLS_PRIVATE(usage);

2
include/psa/crypto_types.h
View file

@ -477,7 +477,7 @@ typedef uint16_t psa_key_derivation_step_t;
* - Other key types: reserved for future use. \c flags must be 0.
*
*/
typedef struct psa_key_generation_method_s psa_key_generation_method_t;
typedef struct psa_key_production_parameters_s psa_key_production_parameters_t;
/**@}*/

45
library/psa_crypto.c
View file

@ -6023,16 +6023,17 @@ exit:
return status;
}
static const psa_key_generation_method_t default_method = PSA_KEY_GENERATION_METHOD_INIT;
static const psa_key_production_parameters_t default_production_parameters =
PSA_KEY_PRODUCTION_PARAMETERS_INIT;
int psa_key_generation_method_is_default(
const psa_key_generation_method_t *method,
size_t method_data_length)
int psa_key_production_parameters_are_default(
const psa_key_production_parameters_t *params,
size_t params_data_length)
{
if (method->flags != 0) {
if (params->flags != 0) {
return 0;
}
if (method_data_length != 0) {
if (params_data_length != 0) {
return 0;
}
return 1;
@ -6041,8 +6042,8 @@ int psa_key_generation_method_is_default(
psa_status_t psa_key_derivation_output_key_ext(
const psa_key_attributes_t *attributes,
psa_key_derivation_operation_t *operation,
const psa_key_generation_method_t *method,
size_t method_data_length,
const psa_key_production_parameters_t *params,
size_t params_data_length,
mbedtls_svc_key_id_t *key)
{
psa_status_t status;
@ -6057,7 +6058,7 @@ psa_status_t psa_key_derivation_output_key_ext(
return PSA_ERROR_INVALID_ARGUMENT;
}
if (!psa_key_generation_method_is_default(method, method_data_length)) {
if (!psa_key_production_parameters_are_default(params, params_data_length)) {
return PSA_ERROR_INVALID_ARGUMENT;
}
@ -6098,7 +6099,7 @@ psa_status_t psa_key_derivation_output_key(
mbedtls_svc_key_id_t *key)
{
return psa_key_derivation_output_key_ext(attributes, operation,
&default_method, 0,
&default_production_parameters, 0,
key);
}
@ -7497,15 +7498,15 @@ static psa_status_t psa_validate_key_type_and_size_for_key_generation(
psa_status_t psa_generate_key_internal(
const psa_key_attributes_t *attributes,
const psa_key_generation_method_t *method, size_t method_data_length,
const psa_key_production_parameters_t *params, size_t params_data_length,
uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length)
{
psa_status_t status = PSA_ERROR_CORRUPTION_DETECTED;
psa_key_type_t type = attributes->core.type;
/* Only used for RSA */
(void) method;
(void) method_data_length;
(void) params;
(void) params_data_length;
if ((attributes->domain_parameters == NULL) &&
(attributes->domain_parameters_size != 0)) {
@ -7532,9 +7533,9 @@ psa_status_t psa_generate_key_internal(
* that mbedtls_psa_rsa_generate_key() gets e via a new
* parameter instead. */
psa_key_attributes_t override_attributes = *attributes;
if (method_data_length != 0) {
override_attributes.domain_parameters_size = method_data_length;
override_attributes.domain_parameters = (uint8_t *) &method->data;
if (params_data_length != 0) {
override_attributes.domain_parameters_size = params_data_length;
override_attributes.domain_parameters = (uint8_t *) &params->data;
}
return mbedtls_psa_rsa_generate_key(&override_attributes,
key_buffer,
@ -7569,8 +7570,8 @@ psa_status_t psa_generate_key_internal(
}
psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes,
const psa_key_generation_method_t *method,
size_t method_data_length,
const psa_key_production_parameters_t *params,
size_t params_data_length,
mbedtls_svc_key_id_t *key)
{
psa_status_t status;
@ -7593,12 +7594,12 @@ psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes,
#if defined(PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_GENERATE)
if (attributes->core.type == PSA_KEY_TYPE_RSA_KEY_PAIR) {
if (method->flags != 0) {
if (params->flags != 0) {
return PSA_ERROR_INVALID_ARGUMENT;
}
} else
#endif
if (!psa_key_generation_method_is_default(method, method_data_length)) {
if (!psa_key_production_parameters_are_default(params, params_data_length)) {
return PSA_ERROR_INVALID_ARGUMENT;
}
@ -7639,7 +7640,7 @@ psa_status_t psa_generate_key_ext(const psa_key_attributes_t *attributes,
}
status = psa_driver_wrapper_generate_key(attributes,
method, method_data_length,
params, params_data_length,
slot->key.data, slot->key.bytes,
&slot->key.bytes);
if (status != PSA_SUCCESS) {
@ -7661,7 +7662,7 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
mbedtls_svc_key_id_t *key)
{
return psa_generate_key_ext(attributes,
&default_method, 0,
&default_production_parameters, 0,
key);
}

24
library/psa_crypto_core.h
View file

@ -396,17 +396,17 @@ psa_status_t psa_export_public_key_internal(
const uint8_t *key_buffer, size_t key_buffer_size,
uint8_t *data, size_t data_size, size_t *data_length);
/** Whether a key generation method is the default.
/** Whether a key production parameters structure is the default.
*
* Calls to a key generation driver with a non-default method
* require a driver supporting custom methods.
* Calls to a key generation driver with non-default production parameters
* require a driver supporting custom production parameters.
*
* \param[in] method The key generation method to check.
* \param method_data_length Size of `method.data` in bytes.
* \param[in] params The key production parameters to check.
* \param params_data_length Size of `params->data` in bytes.
*/
int psa_key_generation_method_is_default(
const psa_key_generation_method_t *method,
size_t method_data_length);
int psa_key_production_parameters_are_default(
const psa_key_production_parameters_t *params,
size_t params_data_length);
/**
* \brief Generate a key.
@ -415,9 +415,9 @@ int psa_key_generation_method_is_default(
* entry point.
*
* \param[in] attributes The attributes for the key to generate.
* \param[in] method The generation method from
* \param[in] params The production parameters from
* psa_generate_key_ext().
* \param method_data_length The size of `method.data` in bytes.
* \param params_data_length The size of `params->data` in bytes.
* \param[out] key_buffer Buffer where the key data is to be written.
* \param[in] key_buffer_size Size of \p key_buffer in bytes.
* \param[out] key_buffer_length On success, the number of bytes written in
@ -432,8 +432,8 @@ int psa_key_generation_method_is_default(
* The size of \p key_buffer is too small.
*/
psa_status_t psa_generate_key_internal(const psa_key_attributes_t *attributes,
const psa_key_generation_method_t *method,
size_t method_data_length,
const psa_key_production_parameters_t *params,
size_t params_data_length,
uint8_t *key_buffer,
size_t key_buffer_size,
size_t *key_buffer_length);

22
scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
View file

@ -731,7 +731,7 @@ static inline psa_status_t psa_driver_wrapper_get_key_buffer_size_from_key_data(
static inline psa_status_t psa_driver_wrapper_generate_key(
const psa_key_attributes_t *attributes,
const psa_key_generation_method_t *method, size_t method_data_length,
const psa_key_production_parameters_t *params, size_t params_data_length,
uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length )
{
psa_status_t status = PSA_ERROR_CORRUPTION_DETECTED;
@ -739,16 +739,17 @@ static inline psa_status_t psa_driver_wrapper_generate_key(
PSA_KEY_LIFETIME_GET_LOCATION(attributes->core.lifetime);
#if defined(PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_GENERATE)
int is_default_method =
psa_key_generation_method_is_default(method, method_data_length);
if( location != PSA_KEY_LOCATION_LOCAL_STORAGE && !is_default_method )
int is_default_production =
psa_key_production_parameters_are_default(params, params_data_length);
if( location != PSA_KEY_LOCATION_LOCAL_STORAGE && !is_default_production )
{
/* We don't support passing a custom method to drivers yet. */
/* We don't support passing custom production parameters
* to drivers yet. */
return PSA_ERROR_NOT_SUPPORTED;
}
#else
int is_default_method = 1;
(void) is_default_method;
int is_default_production = 1;
(void) is_default_production;
#endif
/* Try dynamically-registered SE interface first */
@ -777,9 +778,10 @@ static inline psa_status_t psa_driver_wrapper_generate_key(
case PSA_KEY_LOCATION_LOCAL_STORAGE:
#if defined(PSA_CRYPTO_ACCELERATOR_DRIVER_PRESENT)
/* Transparent drivers are limited to generating asymmetric keys. */
/* We don't support passing a custom method to drivers yet. */
/* We don't support passing custom production parameters
* to drivers yet. */
if( PSA_KEY_TYPE_IS_ASYMMETRIC( attributes->core.type ) &&
is_default_method )
is_default_production )
{
/* Cycle through all known transparent accelerators */
#if defined(PSA_CRYPTO_DRIVER_TEST)
@ -809,7 +811,7 @@ static inline psa_status_t psa_driver_wrapper_generate_key(
/* Software fallback */
status = psa_generate_key_internal(
attributes, method, method_data_length,
attributes, params, params_data_length,
key_buffer, key_buffer_size, key_buffer_length );
break;

4
tests/suites/test_suite_psa_crypto.data
View file

@ -7550,8 +7550,8 @@ PSA generate key ext: ECC, method.data non-empty
depends_on:PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE:PSA_WANT_ECC_SECP_R1_256:PSA_WANT_ALG_ECDH
generate_key_ext:PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1):256:PSA_KEY_USAGE_DERIVE:PSA_ALG_ECDH:0:"2a":PSA_ERROR_INVALID_ARGUMENT
Key generation method initializers
key_generation_method_init:
Key production parameters initializers
key_production_parameters_init:
PSA import persistent key: raw data, 8 bits
depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C

61
tests/suites/test_suite_psa_crypto.function
View file

@ -1309,26 +1309,25 @@ exit:
}
#endif /* PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_GENERATE */
static int setup_key_generation_method(psa_key_generation_method_t **method,
size_t *method_data_length,
int flags_arg,
const data_t *method_data)
static int setup_key_production_parameters(
psa_key_production_parameters_t **params, size_t *params_data_length,
int flags_arg, const data_t *params_data)
{
*method_data_length = method_data->len;
*params_data_length = params_data->len;
/* If there are N bytes of padding at the end of
* psa_key_generation_method_t, then it's enough to allocate
* MIN(sizeof(psa_key_generation_method_t),
* offsetof(psa_key_generation_method_t, data) + method_data_length).
* psa_key_production_parameters_t, then it's enough to allocate
* MIN(sizeof(psa_key_production_parameters_t),
* offsetof(psa_key_production_parameters_t, data) + params_data_length).
*
* For simplicity, here, we allocate up to N more bytes than necessary.
* In practice, the current layout of psa_key_generation_method_t
* In practice, the current layout of psa_key_production_parameters_t
* makes padding extremely unlikely, so we don't worry about testing
* that the library code doesn't try to access these extra N bytes.
*/
*method = mbedtls_calloc(1, sizeof(**method) + *method_data_length);
TEST_ASSERT(*method != NULL);
(*method)->flags = (uint32_t) flags_arg;
memcpy((*method)->data, method_data->x, method_data->len);
*params = mbedtls_calloc(1, sizeof(**params) + *params_data_length);
TEST_ASSERT(*params != NULL);
(*params)->flags = (uint32_t) flags_arg;
memcpy((*params)->data, params_data->x, params_data->len);
return 1;
exit:
return 0;
@ -9340,7 +9339,7 @@ void derive_key_ext(int alg_arg,
data_t *input2,
int key_type_arg, int bits_arg,
int flags_arg,
data_t *method_data,
data_t *params_data,
psa_status_t expected_status,
data_t *expected_export)
{
@ -9349,8 +9348,8 @@ void derive_key_ext(int alg_arg,
const psa_algorithm_t alg = alg_arg;
const psa_key_type_t key_type = key_type_arg;
const size_t bits = bits_arg;
psa_key_generation_method_t *method = NULL;
size_t method_data_length = 0;
psa_key_production_parameters_t *params = NULL;
size_t params_data_length = 0;
psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
const size_t export_buffer_size =
PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, bits);
@ -9380,13 +9379,13 @@ void derive_key_ext(int alg_arg,
psa_set_key_algorithm(&derived_attributes, 0);
psa_set_key_type(&derived_attributes, key_type);
psa_set_key_bits(&derived_attributes, bits);
if (!setup_key_generation_method(&method, &method_data_length,
flags_arg, method_data)) {
if (!setup_key_production_parameters(&params, &params_data_length,
flags_arg, params_data)) {
goto exit;
}
TEST_EQUAL(psa_key_derivation_output_key_ext(&derived_attributes, &operation,
method, method_data_length,
params, params_data_length,
&derived_key),
expected_status);
@ -9400,7 +9399,7 @@ void derive_key_ext(int alg_arg,
exit:
mbedtls_free(export_buffer);
mbedtls_free(method);
mbedtls_free(params);
psa_key_derivation_abort(&operation);
psa_destroy_key(base_key);
psa_destroy_key(derived_key);
@ -9929,7 +9928,7 @@ void generate_key_ext(int type_arg,
int usage_arg,
int alg_arg,
int flags_arg,
data_t *method_data,
data_t *params_data,
int expected_status_arg)
{
mbedtls_svc_key_id_t key = MBEDTLS_SVC_KEY_ID_INIT;
@ -9939,8 +9938,8 @@ void generate_key_ext(int type_arg,
psa_algorithm_t alg = alg_arg;
psa_status_t expected_status = expected_status_arg;
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_key_generation_method_t *method = NULL;
size_t method_data_length = 0;
psa_key_production_parameters_t *params = NULL;
size_t params_data_length = 0;
psa_key_attributes_t got_attributes = PSA_KEY_ATTRIBUTES_INIT;
PSA_ASSERT(psa_crypto_init());
@ -9950,14 +9949,14 @@ void generate_key_ext(int type_arg,
psa_set_key_type(&attributes, type);
psa_set_key_bits(&attributes, bits);
if (!setup_key_generation_method(&method, &method_data_length,
flags_arg, method_data)) {
if (!setup_key_production_parameters(&params, &params_data_length,
flags_arg, params_data)) {
goto exit;
}
/* Generate a key */
psa_status_t status = psa_generate_key_ext(&attributes,
method, method_data_length,
params, params_data_length,
&key);
TEST_EQUAL(status, expected_status);
@ -9972,7 +9971,7 @@ void generate_key_ext(int type_arg,
#if defined(PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_GENERATE)
if (type == PSA_KEY_TYPE_RSA_KEY_PAIR) {
TEST_ASSERT(rsa_test_e(key, bits, method_data));
TEST_ASSERT(rsa_test_e(key, bits, params_data));
}
#endif
@ -9987,17 +9986,17 @@ exit:
* thus reset them as required.
*/
psa_reset_key_attributes(&got_attributes);
mbedtls_free(method);
mbedtls_free(params);
psa_destroy_key(key);
PSA_DONE();
}
/* END_CASE */
/* BEGIN_CASE */
void key_generation_method_init()
void key_production_parameters_init()
{
psa_key_generation_method_t init = PSA_KEY_GENERATION_METHOD_INIT;
psa_key_generation_method_t zero;
psa_key_production_parameters_t init = PSA_KEY_PRODUCTION_PARAMETERS_INIT;
psa_key_production_parameters_t zero;
memset(&zero, 0, sizeof(zero));
TEST_EQUAL(init.flags, 0);