Add psa_generate_key_iop_setup() documentation
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
diff --git a/tf-psa-crypto/core/psa_crypto_ecp.c b/tf-psa-crypto/core/psa_crypto_ecp.c
index 7f3a2b6..16c3946 100644
--- a/tf-psa-crypto/core/psa_crypto_ecp.c
+++ b/tf-psa-crypto/core/psa_crypto_ecp.c
@@ -603,6 +603,16 @@
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 @@
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 ac466da..71ac2e9 100644
--- a/tf-psa-crypto/include/psa/crypto.h
+++ b/tf-psa-crypto/include/psa/crypto.h
@@ -5231,6 +5231,118 @@
*/
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