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;
/**@}*/