Use case

There are some systems in which there is a requirement for asymmetric cryptographic operations in execution contexts that cannot tolerate long-running functions. However, some asymmetric operations have long, very long, or even arbitrary execution times.

For example, these use cases can arise in constrained microcontrollers that have real-time response requirements, or in firmware that executes in highly-privileged execution modes.

Proposal

The long-duration asymmetric operations are typically composed of many repeated smaller steps. If the Crypto API exposed a mechanism for the application to perform the operation in a step-wise — 'interruptible' — manner, then the application can meet the bounded-latency requirement by repeatedly calling the API to make progress on the operation.

Mbed-TLS now has a prototype API for interruptible hash signature operations (sigh-hash and verify-hash), which effectively proposes a general pattern for this type of API.

The API is composed of the following building-blocks. For details of the proposal please see Mbed-TLS/mbedtls#6279.

PSA_OPERATION_INCOMPLETE (macro)

This is a non-error status code to indicate an incomplete interruptible operation. This is already defined in the Status code API.

ops

This is a term used to describe a 'unit of work' that can be carried out within an interruptible operation. The actual 'size' or time duration for one op is implementation- and function- specific, and can also be dependent on the algorithm inputs (such as the key size).

An application can set a global 'max ops' value, that limits the ops performed within any interruptible function. If an interruptible function does not complete before reaching this threshold it will return PSA_OPERATION_INCOMPLETE instead of an error or success status.

The current threshold can also be queried. When an interruptible operation completes, the application can also query the total number of ops required: this can allow an application to tune the threshold value it uses.

Interruptible operation object

An interruptible operation requires the management of state relating to the operation. This is held (or referenced, depending on implementation) in an implementation-defined object that this allocated by the application. The allocation and lifecycle of these objects follows a similar pattern to that used for multi-part operations in the existing API.

Interruptible operation objects must be initialized before first use, also like the multi-part operation objects.

Interruptible operation sequence

Each interruptible operation will have a set-up function to provide the input parameters. This is typically named psa_xxx_start(), for example, psa_sign_hash_start().

To progress the operation, a matching psa_xxx_complete() function is called repeatedly, providing any required output parameters:

• If the operation finishes, the output is provided and PSA_SUCCESS is returned.
• If the operation fails, then an appropriate error status is returned
• If the operation has not completed yet, PSA_OPERATION_INCOMPLETE is returned. The caller should invoke the psa_xxx_complete() function again

On successful completion, the operation object is reset, but can still be queried to determine the number of ops required.

On error, the operation object enters an error state, and must be reset by a call to psa_xxx_abort(). The application can also call psa_xxx_abort() to cancel an in-progress interruptible operation.