Rename "key generation method" to "key production parameters"
"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>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0878836..18c783c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3703,8 +3703,8 @@
*
* \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_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 @@
* 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_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 @@
* 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 @@
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 @@
* 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 @@
* 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);
/**@}*/
diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h
index f41bc83..e2068e8 100644
--- a/include/psa/crypto_struct.h
+++ b/include/psa/crypto_struct.h
@@ -223,21 +223,21 @@
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);
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 35a3bdb..c509807 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -477,7 +477,7 @@
* - 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;
/**@}*/
diff --git a/library/psa_crypto.c b/library/psa_crypto.c
index d84d101..4df3dc5 100644
--- a/library/psa_crypto.c
+++ b/library/psa_crypto.c
@@ -6023,16 +6023,17 @@
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 @@
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 @@
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 @@
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 @@
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 @@
* 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 *) ¶ms->data;
}
return mbedtls_psa_rsa_generate_key(&override_attributes,
key_buffer,
@@ -7569,8 +7570,8 @@
}
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 @@
#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 @@
}
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 @@
mbedtls_svc_key_id_t *key)
{
return psa_generate_key_ext(attributes,
- &default_method, 0,
+ &default_production_parameters, 0,
key);
}
diff --git a/library/psa_crypto_core.h b/library/psa_crypto_core.h
index 965db94..6db533c 100644
--- a/library/psa_crypto_core.h
+++ b/library/psa_crypto_core.h
@@ -396,17 +396,17 @@
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 @@
* 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 @@
* 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);
diff --git a/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja b/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
index 10843c3..4f9764d 100644
--- a/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
+++ b/scripts/data_files/driver_templates/psa_crypto_driver_wrappers.h.jinja
@@ -731,7 +731,7 @@
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 @@
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 @@
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 @@
/* 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;
diff --git a/tests/suites/test_suite_psa_crypto.data b/tests/suites/test_suite_psa_crypto.data
index e29e466..8139469 100644
--- a/tests/suites/test_suite_psa_crypto.data
+++ b/tests/suites/test_suite_psa_crypto.data
@@ -7550,8 +7550,8 @@
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
diff --git a/tests/suites/test_suite_psa_crypto.function b/tests/suites/test_suite_psa_crypto.function
index 6cd1e93..b40b5f8 100644
--- a/tests/suites/test_suite_psa_crypto.function
+++ b/tests/suites/test_suite_psa_crypto.function
@@ -1309,26 +1309,25 @@
}
#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 @@
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 @@
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 @@
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(¶ms, ¶ms_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 @@
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 @@
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 @@
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 @@
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(¶ms, ¶ms_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 @@
#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 @@
* 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);