Add psa_export_public_key_iop_complete() header/doc

Signed-off-by: Waleed Elmelegy <waleed.elmelegy@arm.com>
This commit is contained in:
Waleed Elmelegy 2024-11-15 17:13:13 +00:00
parent c8d50f5753
commit e5b3e66fba

View File

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