Loading...
Searching...
No Matches
Interruptible sign/verify hash

## Typedefs

typedef struct psa_sign_hash_interruptible_operation_s | psa_sign_hash_interruptible_operation_t
typedef struct psa_verify_hash_interruptible_operation_s | psa_verify_hash_interruptible_operation_t

## Functions

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.
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.
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.
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.
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.
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.
psa_status_t | psa_sign_hash_abort (psa_sign_hash_interruptible_operation_t *operation)
| Abort a sign hash operation.
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.
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.
psa_status_t | psa_verify_hash_abort (psa_verify_hash_interruptible_operation_t *operation)
| Abort a verify hash operation.

## Detailed Description

## Typedef Documentation

## psa_sign_hash_interruptible_operation_t

typedef struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_t

The type of the state data structure for interruptible hash signing operations.

Before calling any function on a sign hash operation object, the application must initialize it by any of the following means:

- Set the structure to all-bits-zero, for example:
  psa_sign_hash_interruptible_operation_t operation;
  memset(&operation, 0, sizeof(operation));
  psa_sign_hash_interruptible_operation_s
  The context for PSA interruptible hash signing.
  Definition crypto_struct.h:450
- Initialize the structure to logical zero values, for example:
  psa_sign_hash_interruptible_operation_t operation = {0};
- Initialize the structure to the initializer PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT, for example:
  psa_sign_hash_interruptible_operation_t operation =
  PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT;
  PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT
  #define PSA_SIGN_HASH_INTERRUPTIBLE_OPERATION_INIT
  Definition crypto_struct.h:473
- Assign the result of the function psa_sign_hash_interruptible_operation_init() to the structure, for example:
  psa_sign_hash_interruptible_operation_t operation;
  operation = psa_sign_hash_interruptible_operation_init();
  psa_sign_hash_interruptible_operation_init
  static struct psa_sign_hash_interruptible_operation_s psa_sign_hash_interruptible_operation_init(void)
  Definition crypto_struct.h:477

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 4367 of file crypto.h.

## psa_verify_hash_interruptible_operation_t

typedef struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_t

The type of the state data structure for interruptible hash verification operations.

Before calling any function on a sign hash operation object, the application must initialize it by any of the following means:

- Set the structure to all-bits-zero, for example:
  psa_verify_hash_interruptible_operation_t operation;
  memset(&operation, 0, sizeof(operation));
  psa_verify_hash_interruptible_operation_s
  The context for PSA interruptible hash verification.
  Definition crypto_struct.h:488
- Initialize the structure to logical zero values, for example:
  psa_verify_hash_interruptible_operation_t operation = {0};
- Initialize the structure to the initializer PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT, for example:
  psa_verify_hash_interruptible_operation_t operation =
  PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT;
  PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT
  #define PSA_VERIFY_HASH_INTERRUPTIBLE_OPERATION_INIT
  Definition crypto_struct.h:511
- Assign the result of the function psa_verify_hash_interruptible_operation_init() to the structure, for example:
  psa_verify_hash_interruptible_operation_t operation;
  operation = psa_verify_hash_interruptible_operation_init();
  psa_verify_hash_interruptible_operation_init
  static struct psa_verify_hash_interruptible_operation_s psa_verify_hash_interruptible_operation_init(void)
  Definition crypto_struct.h:515

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 4400 of file crypto.h.

## Function Documentation

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

Warning
  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_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.

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

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

Parameters

  max_ops | The maximum number of ops to be executed in a single call. This can be a number from 0 to PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED, where 0 is the least amount of work done per call.

## psa_sign_hash_abort()

psa_status_t psa_sign_hash_abort | ( | psa_sign_hash_interruptible_operation_t * | operation | ) |

Abort a sign hash 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 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.

Parameters

  [in,out] | operation | Initialized sign hash operation.

Return values

  PSA_SUCCESS | The operation was aborted successfully.
  PSA_ERROR_NOT_SUPPORTED |
  PSA_ERROR_BAD_STATE | The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## 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()`

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_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()`.

Parameters

  [in,out] | operation | The `psa_sign_hash_interruptible_operation_t` to use. This must be initialized first, and have had `psa_sign_hash_start()` called with it first.
  [out] | signature | Buffer where the signature is to be written.

  signature_size

  Size of the `signature` buffer in bytes. This must be appropriate for the selected algorithm and key:
  - The required signature size is PSA_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of key.
  - PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.

  [out] | signature_length | On success, the number of bytes that make up the returned signature value.

Return values

  PSA_SUCCESS | Operation completed successfully
  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_BUFFER_TOO_SMALL | The size of the `signature` buffer is too small. You can determine a sufficient buffer size by calling PSA_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of `key`.
  PSA_ERROR_BAD_STATE | An operation was not previously started on this context via `psa_sign_hash_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 library has either not been previously initialized by psa_crypto_init() or you did not previously call psa_sign_hash_start() with this operation object. It is implementation-dependent whether a failure to initialize results in this error code.

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

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_sign_hash_interruptible_operation_t` to use. This must be initialized first.

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()`

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_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()`.

Parameters

  [in,out] | operation | The `psa_sign_hash_interruptible_operation_t` to use. This must be initialized first.
  | key | Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
  | alg | A signature algorithm (`PSA_ALG_XXX` value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
  [in] | hash | The hash or message to sign.
  | hash_length | Size of the `hash` buffer in bytes.

Return values

  PSA_SUCCESS | The operation started successfully - call `psa_sign_hash_complete()` with the same context to complete the operation
  PSA_ERROR_INVALID_HANDLE |
  PSA_ERROR_NOT_PERMITTED | The key does not have the PSA_KEY_USAGE_SIGN_HASH flag, or it does not permit the requested algorithm.
  PSA_ERROR_BAD_STATE | An operation has previously been started on this context, and is still in progress.
  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 library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## psa_verify_hash_abort()

psa_status_t psa_verify_hash_abort | ( | psa_verify_hash_interruptible_operation_t * | operation | ) |

Abort a verify hash 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 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.

Parameters

  [in,out] | operation | Initialized verify hash operation.

Return values

  PSA_SUCCESS | The operation was aborted successfully.
  PSA_ERROR_NOT_SUPPORTED |
  PSA_ERROR_BAD_STATE | The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

## 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()`

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_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()`.

Parameters

  [in,out] | operation | The `psa_verify_hash_interruptible_operation_t` to use. This must be initialized first, and have had `psa_verify_hash_start()` called with it first.

Return values

  PSA_SUCCESS | Operation completed successfully, and the passed signature is valid.
  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_INVALID_HANDLE |
  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_verify_hash_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 library has either not been previously initialized by psa_crypto_init() or you did not previously call psa_verify_hash_start() on this object. It is implementation-dependent whether a failure to initialize results in this error code.

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

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_verify_hash_interruptible_operation_t` to use. This must be initialized first.

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

## 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()`

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_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()`.

Parameters

  [in,out] | operation | The `psa_verify_hash_interruptible_operation_t` to use. This must be initialized first.
  | key | Identifier of the key to use for the operation. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
  | alg | A signature algorithm (`PSA_ALG_XXX` value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
  [in] | hash | The hash whose signature is to be verified.
  | hash_length | Size of the `hash` buffer in bytes.
  [in] | signature | Buffer containing the signature to verify.
  | signature_length | Size of the `signature` buffer in bytes.

Return values

  PSA_SUCCESS | The operation started successfully - please call `psa_verify_hash_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 key does not have the PSA_KEY_USAGE_VERIFY_HASH flag, or it does not permit the requested algorithm.
  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_BAD_STATE | The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.