Add psa_key_agreement_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 9e98cc1..ce119e2 100644
--- a/tf-psa-crypto/core/psa_crypto_ecp.c
+++ b/tf-psa-crypto/core/psa_crypto_ecp.c
@@ -603,4 +603,22 @@
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 75ea8fe..c43f674 100644
--- a/tf-psa-crypto/include/psa/crypto.h
+++ b/tf-psa-crypto/include/psa/crypto.h
@@ -4877,6 +4877,164 @@
*/
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