The Cryptographic hash related functions API provides functionality to create hash digests from arbitrary input data using cryptographic hash functions.

Detailed description

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:

Must be deterministic - the same input must give the same output.
Is designed to be fast to calculate.
Must be a one-way function - it must be impossible to go from a hash digest back to the original input.
Single change in input data should have big impact - hash digest should have a "good distribution".
Should not collide - two messages cannot have the same digest.

Supported cryptographic hash modes

The Cryptographic hash related functions API supports the following cryptographic hash functions from the SHA-2 family of cryptograhic hash algorithms:

SHA-256
SHA-512

The SHA-2 family of cryptographic hash algorithms is specified in NIST FIPS 180-4.

Cryptographic hash backend support

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.

Cryptographic hash functions
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.

Note: nrf_crypto_hash supports only selected cryptographic hash functions. Some cryptographic hash functions have not been implemented in the Cryptographic hash related functions API because they involve security risks, while others have been dropped because the algorithms are not widely used.

Prerequisites

The following are the prerequisites for running nrf_crypto_hash.

Configure the nrf_crypto frontend and enable a backend that supports the cryptographic hash algorithm required.
See Configuring nrf_crypto frontend and backends for details on configuring nrf_crypto.
Initialize the nrf_crypto library by running nrf_crypto_init.

Example main-function

ret_code_t err_code;

// Initialize nrf_crypto

err_code = nrf_crypto_init();

VERIFY_SUCCESS(err_code);

// The nrf_crypto_hash API is now ready to be used.

Usage

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.

Selecting Cryptographic hash algorithm

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.

Note: If there are no enabled nrf_crypto backends that support the given mode, then no globally accessible info structure is available.

Configuring SHA-256 using g_nrf_crypto_hash_sha256_info
ret_code_t err_code;
static nrf_crypto_hash_context_t hash_context;
// Initializing hash_context to use the SHA-256 algorithm
err_code = nrf_crypto_hash_init(&hash_context, &g_nrf_crypto_hash_sha256_info);
APP_ERROR_CHECK(err_code);

Hash calculation with init, update, and finalize

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.

Note: The prerequisites outlined in Prerequisites must be met before the nrf_crypto_hash APIs can be used.

Example of hash calculation using init, update, and finalize
ret_code_t err_code;
static nrf_crypto_hash_context_t hash_context;
static nrf_crypto_hash_sha256_digest_t hash_digest;
uint32_t digest_size = sizeof(hash_digest);
// Initialize the hash context 
err_code = nrf_crypto_hash_init(&hash_context, &g_nrf_crypto_hash_sha256_info);
APP_ERROR_CHECK(err_code);
// Run the update function (this can be run multiple times if the data 
// is accessible in smaller chunks, e.g. when received on-air).
err_code = nrf_crypto_hash_update(&hash_context, message, message_len);
APP_ERROR_CHECK(err_code);
// Run the finalize when all data has been fed to the update function.
// This gives you the result in hash_digest
err_code = nrf_crypto_hash_finalize(&hash_context, hash_digest, &digest_size);
APP_ERROR_CHECK(err_code);

Note: The hash_context structure must be retained in RAM throughout all the calls to nrf_crypto_hash_update and the final call to nrf_crypto_hash_finalize.

Warning: CC310 requires storing the input data in RAM. This is caused by the fact that CC310 communicates with the shared memory by using DMA access.

Hash calculation with integrated function

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.

Note: The prerequisites outlined in Prerequisites must be met before the nrf_crypto_hash API can be used.

Example of hash calculation using the integrated version
ret_code_t err_code;
static nrf_crypto_hash_context_t hash_context;
static nrf_crypto_hash_sha256_digest_t hash_digest;
uint32_t digest_size = sizeof(hash_digest);
err_code = nrf_crypto_hash_calculate(
 &hash_context, // Context
 &g_nrf_crypto_hash_sha256_info, // Info structure
 message, // Input buffer
 message_size, // Input size
 hash_digest, // Result buffer
 &digest_size); // Result size
APP_ERROR_CHECK(err_code);

Warning: CC310 requires storing the input data in RAM. This is caused by the fact that CC310 communicates with the shared memory by using DMA access.

Dynamic memory management

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.

API documentation

For API documentation, see Cryptographic hash related functions.

Usage example

For an example application that shows the usage of SHA-256, see Hash Example.

Verification example

For an example showing the verification procedure of SHA-256, see Test Example.