mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-03-04 13:13:31 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Document new functions psa_generate_key_ext, psa_key_derivation_output_key_ext

Browse Source 
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 <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2024-02-12 16:25:19 +01:00
parent 3ea9450463
commit 6d81cbc81f
3 changed files with 204 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
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,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

23
include/psa/crypto_struct.h
View File

@ -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);

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 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 */