From 6d81cbc81f1c0d045c3c84e1a59b9be37d1273bc Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 12 Feb 2024 16:25:19 +0100 Subject: [PATCH] Document new functions psa_generate_key_ext, psa_key_derivation_output_key_ext Document proposed additions to the PSA API: psa_generate_key_ext(), psa_key_derivation_output_key_ext(). For psa_generate_key_ext(), document the one use case we intend to implement immediately, which is generating an RSA key with a custom public exponent. Subsequent commits will implement the documented functionality. Signed-off-by: Gilles Peskine --- include/psa/crypto.h | 164 ++++++++++++++++++++++++++++++++++-- include/psa/crypto_struct.h | 23 +++++ include/psa/crypto_types.h | 24 ++++++ 3 files changed, 204 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index fe10ee0e44..d6ad969b89 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -119,8 +119,9 @@ static psa_key_attributes_t psa_key_attributes_init(void); * value in the structure. * The persistent key will be written to storage when the attribute * structure is passed to a key creation function such as - * psa_import_key(), psa_generate_key(), - * psa_key_derivation_output_key() or psa_copy_key(). + * psa_import_key(), psa_generate_key(), psa_generate_key_ext(), + * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext() + * or psa_copy_key(). * * This function may be declared as `static` (i.e. without external * linkage). This function may be provided as a function-like macro, @@ -163,8 +164,9 @@ static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes, * value in the structure. * The persistent key will be written to storage when the attribute * structure is passed to a key creation function such as - * psa_import_key(), psa_generate_key(), - * psa_key_derivation_output_key() or psa_copy_key(). + * psa_import_key(), psa_generate_key(), psa_generate_key_ext(), + * psa_key_derivation_output_key(), psa_key_derivation_output_key_ext() + * or psa_copy_key(). * * This function may be declared as `static` (i.e. without external * linkage). This function may be provided as a function-like macro, @@ -3226,7 +3228,8 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void); * psa_key_derivation_set_capacity(). You may do this before, in the middle * of or after providing inputs. For some algorithms, this step is mandatory * because the output depends on the maximum capacity. - * -# To derive a key, call psa_key_derivation_output_key(). + * -# To derive a key, call psa_key_derivation_output_key() or + * psa_key_derivation_output_key_ext(). * To derive a byte string for a different purpose, call * psa_key_derivation_output_bytes(). * Successive calls to these functions use successive output bytes @@ -3449,7 +3452,8 @@ psa_status_t psa_key_derivation_input_integer( * \note Once all inputs steps are completed, the operations will allow: * - psa_key_derivation_output_bytes() if each input was either a direct input * or a key with #PSA_KEY_USAGE_DERIVE set; - * - psa_key_derivation_output_key() if the input for step + * - psa_key_derivation_output_key() or psa_key_derivation_output_key_ext() + * if the input for step * #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD * was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was * either a direct input or a key with #PSA_KEY_USAGE_DERIVE set; @@ -3697,6 +3701,12 @@ psa_status_t psa_key_derivation_output_bytes( * Future versions of this specification may include additional restrictions * on the derived key based on the attributes and strength of the secret key. * + * \note This function is equivalent to calling + * psa_key_derivation_output_key_ext() + * with the method #PSA_KEY_GENERATION_METHOD_INIT and + * `method_length == sizeof(psa_key_generation_method_t)` + * (i.e. `method->flags == 0` and `method->data` is empty). + * * \param[in] attributes The attributes for the new key. * If the key type to be created is * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in @@ -3750,6 +3760,83 @@ 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. + * + * 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. + * + * \note This function is experimental and may change in future minor + * versions of Mbed TLS. + * + * \param[in] attributes The attributes for the new key. + * If the key type to be created is + * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in + * 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 generation. + * When this is #PSA_KEY_GENERATION_METHOD_INIT + * with \p method_length = + * `sizeof(psa_key_generation_method_t)`, + * 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, + * for all key types. + * \param method_length Length of \p method in bytes. + * This must be + * `sizeof(psa_key_generation_method_t) + n` + * where `n` is the size of `method->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. + * \c 0 on failure. + * + * \retval #PSA_SUCCESS + * Success. + * If the key is persistent, the key material and the key's metadata + * have been saved to persistent storage. + * \retval #PSA_ERROR_ALREADY_EXISTS + * This is an attempt to create a persistent key, and there is + * already a persistent key with the given identifier. + * \retval #PSA_ERROR_INSUFFICIENT_DATA + * There was not enough data to create the desired key. + * Note that in this case, no output is written to the output buffer. + * The operation's capacity is set to 0, thus subsequent calls to + * this function will not succeed, even with a smaller output buffer. + * \retval #PSA_ERROR_NOT_SUPPORTED + * The key type or key size is not supported, either by the + * implementation in general or in this particular location. + * \retval #PSA_ERROR_INVALID_ARGUMENT + * The provided key attributes are not valid for the operation. + * \retval #PSA_ERROR_NOT_PERMITTED + * The #PSA_KEY_DERIVATION_INPUT_SECRET or + * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a + * key; or one of the inputs was a key whose policy didn't allow + * #PSA_KEY_USAGE_DERIVE. + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_BAD_STATE + * The operation state is not valid (it must be active and completed + * all required input steps), or the library has not been previously + * initialized by psa_crypto_init(). + * It is implementation-dependent whether a failure to initialize + * results in this error code. + */ +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_length, + mbedtls_svc_key_id_t *key); + /** Compare output data from a key derivation operation to an expected value. * * This function calculates output bytes from a key derivation algorithm and @@ -3835,7 +3922,8 @@ psa_status_t psa_key_derivation_verify_bytes( * and the permitted algorithm must match the * operation. The value of this key was likely * computed by a previous call to - * psa_key_derivation_output_key(). + * psa_key_derivation_output_key() or + * psa_key_derivation_output_key_ext(). * * \retval #PSA_SUCCESS \emptydescription * \retval #PSA_ERROR_INVALID_SIGNATURE @@ -4003,6 +4091,11 @@ psa_status_t psa_generate_random(uint8_t *output, * between 2^{n-1} and 2^n where n is the bit size specified in the * attributes. * + * \note This function is equivalent to calling psa_generate_key_ext() + * with the method #PSA_KEY_GENERATION_METHOD_INIT and + * `method_length == sizeof(psa_key_generation_method_t)` + * (i.e. `method->flags == 0` and `method->data` is empty). + * * \param[in] attributes The attributes for the new key. * \param[out] key On success, an identifier for the newly created * key. For persistent keys, this is the key @@ -4035,6 +4128,63 @@ psa_status_t psa_generate_random(uint8_t *output, 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. + * + * 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: + * + * - RSA keys: generation with a custom public exponent. + * + * \note This function is experimental and may change in future minor + * 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_length = + * `sizeof(psa_key_generation_method_t)`, + * this function is equivalent to + * psa_key_derivation_output_key(). + * \param method_length Length of \p method in bytes. + * This must be + * `sizeof(psa_key_generation_method_t) + n` + * where `n` is the size of `method->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. + * \c 0 on failure. + * + * \retval #PSA_SUCCESS + * Success. + * If the key is persistent, the key material and the key's metadata + * have been saved to persistent storage. + * \retval #PSA_ERROR_ALREADY_EXISTS + * This is an attempt to create a persistent key, and there is + * already a persistent key with the given identifier. + * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_BAD_STATE + * The library has not been previously initialized by psa_crypto_init(). + * It is implementation-dependent whether a failure to initialize + * 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_length, + mbedtls_svc_key_id_t *key); + /**@}*/ /** \defgroup interruptible_hash Interruptible sign/verify hash diff --git a/include/psa/crypto_struct.h b/include/psa/crypto_struct.h index 34d072ba8e..b5e942e6c1 100644 --- a/include/psa/crypto_struct.h +++ b/include/psa/crypto_struct.h @@ -223,6 +223,29 @@ static inline struct psa_key_derivation_s psa_key_derivation_operation_init( return v; } +struct psa_key_generation_method_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. + * + * Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext() + * with `method=PSA_KEY_GENERATION_METHOD_INIT` and + * `method_length=sizeof(psa_key_generation_method_t)` is equivalent to + * calling psa_generate_key() or psa_key_derivation_output_key() + * respectively. + */ +#define PSA_KEY_GENERATION_METHOD_INIT { 0 } + +static inline struct psa_key_generation_method_s psa_key_generation_method_init( + void) +{ + const struct psa_key_generation_method_s v = PSA_KEY_GENERATION_METHOD_INIT; + return v; +} + struct psa_key_policy_s { psa_key_usage_t MBEDTLS_PRIVATE(usage); psa_algorithm_t MBEDTLS_PRIVATE(alg); diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index e2ebd8af35..35a3bdb0ec 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -455,6 +455,30 @@ typedef uint64_t psa_key_slot_number_t; */ typedef uint16_t psa_key_derivation_step_t; +/** \brief Custom method for key generation or key derivation. + * + * This is a structure type with at least the following fields: + * + * - \c flags: an unsigned integer type. 0 for the default method. + * - \c data: a flexible array of bytes. + * + * The interpretation of this structure depend on the type of the + * created key. + * + * - #PSA_KEY_TYPE_RSA_KEY_PAIR: + * - \c flags: must be 0. + * - \c data: the public exponent, in little-endian order. + * This must be an odd integer and must not be 1. + * Implementations must support 65535, should support 3 and may + * support other values. + * When not using a driver, Mbed TLS supports values up to \c INT_MAX. + * If this is empty or if the custom method is omitted altogether, + * the default value 65537 is used. + * - Other key types: reserved for future use. \c flags must be 0. + * + */ +typedef struct psa_key_generation_method_s psa_key_generation_method_t; + /**@}*/ #endif /* PSA_CRYPTO_TYPES_H */