SE RT Services Utilities library

| SE RT Services Utilities library

Macros | Typedefs | Functions
Hash operations
IFX SE PSA crypto API

## General Description

Hash operations definitions.

## Macros
#define | IFX_SE_HASH_OPERATION_INIT {0}
| the initial value of the Hash operation context

## Typedefs
typedef struct ifx_se_hash_operation_s | ifx_se_hash_operation_t
| The type of the state data structure for multipart hash operations. More...

## Functions
ifx_se_status_t | ifx_se_hash_setup (ifx_se_hash_operation_t *operation, ifx_se_alg_fih_t alg, void *ctx)
| Set up a multipart hash operation. More...
ifx_se_status_t | ifx_se_hash_update (ifx_se_hash_operation_t *operation, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, void *ctx)
| Add a message fragment to a multipart hash operation. More...
ifx_se_status_t | ifx_se_hash_finish (ifx_se_hash_operation_t *operation, ifx_se_fih_ptr_t hash, ifx_se_fih_t hash_size, ifx_se_fih_ptr_t hash_length, void *ctx)
| Finish the calculation of the hash of a message. More...
ifx_se_status_t | ifx_se_hash_verify (ifx_se_hash_operation_t *operation, const ifx_se_fih_ptr_t hash, ifx_se_fih_t hash_length, void *ctx)
| Finish the calculation of the hash of a message and compare it with an expected value. More...
ifx_se_status_t | ifx_se_hash_abort (ifx_se_hash_operation_t *operation, void *ctx)
| Abort a hash operation. More...
ifx_se_status_t | ifx_se_hash_compute (ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, ifx_se_fih_ptr_t hash, ifx_se_fih_t hash_size, ifx_se_fih_ptr_t hash_length, void *ctx)
| Calculate the hash (digest) of a message. More...
ifx_se_status_t | ifx_se_hash_clone (const ifx_se_hash_operation_t *source_operation, ifx_se_hash_operation_t *target_operation, void *ctx)
| Clone a hash operation. More...
static struct ifx_se_hash_operation_s | ifx_se_hash_operation_init (void)
| Initialize the Hash operation context. More...

## Typedef Documentation

## ◆ ifx_se_hash_operation_t

typedef struct ifx_se_hash_operation_s ifx_se_hash_operation_t

The type of the state data structure for multipart hash operations.

This is an implementation-defined `struct`. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

## Function Documentation

## ◆ ifx_se_hash_setup()

ifx_se_status_t ifx_se_hash_setup | ( | ifx_se_hash_operation_t * | operation,
|  | ifx_se_alg_fih_t | alg,
|  | void * | ctx
| ) |  |

Set up a multipart hash operation.

The sequence of operations to calculate a hash (message digest) is as follows:

1. Allocate an operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for ifx_se_hash_operation_t, e.g. IFX_SE_HASH_OPERATION_INIT.
3. Call ifx_se_hash_setup() to specify the algorithm.
4. Call ifx_se_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.
5. To calculate the hash, call ifx_se_hash_finish(). To compare the hash with an expected value, call ifx_se_hash_verify().

If an error occurs at any step after a call to ifx_se_hash_setup(), the operation will need to be reset by a call to ifx_se_hash_abort(). The application may call ifx_se_hash_abort() at any time after the operation has been initialized.

After a successful call to ifx_se_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:

- A successful call to ifx_se_hash_finish() or ifx_se_hash_verify().
- A call to ifx_se_hash_abort().

Parameters

  [in,out] | operation | The operation object to set up. It must have been initialized as per the documentation for ifx_se_hash_operation_t and not yet in use.
  [in] | alg | The hash algorithm to compute (`IFX_SE_ALG_XXX` value such that IFX_SE_ALG_IS_HASH(`alg`) is true).
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS | Success.
  IFX_SE_ERROR_NOT_SUPPORTED | `alg` is not a supported hash algorithm.
  IFX_SE_ERROR_INVALID_ARGUMENT | `alg` is not a hash algorithm.
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_BAD_STATE | The operation state is not valid (it must be inactive).

## ◆ ifx_se_hash_update()

ifx_se_status_t ifx_se_hash_update | ( | ifx_se_hash_operation_t * | operation,
|  | const ifx_se_fih_ptr_t | input,
|  | ifx_se_fih_t | input_length,
|  | void * | ctx
| ) |  |

Add a message fragment to a multipart hash operation.

The application must call ifx_se_hash_setup() before calling this function.

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

Parameters

  [in,out] | operation | Active hash operation.
  [in] | input | Buffer containing the message fragment to hash (encoded pointer to input data).
  [in] | input_length | Size of the `input` buffer in bytes (size_t).
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS | Success.
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_BAD_STATE | The operation state is not valid (it must be active).

## ◆ ifx_se_hash_finish()

ifx_se_status_t ifx_se_hash_finish | ( | ifx_se_hash_operation_t * | operation,
|  | ifx_se_fih_ptr_t | hash,
|  | ifx_se_fih_t | hash_size,
|  | ifx_se_fih_ptr_t | hash_length,
|  | void * | ctx
| ) |  |

Finish the calculation of the hash of a message.

The application must call ifx_se_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to ifx_se_hash_update().

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

Warning
  Applications should not call this function if they expect a specific value for the hash. Call ifx_se_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as `memcmp` is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.

Parameters

  [in,out] | operation | Active hash operation.
  [out] | hash | Buffer where the hash is to be written (encoded pointer to output buffer).
  [in] | hash_size | Size of the `hash` buffer in bytes (size_t).
  [out] | hash_length | On success, the number of bytes that make up the hash value (encoded pointer to size_t variable). This is always IFX_SE_HASH_LENGTH(`alg`) where `alg` is the hash algorithm that is calculated.
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS | Success.
  IFX_SE_ERROR_BUFFER_TOO_SMALL | The size of the `hash` buffer is too small. You can determine a sufficient buffer size by calling IFX_SE_HASH_LENGTH(`alg`) where `alg` is the hash algorithm that is calculated.
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_BAD_STATE | The operation state is not valid (it must be active).

## ◆ ifx_se_hash_verify()

ifx_se_status_t ifx_se_hash_verify | ( | ifx_se_hash_operation_t * | operation,
|  | const ifx_se_fih_ptr_t | hash,
|  | ifx_se_fih_t | hash_length,
|  | void * | ctx
| ) |  |

Finish the calculation of the hash of a message and compare it with an expected value.

The application must call ifx_se_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to ifx_se_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.

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

Note
  Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.

Parameters

  [in,out] | operation | Active hash operation.
  [in] | hash | Buffer containing the expected hash value (encoded pointer to input data).
  [in] | hash_length | Size of the `hash` buffer in bytes (size_t).
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS | The expected hash is identical to the actual hash of the message.
  IFX_SE_ERROR_INVALID_SIGNATURE | The hash of the message was calculated successfully, but it differs from the expected hash.
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_BAD_STATE | The operation state is not valid (it must be active).

## ◆ ifx_se_hash_abort()

ifx_se_status_t ifx_se_hash_abort | ( | ifx_se_hash_operation_t * | operation,
|  | void * | ctx
| ) |  |

Abort a hash operation.

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

You may call this function any time after the operation object has been initialized by one of the methods described in ifx_se_hash_operation_t.

In particular, calling ifx_se_hash_abort() after the operation has been terminated by a call to ifx_se_hash_abort(), ifx_se_hash_finish() or ifx_se_hash_verify() is safe and has no effect.

Parameters

  [in,out] | operation | Initialized hash operation.
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |

## ◆ ifx_se_hash_compute()

ifx_se_status_t ifx_se_hash_compute | ( | ifx_se_alg_fih_t | alg,
|  | const ifx_se_fih_ptr_t | input,
|  | ifx_se_fih_t | input_length,
|  | ifx_se_fih_ptr_t | hash,
|  | ifx_se_fih_t | hash_size,
|  | ifx_se_fih_ptr_t | hash_length,
|  | void * | ctx
| ) |  |

Calculate the hash (digest) of a message.

Note
  To verify the hash of a message against an expected value, use ifx_se_hash_compare() instead.

Parameters

  [in] | alg | The hash algorithm to compute (`IFX_SE_ALG_XXX` value such that IFX_SE_ALG_IS_HASH(`alg`) is true).
  [in] | input | Buffer containing the message to hash (encoded pointer to input data).
  [in] | input_length | Size of the `input` buffer in bytes (size_t).
  [out] | hash | Buffer where the hash is to be written (encoded pointer to output buffer).
  [in] | hash_size | Size of the `hash` buffer in bytes (size_t).
  [out] | hash_length | On success, the number of bytes that make up the hash value (encoded pointer to size_t variable). This is always IFX_SE_HASH_LENGTH(`alg`).
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS | Success.
  IFX_SE_ERROR_NOT_SUPPORTED | `alg` is not supported or is not a hash algorithm.
  IFX_SE_ERROR_INVALID_ARGUMENT |
  IFX_SE_ERROR_BUFFER_TOO_SMALL | `hash_size` is too small
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |

## ◆ ifx_se_hash_clone()

ifx_se_status_t ifx_se_hash_clone | ( | const ifx_se_hash_operation_t * | source_operation,
|  | ifx_se_hash_operation_t * | target_operation,
|  | void * | ctx
| ) |  |

Clone a hash operation.

This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling ifx_se_hash_setup() on `target_operation` with the same algorithm that `source_operation` was set up for, then ifx_se_hash_update() on `target_operation` with the same input that that was passed to `source_operation`. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.

Parameters

  [in] | source_operation | The active hash operation to clone.
  [in,out] | target_operation | The operation object to set up. It must be initialized but not active.
  [in] | ctx | The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

  IFX_SE_SUCCESS |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_BAD_STATE | The `source_operation` state is not valid (it must be active), or the `target_operation` state is not valid (it must be inactive).

## ◆ ifx_se_hash_operation_init()

static struct ifx_se_hash_operation_s ifx_se_hash_operation_init | ( | void |  | ) |
| inlinestatic

Initialize the Hash operation context.

Returns
  ifx_se_hash_operation_s structure