Interruptible Key Agreement

Typedefs
typedef struct psa_key_agreement_iop_s	psa_key_agreement_iop_t

Functions
uint32_t	psa_key_agreement_iop_get_num_ops (psa_key_agreement_iop_t *operation)
	Get the number of ops that a key agreement operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling psa_key_agreement_iop_abort() on the operation, a value of 0 will be returned. More...
psa_status_t	psa_key_agreement_iop_setup (psa_key_agreement_iop_t *operation, mbedtls_svc_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)
	Start a key agreement operation, in an interruptible manner. More...
psa_status_t	psa_key_agreement_iop_complete (psa_key_agreement_iop_t *operation, mbedtls_svc_key_id_t *key)
	Continue and eventually complete the action of key agreement, in an interruptible manner. More...
psa_status_t	psa_key_agreement_iop_abort (psa_key_agreement_iop_t *operation)
	Abort a key agreement operation. More...

Detailed Description

Typedef Documentation

typedef struct psa_key_agreement_iop_s psa_key_agreement_iop_t

The type of the state data structure for interruptible key agreement operations.

Before calling any function on an interruptible key agreement object, the application must initialize it by any of the following means:

• Set the structure to all-bits-zero, for example:

  psa_key_agreement_iop_t operation;
  memset(&operation, 0, sizeof(operation));

• Initialize the structure to logical zero values, for example:

  psa_key_agreement_iop_t operation = {0};

• Initialize the structure to the initializer PSA_KEY_AGREEMENT_IOP_INIT, for example:

• psa_key_agreement_iop_t operation = PSA_KEY_AGREEMENT_IOP_INIT;

• Assign the result of the function psa_key_agreement_iop_init() to the structure, for example:

  psa_key_agreement_iop_t operation;
  operation = psa_key_agreement_iop_init();

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure. Implementation details can change in future versions without notice.

Definition at line 4940 of file crypto.h.

Function Documentation

psa_status_t psa_key_agreement_iop_abort

(

psa_key_agreement_iop_t *

operation

)

Abort a key agreement operation.

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 clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_key_agreement_iop_get_num_ops() if required before calling.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_key_agreement_iop_setup() again.

You may call this function any time after the operation object has been initialized. In particular, calling psa_key_agreement_iop_abort() after the operation has already been terminated by a call to psa_key_agreement_iop_abort() or psa_key_agreement_iop_complete() is safe.

Parameters

[in,out]

operation

The psa_key_agreement_iop_t to use

Return values

PSA_SUCCESS	The operation was aborted successfully.
PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init().

psa_status_t psa_key_agreement_iop_complete	(	psa_key_agreement_iop_t *	operation,
		mbedtls_svc_key_id_t *	key
	)

Continue and eventually complete the action of key agreement, in an interruptible manner.

See Also

psa_key_agreement_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 psa_key_agreement_iop_setup() is equivalent to psa_raw_key_agreement() but this function can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function call.

Users should call this function on the same operation object repeatedly while it returns PSA_OPERATION_INCOMPLETE, stopping when it returns either PSA_SUCCESS or an error. Alternatively users can call psa_key_agreement_iop_abort() at any point if they no longer want the result.

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 psa_key_agreement_iop_abort().

Parameters

[in,out]	operation	The psa_key_agreement_iop_t to use. This must be initialized first, and have had psa_key_agreement_iop_start() called with it first.
[out]	key	On success, an identifier for the newly created key. On failure this will be set to PSA_KEY_ID_NULL.

Return values

PSA_SUCCESS	The operation is complete and key contains the shared secret. If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
PSA_OPERATION_INCOMPLETE	Operation was interrupted due to the setting of psa_interruptible_set_max_ops(). There is still work to be done. Call this function again with the same operation object.
PSA_ERROR_ALREADY_EXISTS	This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_SIGNATURE	The calculation was performed successfully, but the passed signature is not a valid signature.
PSA_ERROR_BAD_STATE	An operation was not previously started on this context via psa_key_agreement_iop_start().
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_BAD_STATE	The following conditions can result in this error: The library has not been previously initialized by psa_crypto_init(). The operation state is not valid: it must be inactive.

uint32_t psa_key_agreement_iop_get_num_ops

(

psa_key_agreement_iop_t *

operation

)

Get the number of ops that a key agreement operation has taken so far. If the operation has completed, then this will represent the number of ops required for the entire operation. After initialization or calling psa_key_agreement_iop_abort() on the operation, a value of 0 will be returned.

Warning

This is a beta API, and thus subject to change at any point. It is not bound by the usual interface stability promises.

This is a helper provided to help you tune the value passed to psa_interruptible_set_max_ops().

Parameters

operation

The psa_key_agreement_iop_t to use. This must be initialized first.

Returns

Number of ops that the operation has taken so far.

psa_status_t psa_key_agreement_iop_setup	(	psa_key_agreement_iop_t *	operation,
		mbedtls_svc_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
	)

Start a key agreement operation, in an interruptible manner.

See Also

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.

The raw result of a key agreement algorithm such elliptic curve Diffie-Hellman has biases and should not be used directly as key material. It should instead be passed as input to a key derivation algorithm.

Note

This function combined with psa_key_agreement_iop_complete() is equivalent to psa_raw_key_agreement() but psa_key_agreement_iop_complete() can return early and resume according to the limit set with psa_interruptible_set_max_ops() to reduce the maximum time spent in a function.

Users should call psa_key_agreement_iop_complete() repeatedly on the same operation object after a successful call to this function until psa_key_agreement_iop_complete() either returns PSA_SUCCESS or an error. psa_key_agreement_iop_complete() will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_key_agreement_iop_abort() at any point if they no longer want the result.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_agreement_iop_abort().

Parameters

[in,out]	operation	The psa_key_agreement_iop_t to use. This must be initialized as per the documentation for psa_key_agreement_iop_t, and be inactive.
	private_key	Identifier of the private key to use. It must allow the usage PSA_KEY_USAGE_DERIVE.
[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 private_key, and with the same bit-size as private_key.
	peer_key_length	Size of peer_key in bytes.
	alg	The key agreement algorithm to compute (a PSA_ALG_XXX value such that PSA_ALG_IS_KEY_AGREEMENT(alg) is true).
[in]	attributes	The attributes for the new key. The following attributes are required for all keys: The key type, which must be one of PSA_KEY_TYPE_DERIVE, PSA_KEY_TYPE_RAW_DATA, PSA_KEY_TYPE_HMAC or PSA_KEY_TYPE_PASSWORD. 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 The following attributes are optional: If the key size 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 8 * PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(type, bits), where type and bits are the type and bit-size of private_key.

Note

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.

This function clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_key_agreement_iop_get_num_ops() if required before calling.

Return values

PSA_SUCCESS	The operation started successfully. Call psa_key_agreement_iop_complete() with the same context to complete the operation.
PSA_ERROR_BAD_STATE	Another operation has already been started on this context, and is still in progress.
PSA_ERROR_NOT_PERMITTED	The following conditions can result in this error: Either the private_key does not have the PSA_KEY_USAGE_DERIVE` flag, or it does not permit the requested algorithm.
PSA_ERROR_INVALID_HANDLE	private_key is not a valid key identifier.
PSA_ERROR_ALREADY_EXISTS	This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT	The following conditions can result in this error: alg is not a key agreement algorithm. private_key is not compatible with alg. peer_key is not a valid public key corresponding to private_key. The output key attributes in 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.
PSA_ERROR_NOT_SUPPORTED	The following conditions can result in this error: alg is not supported. private_key is not supported for use with alg. Only elliptic curve Diffie-Hellman with ECC keys is supported, not finite field Diffie-Hellman with DH keys.
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_BAD_STATE	The following conditions can result in this error: The library has not been previously initialized by psa_crypto_init(). The operation state is not valid: it must be inactive.