Group interruptible_generate_key

group Interruptible Key Generation

Typedefs

typedef struct psa_generate_key_iop_s psa_generate_key_iop_t

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

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

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

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

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

  psa_generate_key_iop_t operation = {0};
  

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

  psa_generate_key_iop_t operation = PSA_GENERATE_KEY_IOP_INIT;
  

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

  psa_generate_key_iop_t operation;
  operation = psa_generate_key_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.

Functions

uint32_t psa_generate_key_iop_get_num_ops(psa_generate_key_iop_t *operation)

Get the number of ops that a key generation 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_generate_key_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_generate_key_iop_t to use. This must be initialized first.

Returns:

Number of ops that the operation has taken so far.

psa_status_t psa_generate_key_iop_setup(psa_generate_key_iop_t *operation, const psa_key_attributes_t *attributes)

Start a key generation operation, in an interruptible manner.

See also

psa_generate_key_iop_complete()

Note

This function combined with psa_generate_key_iop_complete() is equivalent to psa_generate_key() but psa_generate_key_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.

Note

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

Note

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

Note

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

Note

Only asymmetric key pairs are supported. (See attributes.)

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.

Warning

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

Parameters:

• operation – [inout] The psa_generate_key_iop_t to use. This must be initialized as per the documentation for psa_generate_key_iop_t, and be inactive.

• attributes – [in] The attributes for the new key. The following attributes are required for all keys:

  • The key type. It must be an asymmetric key-pair.

  • The key size. It must be a valid size for the key type. 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,

Return values:

• PSA_SUCCESS – The operation started successfully. Call psa_generate_key_iop_complete() with the same context to complete the operation.

• 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_NOT_SUPPORTED – The key attributes, as a whole, are not supported, either in general or in the specified storage location.

• PSA_ERROR_INVALID_ARGUMENT – The following conditions can result in this error:

  • The key type is invalid, or is an asymmetric public key type.

  • The key size is not valid for the key type.

  • 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_PERMITTED – Creating a key with the specified attributes is not permitted.

• 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.

psa_status_t psa_generate_key_iop_complete(psa_generate_key_iop_t *operation, mbedtls_svc_key_id_t *key)

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

See also

psa_generate_key_iop_setup()

Note

This function combined with psa_generate_key_iop_setup() is equivalent to psa_generate_key() 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.

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 psa_generate_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 psa_generate_key_iop_abort().

Warning

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

Parameters:

• operation – [inout] The psa_generate_key_iop_t to use. This must be initialized first, and have had psa_generate_key_iop_setup() called with it first.

• key – [out] 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 new key. 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_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 active.

psa_status_t psa_generate_key_iop_abort(psa_generate_key_iop_t *operation)

Abort a key generation operation.

Note

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

Note

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_generate_key_iop_setup() again.

Note

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

Warning

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

Parameters:

operation – [inout] 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().