Interruptible sign/verify hash#

psa_interruptible_set_max_ops#

void psa_interruptible_set_max_ops (uint32_t max_ops)

Set the maximum number of ops allowed to be executed by an interruptible function in a single call.

Warnings

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

Note

• The time taken to execute a single op is implementation specific and depends on software, hardware, the algorithm, key type and curve chosen. Even within a single operation, successive ops can take differing amounts of time. The only guarantee is that lower values for max_ops means functions will block for a lesser maximum amount of time. The functions psa_sign_interruptible_get_num_ops() and psa_verify_interruptible_get_num_ops() are provided to help with tuning this value.

• This value defaults to PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, which means the whole operation will be done in one go, regardless of the number of ops required.

• If more ops are needed to complete a computation, PSA_OPERATION_INCOMPLETE will be returned by the function performing the computation. It is then the caller's responsibility to either call again with the same operation context until it returns 0 or an error code; or to call the relevant abort function if the answer is no longer required.

• The interpretation of max_ops is also implementation defined. On a hard real time system, this can indicate a hard deadline, as a real-time system needs a guarantee of not spending more than X time, however care must be taken in such an implementation to avoid the situation whereby calls just return, not being able to do any actual work within the allotted time. On a non-real-time system, the implementation can be more relaxed, but again whether this number should be interpreted as as hard or soft limit or even whether a less than or equals as regards to ops executed in a single call is implementation defined.

• For keys in local storage when no accelerator driver applies, please see also the documentation for mbedtls_ecp_set_max_ops(), which is the internal implementation in these cases.

Warnings

• With implementations that interpret this number as a hard limit, setting this number too small may result in an infinite loop, whereby each call results in immediate return with no ops done (as there is not enough time to execute any), and thus no result will ever be achieved.

Note

• This only applies to functions whose documentation mentions they may return PSA_OPERATION_INCOMPLETE.

psa_interruptible_get_max_ops#

uint32_t psa_interruptible_get_max_ops (void)

Get the maximum number of ops allowed to be executed by an interruptible function in a single call.

This will return the last value set by psa_interruptible_set_max_ops() or PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED if that function has never been called.

Warnings

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

Returns

• Maximum number of ops allowed to be executed by an interruptible function in a single call.

psa_sign_hash_get_num_ops#

uint32_t psa_sign_hash_get_num_ops (const psa_sign_hash_interruptible_operation_t *operation)

Get the number of ops that a hash signing 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_sign_hash_interruptible_abort() on the operation, a value of 0 will be returned.

Note

• This interface is guaranteed re-entrant and thus may be called from driver code.

Warnings

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

Returns

• Number of ops that the operation has taken so far.

psa_verify_hash_get_num_ops#

uint32_t psa_verify_hash_get_num_ops (const psa_verify_hash_interruptible_operation_t *operation)

Get the number of ops that a hash verification 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_verify_hash_interruptible_abort() on the operation, a value of 0 will be returned.

Warnings

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

Returns

• Number of ops that the operation has taken so far.

psa_sign_hash_start#

psa_status_t psa_sign_hash_start (psa_sign_hash_interruptible_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length)

Start signing a hash or short message with a private key, in an interruptible manner.

See Also

• psa_sign_hash_complete()

Warnings

• 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_sign_hash_complete() is equivalent to psa_sign_hash() but psa_sign_hash_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 call.

• Users should call psa_sign_hash_complete() repeatedly on the same context after a successful call to this function until psa_sign_hash_complete() either returns 0 or an error. psa_sign_hash_complete() will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_sign_hash_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_sign_hash_abort().

psa_sign_hash_complete#

psa_status_t psa_sign_hash_complete (psa_sign_hash_interruptible_operation_t *operation, uint8_t *signature, size_t signature_size, size_t *signature_length)

Continue and eventually complete the action of signing a hash or short message with a private key, in an interruptible manner.

See Also

• psa_sign_hash_start()

Warnings

• 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_sign_hash_start() is equivalent to psa_sign_hash() 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 until it either returns 0 or an error. This function will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_sign_hash_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_sign_hash_abort().

See Also

• psa_sign_hash_start()

Warnings

• 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_sign_hash_start() is equivalent to psa_sign_hash() 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 until it either returns 0 or an error. This function will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_sign_hash_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_sign_hash_abort().

psa_sign_hash_abort#

psa_status_t psa_sign_hash_abort (psa_sign_hash_interruptible_operation_t *operation)

Abort a sign hash operation.

Warnings

• 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 is the only function that clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_sign_hash_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_sign_hash_start() again.

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

psa_verify_hash_start#

psa_status_t psa_verify_hash_start (psa_verify_hash_interruptible_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)

Start reading and verifying a hash or short message, in an interruptible manner.

See Also

• psa_verify_hash_complete()

Warnings

• 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_verify_hash_complete() is equivalent to psa_verify_hash() but psa_verify_hash_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_verify_hash_complete() repeatedly on the same operation object after a successful call to this function until psa_verify_hash_complete() either returns 0 or an error. psa_verify_hash_complete() will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_verify_hash_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_verify_hash_abort().

psa_verify_hash_complete#

psa_status_t psa_verify_hash_complete (psa_verify_hash_interruptible_operation_t *operation)

Continue and eventually complete the action of reading and verifying a hash or short message signed with a private key, in an interruptible manner.

See Also

• psa_verify_hash_start()

Warnings

• 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_verify_hash_start() is equivalent to psa_verify_hash() 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 until it either returns 0 or an error. This function will return PSA_OPERATION_INCOMPLETE if there is more work to do. Alternatively users can call psa_verify_hash_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_verify_hash_abort().

psa_verify_hash_abort#

psa_status_t psa_verify_hash_abort (psa_verify_hash_interruptible_operation_t *operation)

Abort a verify hash operation.

Warnings

• 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 is the only function that clears the number of ops completed as part of the operation. Please ensure you copy this value via psa_verify_hash_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_verify_hash_start() again.

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