MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClCss_Hash_Functions

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]optionsThe command options. For more information, see mcuxClCss_HashOption_t.
[in]pInputPadded input data to be hashed
[in]inputLengthSize 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]pDigestPointer 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_PARAMif invalid parameters were specified
MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLCSS_STATUS_OK_WAITon 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_INTERRUPTif a running operation prevented the request
MCUXCLCSS_STATUS_OKon 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_INTERRUPTif a running operation prevented the request
MCUXCLCSS_STATUS_OKon 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]optionsThe command options. For more information, see mcuxClCss_HashOption_t.
[in]pInputPadded input data to be hashed.
[in]inputLengthSize 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]pDigestPointer to the memory area that contains/receives the (intermediate) hash digest, allocated by the caller, see MCUXCLCSS_HASH_STATE_SIZE_.
[in]pCallbackCallback function to load data into Sha core.
[in,out]pCallerDataPointer 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_PARAMif invalid parameters were specified
MCUXCLCSS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLCSS_STATUS_SW_FAULTif the callback returned an error
MCUXCLCSS_STATUS_OKon success
Examples
hash_sha256_sha_direct_one_block.c, and hash_sha384_sha_direct_one_block.c.