lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-08-07 06:42:56 +03:00
Code Activity

Merge pull request #8815 from gilles-peskine-arm/psa_generate_key_ext-prototype

Browse Source 
Introduce psa_generate_key_ext
This commit is contained in:
Gilles Peskine
2024-02-26 07:16:49 +00:00
committed by GitHub
parent 665cf928d9 23605d19d9
commit 0f63028809
10 changed files with 649 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
include/psa/crypto.h
View File

@@ -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,11 @@ 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 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
* #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in
@@ -3750,6 +3759,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 custom
* production parameters.
*
* See the description of psa_key_derivation_out_key() for the operation of
* 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.
*
* \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] 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
* production parameters, i.e.
* #PSA_KEY_PRODUCTION_PARAMETERS_INIT,
* for all key types.
* \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.
* \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_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.
*
* This function calculates output bytes from a key derivation algorithm and
@@ -3835,7 +3921,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 +4090,10 @@ 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 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
* key. For persistent keys, this is the key
@@ -4035,6 +4126,60 @@ 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 custom production parameters.
*
* See the description of psa_generate_key() for the operation of this
* 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.
*
* \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] 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 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.
* \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_production_parameters_t *params,
size_t params_data_length,
mbedtls_svc_key_id_t *key);
/**@}*/
/** \defgroup interruptible_hash Interruptible sign/verify hash

16
include/psa/crypto_struct.h
View File

@@ -223,6 +223,22 @@ static inline struct psa_key_derivation_s psa_key_derivation_operation_init(
return v;
}
struct psa_key_production_parameters_s {
/* Future versions may add other fields in this structure. */
uint32_t flags;
uint8_t data[];
};
/** The default production parameters for key generation or key derivation.
*
* Calling psa_generate_key_ext() or psa_key_derivation_output_key_ext()
* 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_PRODUCTION_PARAMETERS_INIT { 0 }
struct psa_key_policy_s {
psa_key_usage_t MBEDTLS_PRIVATE(usage);
psa_algorithm_t MBEDTLS_PRIVATE(alg);

24
include/psa/crypto_types.h
View File

@@ -455,6 +455,30 @@ typedef uint64_t psa_key_slot_number_t;
*/
typedef uint16_t psa_key_derivation_step_t;
/** \brief Custom parameters 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 production parameters.
* - \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 production parameters are omitted
* altogether, the default value 65537 is used.
* - Other key types: reserved for future use. \c flags must be 0.
*
*/
typedef struct psa_key_production_parameters_s psa_key_production_parameters_t;
/**@}*/
#endif /* PSA_CRYPTO_TYPES_H */