From e5b3e66fbaff47b5f8f6033f568bd14e4531ef08 Mon Sep 17 00:00:00 2001
From: Waleed Elmelegy <waleed.elmelegy@arm.com>
Date: Fri, 15 Nov 2024 17:13:13 +0000
Subject: [PATCH] Add psa_export_public_key_iop_complete() header/doc

Signed-off-by: Waleed Elmelegy <waleed.elmelegy@arm.com>
---
 tf-psa-crypto/include/psa/crypto.h | 84 ++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/tf-psa-crypto/include/psa/crypto.h b/tf-psa-crypto/include/psa/crypto.h
index ec4043a0d..79a7d5177 100644
--- a/tf-psa-crypto/include/psa/crypto.h
+++ b/tf-psa-crypto/include/psa/crypto.h
@@ -5684,6 +5684,90 @@ uint32_t psa_export_public_key_iop_get_num_ops(psa_export_public_key_iop_t *oper
 psa_status_t psa_export_public_key_iop_setup(psa_export_public_key_iop_t *operation,
                                              psa_key_id_t key);
 
+/**
+ * \brief                       Continue and eventually complete the action of
+ *                              exporting a public key, in an interruptible
+ *                              manner.
+ * \see                         \c psa_export_public_key_iop_setup()
+ *
+ * \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_export_public_key_iop_setup() is equivalent to
+ *                              \c psa_export_public_key() but this
+ *                              function 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 call.
+ *
+ * \note                        Users should call this function on the same
+ *                              operation object repeatedly whilst it returns
+ *                              #PSA_OPERATION_INCOMPLETE, stopping when it
+ *                              returns either #PSA_SUCCESS or an error.
+ *                              Alternatively users can call
+ *                              \c psa_export_public_key_iop_abort() at any
+ *                              point if they no longer want the result.
+ *
+ * \note                        When this function returns successfully, the
+ *                              operation becomes inactive. If this function
+ *                              returns an error status, the operation enters an
+ *                              error state and must be aborted by calling
+ *                              \c psa_export_public_key_iop_abort().
+ *
+ * \param[in, out] operation    The \c psa_export_public_key_iop_t to use.
+ *                              This must be initialized first, and have had
+ *                              \c psa_export_public_key_iop_setup() called
+ *                              with it first.
+ *
+ * \param[out] data             Buffer where the key data is to be written.
+ *
+ * \param[in] data_size         Size of the \c data buffer in bytes.
+ *                              This must be appropriate for the key:
+ *                               * The required output size is
+ *                                 \c PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(type, bits)
+ *                                 where type is the key type and bits is the key
+ *                                 size in bits.
+ *                               * \c PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum
+ *                                 output size of any supported public key or public part
+ *                                 of a key pair.
+ *                               * \c PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE evaluates
+ *                                 to the maximum output size of any supported public
+ *                                 key or key pair.
+ *
+ * \param[out] data_length      On success, the number of bytes that make up the key data.
+ *
+ * \retval #PSA_SUCCESS
+ *         Success. The first (*\c data_length) bytes of data contain the exported
+           public key.
+ * \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 active.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *          The size of the data buffer is too small.
+ *          \c PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(),
+ *          \c PSA_EXPORT_PUBLIC_KEY_MAX_SIZE, or
+ *          \c PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE can be used to determine a
+ *          sufficient buffer size.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_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_OPERATION_INCOMPLETE
+ *         Operation was interrupted due to the setting of
+ *         \c psa_interruptible_set_max_ops(). There is still work to be done.
+ *         Call this function again with the same operation object.
+ */
+psa_status_t psa_export_public_key_iop_complete(psa_export_public_key_iop_t *operation,
+                                                uint8_t *data,
+                                                size_t data_size,
+                                                size_t *data_length);
+
 #ifdef __cplusplus
 }
 #endif