mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-03-12 19:13:31 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add psa_key_agreement_iop_setup() documentation

Browse Source 
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
This commit is contained in:
Paul Elliott 2024-07-18 21:30:36 +01:00
parent d791062fee
commit 2dc58fe717
2 changed files with 176 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
tf-psa-crypto/core/psa_crypto_ecp.c
View File

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

158
tf-psa-crypto/include/psa/crypto.h
View File

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