From 6044f3e4449c66ffc5ca09e889a900602b4d4e34 Mon Sep 17 00:00:00 2001 From: Paul Elliott Date: Thu, 18 Jul 2024 21:30:36 +0100 Subject: [PATCH] Add psa_generate_key_iop_setup() documentation Signed-off-by: Paul Elliott --- tf-psa-crypto/core/psa_crypto_ecp.c | 11 +++ tf-psa-crypto/include/psa/crypto.h | 112 ++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) diff --git a/tf-psa-crypto/core/psa_crypto_ecp.c b/tf-psa-crypto/core/psa_crypto_ecp.c index 7f3a2b6496..16c394683b 100644 --- a/tf-psa-crypto/core/psa_crypto_ecp.c +++ b/tf-psa-crypto/core/psa_crypto_ecp.c @@ -603,6 +603,16 @@ uint32_t psa_generate_key_iop_get_num_ops( return 0; } +psa_status_t psa_generate_key_iop_setup( + psa_generate_key_iop_t *operation, + const psa_key_attributes_t *attributes) +{ + (void) operation; + (void) attributes; + + return PSA_SUCCESS; +} + /****************************************************************/ /* Interruptible ECC Key Agreement */ /****************************************************************/ @@ -649,4 +659,5 @@ psa_status_t psa_key_agreement_iop_abort( return PSA_SUCCESS; } + #endif /* MBEDTLS_PSA_CRYPTO_C */ diff --git a/tf-psa-crypto/include/psa/crypto.h b/tf-psa-crypto/include/psa/crypto.h index ac466da663..71ac2e9895 100644 --- a/tf-psa-crypto/include/psa/crypto.h +++ b/tf-psa-crypto/include/psa/crypto.h @@ -5231,6 +5231,118 @@ typedef struct psa_generate_key_iop_s psa_generate_key_iop_t; */ uint32_t psa_generate_key_iop_get_num_ops(psa_generate_key_iop_t *operation); +/** + * \brief Start a key generation operation, in an + * interruptible manner. + * + * \see \c psa_generate_key_iop_complete() + * + * \warning This is a beta API, and thus subject to change + * at any point. It is not bound by the usual + * interface stability promises. + * + * \note This function combined with \c + * psa_generate_key_iop_complete() is equivalent + * to \c psa_generate_key() but \c + * psa_generate_key_iop_complete() can return + * early and resume according to the limit set with + * \c psa_interruptible_set_max_ops() to reduce the + * maximum time spent in a function. + * + * \note Users should call + * \c psa_generate_key_iop_complete() repeatedly + * on the same operation object after a successful + * call to this function until \c + * psa_generate_key_iop_complete() either returns + * #PSA_SUCCESS or an error. + * \c psa_generate_key_iop_complete() will return + * #PSA_OPERATION_INCOMPLETE if there is more work + * to do. Alternatively users can call + * \c psa_generate_key_iop_abort() at any point + * if they no longer want the result. + * + * \note This function clears the number of ops completed + * as part of the operation. Please ensure you copy + * this value via + * \c psa_generate_key_iop_get_num_ops() if + * required before calling. + * + * \note If this function returns an error status, the + * operation enters an error state and must be + * aborted by calling \c + * psa_generate_key_iop_abort(). + * + * \param[in, out] operation The \c psa_generate_key_iop_t to use. + * This must be initialized as per the + * documentation for + * \c psa_generate_key_iop_t, and be inactive. + + * \param[in] attributes The attributes for the new key. + * The following attributes are required for all + * keys: + * * The key type. It must not be an asymmetric + * public key. + * * The key size. It must be a valid size for the + * key type. + * The following attributes must be set for keys + * used in cryptographic operations: + * * The key permitted-algorithm policy. + * * The key usage flags. + * The following attributes must be set for keys + * that do not use the default volatile lifetime: + * * The key lifetime. + * * The key identifier is required for a key with + * a persistent lifetime, + * + * \note \p attributes is an input parameter, it is not + * updated with the final key attributes. The final + * attributes of the new key can be queried by + * calling `psa_get_key_attributes()` with + * the key's identifier. + * + * \retval #PSA_SUCCESS + * The operation started successfully. + * Call \c psa_generate_key_iop_complete() with the same context to + * complete the operation. + * + * \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 + * The key attributes, as a whole, are not supported, either in general + * or in the specified storage location. + * \retval PSA_ERROR_INVALID_ARGUMENT + * The following conditions can result in this error: + * * The key type is invalid, or is an asymmetric public key type. + * * The key size is not valid for the key type. + * * The key lifetime is invalid. + * * The key identifier is not valid for the key lifetime. + * * The key usage flags include invalid values. + * * The key's permitted-usage algorithm is invalid. + * * The key attributes, as a whole, are invalid. + * \retval PSA_ERROR_NOT_PERMITTED + * Creating a key with the specified attributes is not permitted. + * + * \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription + * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription + * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription + * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription + * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription + * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription + * \retval #PSA_ERROR_DATA_INVALID \emptydescription + * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription + * \retval #PSA_ERROR_BAD_STATE + * The following conditions can result in this error: + * * The library has not been previously initialized by + * \c psa_crypto_init(). + * * The operation state is not valid: it must be inactive. + */ + +psa_status_t psa_generate_key_iop_setup( + psa_generate_key_iop_t *operation, + const psa_key_attributes_t *attributes); + /**@}*/ #ifdef __cplusplus