MCUX CLNS MCUX Crypto Library Normal Secure |

Functions
mcuxClCss_Hash_Functions
mcuxClCss » mcuxClCss_Hash

Defines all functions of mcuxClCss_Hash. More...

## Functions

MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Hash_Async (mcuxClCss_HashOption_t options, uint8_t const *pInput, size_t inputLength, uint8_t *pDigest)
| Computes the hash of a message. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_ShaDirect_Enable (void)
| Enables SHA-direct mode. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_ShaDirect_Disable (void)
| Disables SHA-direct mode. More...
MCUXCLCSS_API mcuxClCss_Status_Protected_t | mcuxClCss_Hash_ShaDirect (mcuxClCss_HashOption_t options, uint8_t const *pInput, size_t inputLength, uint8_t *pDigest, mcuxClCss_TransferToRegisterFunction_t pCallback, void *pCallerData)
| Calculates the hash of a message using SHA-Direct mode. More...

## Detailed Description

Defines all functions of mcuxClCss_Hash.

## Function Documentation

## ◆ mcuxClCss_Hash_Async()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Hash_Async | ( | mcuxClCss_HashOption_t | options,
|  | uint8_t const * | pInput,
|  | size_t | inputLength,
|  | uint8_t * | pDigest
| ) |  |

Computes the hash of a message.

Call mcuxClCss_WaitForOperation to complete the operation.

Parameters

  [in] | options | The command options. For more information, see mcuxClCss_HashOption_t.
  [in] | pInput | Padded input data to be hashed
  [in] | inputLength | Size of `pInput` in bytes. Since the input is padded, the length must be a multiple of the block size, see MCUXCLCSS_HASH_BLOCK_SIZE_.
  [in,out] | pDigest | Pointer to the memory area that contains/receives the (intermediate) hash digest, allocated by the caller, see MCUXCLCSS_HASH_STATE_SIZE_.

The properties of some parameters change with respect to selected options.

Parameter properties
  `options.hashini` == MCUXCLCSS_HASH_INIT_ENABLE

    `options.hashld` has no effect and shall be MCUXCLCSS_HASH_LOAD_DISABLE. No data is read from `pDigest`.

  `options.hashld` == MCUXCLCSS_HASH_LOAD_DISABLE

    `pDigest` is not expected to contain an initial state. No data is read from `pDigest`.

  `options.rtfoe` == MCUXCLCSS_HASH_RTF_UPDATE_ENABLE

    When this option is used the current runtime fingerprint (RTF) value will be appended to the output `pDigest`; an additional MCUXCLCSS_HASH_RTF_OUTPUT_SIZE bytes has to be allocated for `pDigest`.

  `options.hashoe` == MCUXCLCSS_HASH_OUTPUT_ENABLE

    The hash state is written to `pDigest`. The size varies depending on the choice of `options.hashmd`, for more information see MCUXCLCSS_HASH_STATE_SIZE_ . In cases where the state size and output size differ - see MCUXCLCSS_HASH_OUTPUT_SIZE_ -, the state must be truncated by the caller to obtain the final hash value.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK_WAIT | on successful request

Examples
  hash_sha224_one_block.c, hash_sha256_one_block.c, hash_sha384_one_block.c, and hash_sha512_one_block.c.

## ◆ mcuxClCss_ShaDirect_Enable()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_ShaDirect_Enable | ( | void |  | ) |

Enables SHA-direct mode.

If this mode is enabled, it allows the application processor to access the CSS hash engine, but at the same time it stops CSS operations from using the hash engine.

Therefore, in SHA-direct mode, hashing can only be done with mcuxClCss_Hash_ShaDirect. When SHA-direct mode is active, CSS operations which internally use the CSS hash engine will result in an operational error (see MCUXCLCSS_STATUS_HW_OPERATIONAL). To use those operations, disable SHA-direct mode. Please consult function descriptions to check whether and under which circumstances they internally use the CSS hash engine.

CSS operations which do not internally use the CSS hash engine can be performed in parallel with a SHA-direct hash operation.

Returns
  A code-flow protected error code (see Flow Protection API)

Return values

  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK | on success

Examples
  hash_sha256_sha_direct_one_block.c, and hash_sha384_sha_direct_one_block.c.

## ◆ mcuxClCss_ShaDirect_Disable()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_ShaDirect_Disable | ( | void |  | ) |

Disables SHA-direct mode.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_OK | on success

Examples
  hash_sha256_sha_direct_one_block.c, and hash_sha384_sha_direct_one_block.c.

## ◆ mcuxClCss_Hash_ShaDirect()

MCUXCLCSS_API mcuxClCss_Status_Protected_t mcuxClCss_Hash_ShaDirect | ( | mcuxClCss_HashOption_t | options,
|  | uint8_t const * | pInput,
|  | size_t | inputLength,
|  | uint8_t * | pDigest,
|  | mcuxClCss_TransferToRegisterFunction_t | pCallback,
|  | void * | pCallerData
| ) |  |

Calculates the hash of a message using SHA-Direct mode.

SHA-Direct mode must be enabled before calling this function. For more information, see mcuxClCss_ShaDirect_Enable.

In order to perform a hash calculation in SHA-Direct mode, the CPU must feed the input data to a register in CSSv2's SHA core, or configure a DMA to copy the input data to that register. A DMA can be used because feeding input data to the SHA core while the SHA core is busy results in an AHB bus stall, and there is no need to check any further flags before copying further data. If a DMA shall be used to perform this copy, a callback function must be provided by the caller that will configure and start the DMA. If no callback function is specified, this function will resort to using the CPU.

Parameters

  [in] | options | The command options. For more information, see mcuxClCss_HashOption_t.
  [in] | pInput | Padded input data to be hashed.
  [in] | inputLength | Size of `pInput` in bytes. Since the input is padded, the length must be a multiple of the block size, see MCUXCLCSS_HASH_BLOCK_SIZE_.
  [in,out] | pDigest | Pointer to the memory area that contains/receives the (intermediate) hash digest, allocated by the caller, see MCUXCLCSS_HASH_STATE_SIZE_.
  [in] | pCallback | Callback function to load data into Sha core.
  [in,out] | pCallerData | Pointer forwarded by the operation to the callback function.

The properties of some parameters change with respect to selected options.

Parameter properties
  `options.hashini` == MCUXCLCSS_HASH_INIT_ENABLE

    `options.hashld` has no effect and shall be MCUXCLCSS_HASH_LOAD_DISABLE. No data is read from `pDigest`.

  `options.hashld` == MCUXCLCSS_HASH_LOAD_DISABLE

    `pDigest` is not expected to contain an initial state. No data is read from `pDigest`.

  `options.hashoe` == MCUXCLCSS_HASH_OUTPUT_ENABLE

    The hash state is written to `pDigest`. The size varies depending on the choice of `options.hashmd`, for more information see MCUXCLCSS_HASH_STATE_SIZE_ . In cases where the state size and output size differ - see MCUXCLCSS_HASH_OUTPUT_SIZE_ -, the state must be truncated by the caller to obtain the final hash value.

  `pCallback` != `NULL`
    The callback function referenced by `pCallback` is called. Otherwise, the function uses a default implementation for the copy.

Returns
  An error code that can be any error code in MCUXCLCSS_STATUS_, see individual documentation for more information

Return values

  MCUXCLCSS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified
  MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request
  MCUXCLCSS_STATUS_SW_FAULT | if the callback returned an error
  MCUXCLCSS_STATUS_OK | on success

Examples
  hash_sha256_sha_direct_one_block.c, and hash_sha384_sha_direct_one_block.c.