The Cryptographic hash related functions API provides functionality to create hash digests from arbitrary input data using cryptographic hash functions.
A hash function is any function that can be used to map data of arbitrary size to data of a fixed size. A special class of this are cryptographic hash functions which are supported by the Cryptographic hash related functions API.
A cryptographic hash function is designed according to the following criteria:
The Cryptographic hash related functions API supports the following cryptographic hash functions from the SHA-2 family of cryptograhic hash algorithms:
The SHA-2 family of cryptographic hash algorithms is specified in NIST FIPS 180-4.
Different level of support is provided by the available nrf_crypto backends. The following table shows the supported mode for a given nrf_crypto backend.
Mode | nrf_cc310 | nrf_oberon | mbedtls | nrf_sw |
---|---|---|---|---|
SHA-256 | | | | |
SHA-512 | | | | |
For information on configuring the correct backend, see Enabling an nrf_crypto backend.
The following are the prerequisites for running nrf_crypto_hash.
There are two ways to use the Cryptographic hash related functions API, either by using nrf_crypto_hash_init, nrf_crypto_hash_update, and nrf_crypto_hash_finalize or through nrf_crypto_hash_calculate. The latter option does init, update, and finalize operations in a single integrated step.
When initializing the context or when running a hash calculation using the integrated function, one of the arguments is an info structure that contains information about the hash algorithm to use. Such structure is available as a constant variable in the system. The two available info structures are g_nrf_crypto_hash_sha256_info and g_nrf_crypto_hash_sha512_info.
If the data to be used in a hash calculation is available in smaller chunks, it is possible to initialize first using nrf_crypto_hash_init, and then call nrf_crypto_hash_update multiple times before running nrf_crypto_hash_finalize to get the result.
If all data is available at the time of the call, it is possible to use the integrated version of the hash function. By calling nrf_crypto_hash_calculate, the init, update, and finalize operations are done in a single integrated step.
Some of the nrf_crypto_hash APIs support dynamic memory allocation (on stack or through a memory management). These APIs allow for sending in NULL as input instead of the allocated memory. For details, see Memory management in nrf_crypto.
For API documentation, see Cryptographic hash related functions.
For an example application that shows the usage of SHA-256, see Hash Example.
For an example showing the verification procedure of SHA-256, see Test Example.