From 2dc58fe717f40c0a7f83fda3dfec0f965d79cde4 Mon Sep 17 00:00:00 2001 From: Paul Elliott Date: Thu, 18 Jul 2024 21:30:36 +0100 Subject: [PATCH] Add psa_key_agreement_iop_setup() documentation Signed-off-by: Paul Elliott --- tf-psa-crypto/core/psa_crypto_ecp.c | 18 ++++ tf-psa-crypto/include/psa/crypto.h | 158 ++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+) diff --git a/tf-psa-crypto/core/psa_crypto_ecp.c b/tf-psa-crypto/core/psa_crypto_ecp.c index 9e98cc1296..ce119e258f 100644 --- a/tf-psa-crypto/core/psa_crypto_ecp.c +++ b/tf-psa-crypto/core/psa_crypto_ecp.c @@ -603,4 +603,22 @@ uint32_t psa_key_agreement_iop_get_num_ops( return 0; } +psa_status_t psa_key_agreement_iop_setup( + psa_key_agreement_iop_t *operation, + psa_key_id_t private_key, + const uint8_t *peer_key, + size_t peer_key_length, + psa_algorithm_t alg, + const psa_key_attributes_t *attributes) +{ + (void) operation; + (void) private_key; + (void) peer_key; + (void) peer_key_length; + (void) alg; + (void) attributes; + + 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 75ea8fe7fe..c43f674c63 100644 --- a/tf-psa-crypto/include/psa/crypto.h +++ b/tf-psa-crypto/include/psa/crypto.h @@ -4877,6 +4877,164 @@ typedef struct psa_key_agreement_iop_s psa_key_agreement_iop_t; */ uint32_t psa_key_agreement_iop_get_num_ops(psa_key_agreement_iop_t *operation); +/** + * \brief Start a key agreement operation, in an + * interruptible manner. + * + * \see \c psa_key_agreement_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_key_agreement_iop_complete() is equivalent + * to \c psa_key_agreement() but \c + * psa_key_agreement_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_key_agreement_iop_complete() repeatedly + * on the same operation object after a successful + * call to this function until \c + * psa_key_agreement_iop_complete() either returns + * 0 or an error. + * \c psa_key_agreement_iop_complete() will return + * #PSA_OPERATION_INCOMPLETE if there is more work + * to do. Alternatively users can call + * \c psa_key_agreement_iop_abort() at any point + * if they no longer want the result. + * + * \note If this function returns an error status, the + * operation enters an error state and must be + * aborted by calling \c + * psa_key_agreement_iop_abort(). + * + * \param[in, out] operation The \c psa_key_agreement_iop_t to use. This must + * be initialized as per the documentation for + * \c psa_key_agreement_iop_t, and be inactive. + + * \param private_key Identifier of the private key to use. It must + * allow the usage #PSA_KEY_USAGE_DERIVE. + * \param[in] peer_key Public key of the peer. It must be in the + * same format that psa_import_key() accepts. The + * standard formats for public keys are documented + * in the documentation of psa_export_public_key(). + * The peer key data is parsed with the type + * #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) where + * type is the type of \p private_key, and with the + * same bit-size as \p private_key. + * \param peer_key_length Size of \p peer_key in bytes. + * + * \param alg The key agreement algorithm to compute + * (a \c PSA_ALG_XXX value such that + * #PSA_ALG_IS_KEY_AGREEMENT(\p alg) is true). + * + * \param[in] attributes The attributes for the new key. + * This function uses the attributes as follows: + * * The key type must be one of + * `PSA_KEY_TYPE_DERIVE`,`PSA_KEY_TYPE_RAW_DATA`, + * `PSA_KEY_TYPE_HMAC`, or + * `PSA_KEY_TYPE_PASSWORD`. + * * Implementations must support the + * `PSA_KEY_TYPE_DERIVE` and + * `PSA_KEY_TYPE_RAW_DATA` key types. + * * The size of the returned key is always the + * bit-size of the shared secret, rounded up to a + * whole number of bytes. The key size in \p + * attributes can be zero; if it is nonzero, it + * must be equal to the output size of the key + * agreement, in bits. + * * The output size, in bits, of the key agreement + * is #PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(type, + * bits), where type and bits are the type and + * bit-size of \p private_key. + * * The key permitted-algorithm policy is required + * for keys that will be used for a cryptographic + * operation. The key usage flags define what + * operations are permitted with the key. The key + * lifetime and identifier are required for a + * persistent key. + * + * \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 - please call \c + * psa_key_agreement_iop_complete() with the same context to complete + * the operation. + * + * \retval #PSA_ERROR_BAD_STATE + * Another operation has already been started on this context, and is + * still in progress. + * + * \retval #PSA_ERROR_NOT_PERMITTED + * The following conditions can result in this error: + * * Either the \p private_key does not have the #PSA_KEY_USAGE_DERIVE` + * flag, or it does not permit the requested algorithm. + * * The implementation does not permit creating a key with the + * specified attributes due to some implementation-specific policy. + * + * \retval #PSA_ERROR_INVALID_HANDLE + * \p private_key is not a valid key identifier. + * + * \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_INVALID_ARGUMENT + * The following conditions can result in this error: + * * \p alg is not a key agreement algorithm. + * * \p private_key is not compatible with \p alg. + * * \p peer_key is not a valid public key corresponding to + * \p private_key. + * * The output key attributes in \p attributes are not valid: + * - The key type is not valid for key agreement output. + * - The key size is nonzero, and is not the size of the shared + * secret. + * - 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_SUPPORTED + * The following conditions can result in this error: + * * \p alg is not supported or is not a key agreement algorithm. + * * \p private_key is not supported for use with \p alg. The output + * key attributes, as a whole, are not supported, either by the + * implementation in general or in the specified storage location. + * + * \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(). It is implementation-dependent whether a + * failure to initialize results in this error code. + * * The operation state is not valid: it must be inactive. + */ + +psa_status_t psa_key_agreement_iop_setup( + psa_key_agreement_iop_t *operation, + psa_key_id_t private_key, + const uint8_t *peer_key, + size_t peer_key_length, + psa_algorithm_t alg, + const psa_key_attributes_t *attributes); + /**@}*/ #ifdef __cplusplus