SE RT Services Utilities library

| SE RT Services Utilities library

Functions
Signature and verification operations
IFX SE PSA crypto API

## General Description

Signature and verification operations definitions.

## Functions
ifx_se_status_t | ifx_se_sign_hash (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t hash, ifx_se_fih_t hash_length, const ifx_se_fih_ptr_t signature, ifx_se_fih_t signature_size, ifx_se_fih_ptr_t signature_length, void *ctx)
| Sign a hash or short message with a private key. More...
ifx_se_status_t | ifx_se_verify_hash (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t hash, ifx_se_fih_t hash_length, const ifx_se_fih_ptr_t signature, ifx_se_fih_t signature_length, void *ctx)
| Verify the signature of a hash or short message using a public key. More...
ifx_se_status_t | ifx_se_sign_message (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, ifx_se_fih_ptr_t signature, ifx_se_fih_t signature_size, ifx_se_fih_ptr_t signature_length, void *ctx)
| Sign a message with a private key. More...
ifx_se_status_t | ifx_se_verify_message (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, const ifx_se_fih_ptr_t signature, ifx_se_fih_t signature_length, void *ctx)
| Verify the signature of a message with a public key, using a hash-and-sign verification algorithm. More...

## Function Documentation

## ◆ ifx_se_sign_hash()

ifx_se_status_t ifx_se_sign_hash | ( | ifx_se_key_id_fih_t | key,
|  | ifx_se_alg_fih_t | alg,
|  | const ifx_se_fih_ptr_t | hash,
|  | ifx_se_fih_t | hash_length,
|  | const ifx_se_fih_ptr_t | signature,
|  | ifx_se_fih_t | signature_size,
|  | ifx_se_fih_ptr_t | signature_length,
|  | void * | ctx
| ) |  |

Sign a hash or short message with a private key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling ifx_se_hash_setup(), ifx_se_hash_update() and ifx_se_hash_finish(), or alternatively by calling ifx_se_hash_compute(). Then pass the resulting hash as the `hash` parameter to this function. You can use IFX_SE_ALG_SIGN_GET_HASH(`alg`) to determine the hash algorithm to use.

Parameters

  [in] | key | Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage IFX_SE_KEY_USAGE_SIGN_HASH.
  [in] | alg | A signature algorithm (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
  [in] | hash | The hash or message to sign (encoded pointer to input data).
  [in] | hash_length | Size of the `hash` buffer in bytes (size_t).
  [out] | signature | Buffer where the signature is to be written (encoded pointer to output buffer).
  [in] | signature_size | Size of the `signature` buffer in bytes (size_t).
  [out] | signature_length | On success, the number of bytes that make up the returned signature value (encoded pointer to size_t variable).
  [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_INVALID_HANDLE |
  IFX_SE_ERROR_NOT_PERMITTED |
  IFX_SE_ERROR_BUFFER_TOO_SMALL | The size of the `signature` buffer is too small. You can determine a sufficient buffer size by calling IFX_SE_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of `key`.
  IFX_SE_ERROR_NOT_SUPPORTED |
  IFX_SE_ERROR_INVALID_ARGUMENT |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_STORAGE_FAILURE |
  IFX_SE_ERROR_INSUFFICIENT_ENTROPY |

## ◆ ifx_se_verify_hash()

ifx_se_status_t ifx_se_verify_hash | ( | ifx_se_key_id_fih_t | key,
|  | ifx_se_alg_fih_t | alg,
|  | const ifx_se_fih_ptr_t | hash,
|  | ifx_se_fih_t | hash_length,
|  | const ifx_se_fih_ptr_t | signature,
|  | ifx_se_fih_t | signature_length,
|  | void * | ctx
| ) |  |

Verify the signature of a hash or short message using a public key.

Note that to perform a hash-and-sign signature algorithm, you must first calculate the hash by calling ifx_se_hash_setup(), ifx_se_hash_update() and ifx_se_hash_finish(), or alternatively by calling ifx_se_hash_compute(). Then pass the resulting hash as the `hash` parameter to this function. You can use IFX_SE_ALG_SIGN_GET_HASH(`alg`) to determine the hash algorithm to use.

Parameters

  [in] | key | Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage IFX_SE_KEY_USAGE_VERIFY_HASH.
  [in] | alg | A signature algorithm (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of `key`.
  [in] | hash | The hash or message whose signature is to be verified (encoded pointer to input data).
  [in] | hash_length | Size of the `hash` buffer in bytes (size_t).
  [in] | signature | Buffer containing the signature to verify (encoded pointer to input data).
  [in] | signature_length | Size of the `signature` 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 signature is valid.
  IFX_SE_ERROR_INVALID_HANDLE |
  IFX_SE_ERROR_NOT_PERMITTED |
  IFX_SE_ERROR_INVALID_SIGNATURE | The calculation was performed successfully, but the passed signature is not a valid signature.
  IFX_SE_ERROR_NOT_SUPPORTED |
  IFX_SE_ERROR_INVALID_ARGUMENT |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_STORAGE_FAILURE |

## ◆ ifx_se_sign_message()

ifx_se_status_t ifx_se_sign_message | ( | ifx_se_key_id_fih_t | key,
|  | ifx_se_alg_fih_t | alg,
|  | const ifx_se_fih_ptr_t | input,
|  | ifx_se_fih_t | input_length,
|  | ifx_se_fih_ptr_t | signature,
|  | ifx_se_fih_t | signature_size,
|  | ifx_se_fih_ptr_t | signature_length,
|  | void * | ctx
| ) |  |

Sign a message with a private key.

For hash-and-sign algorithms, this includes the hashing step.

Note
  To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to ifx_se_sign_hash(). IFX_SE_ALG_GET_HASH(`alg`) can be used to determine the hash algorithm to use.

Parameters

  [in] | key | Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage IFX_SE_KEY_USAGE_SIGN_MESSAGE.
  [in] | alg | An asymmetric signature algorithm (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_SIGN_MESSAGE(`alg`) is true), that is compatible with the type of `key`.
  [in] | input | The input message to sign (encoded pointer to input data).
  [in] | input_length | Size of the `input` buffer in bytes (size_t).
  [out] | signature | Buffer where the signature is to be written (encoded pointer to output buffer).
  [in] | signature_size | Size of the `signature` buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: The required signature size is IFX_SE_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of key. IFX_SE_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 (encoded pointer to size_t variable).
  [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_INVALID_HANDLE |
  IFX_SE_ERROR_NOT_PERMITTED | The key does not have the IFX_SE_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
  IFX_SE_ERROR_BUFFER_TOO_SMALL | The size of the `signature` buffer is too small. You can determine a sufficient buffer size by calling IFX_SE_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of `key`.
  IFX_SE_ERROR_NOT_SUPPORTED |
  IFX_SE_ERROR_INVALID_ARGUMENT |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_STORAGE_FAILURE |
  IFX_SE_ERROR_DATA_CORRUPT |
  IFX_SE_ERROR_DATA_INVALID |
  IFX_SE_ERROR_INSUFFICIENT_ENTROPY |

## ◆ ifx_se_verify_message()

ifx_se_status_t ifx_se_verify_message | ( | ifx_se_key_id_fih_t | key,
|  | ifx_se_alg_fih_t | alg,
|  | const ifx_se_fih_ptr_t | input,
|  | ifx_se_fih_t | input_length,
|  | const ifx_se_fih_ptr_t | signature,
|  | ifx_se_fih_t | signature_length,
|  | void * | ctx
| ) |  |

Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.

Note
  To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash operation to hash the message and then pass the resulting hash to ifx_se_verify_hash(). IFX_SE_ALG_GET_HASH(`alg`) can be used to determine the hash algorithm to use.

Parameters

  [in] | key | Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage IFX_SE_KEY_USAGE_VERIFY_MESSAGE.
  [in] | alg | An asymmetric signature algorithm (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_SIGN_MESSAGE(`alg`) is true), that is compatible with the type of `key`.
  [in] | input | The message whose signature is to be verified (encoded pointer to input data).
  [in] | input_length | Size of the `input` buffer in bytes (size_t).
  [in] | signature | Buffer containing the signature to verify (encoded pointer to input data).
  [in] | signature_length | Size of the `signature` 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 |
  IFX_SE_ERROR_INVALID_HANDLE |
  IFX_SE_ERROR_NOT_PERMITTED | The key does not have the IFX_SE_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.
  IFX_SE_ERROR_INVALID_SIGNATURE | The calculation was performed successfully, but the passed signature is not a valid signature.
  IFX_SE_ERROR_NOT_SUPPORTED |
  IFX_SE_ERROR_INVALID_ARGUMENT |
  IFX_SE_ERROR_INSUFFICIENT_MEMORY |
  IFX_SE_ERROR_COMMUNICATION_FAILURE |
  IFX_SE_ERROR_HARDWARE_FAILURE |
  IFX_SE_ERROR_CORRUPTION_DETECTED |
  IFX_SE_ERROR_STORAGE_FAILURE |
  IFX_SE_ERROR_DATA_CORRUPT |
  IFX_SE_ERROR_DATA_INVALID |