269 lines
14 KiB
C
269 lines
14 KiB
C
/**
|
|
* Copyright (c) 2018 - 2020, Nordic Semiconductor ASA
|
|
*
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without modification,
|
|
* are permitted provided that the following conditions are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright notice, this
|
|
* list of conditions and the following disclaimer.
|
|
*
|
|
* 2. Redistributions in binary form, except as embedded into a Nordic
|
|
* Semiconductor ASA integrated circuit in a product or a software update for
|
|
* such product, must reproduce the above copyright notice, this list of
|
|
* conditions and the following disclaimer in the documentation and/or other
|
|
* materials provided with the distribution.
|
|
*
|
|
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
|
|
* contributors may be used to endorse or promote products derived from this
|
|
* software without specific prior written permission.
|
|
*
|
|
* 4. This software, with or without modification, must only be used with a
|
|
* Nordic Semiconductor ASA integrated circuit.
|
|
*
|
|
* 5. Any software provided in binary form under this license must not be reverse
|
|
* engineered, decompiled, modified and/or disassembled.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
|
|
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
|
|
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
*/
|
|
|
|
#ifndef NRF_CRYPTO_HASH_H__
|
|
#define NRF_CRYPTO_HASH_H__
|
|
|
|
/** @file
|
|
*
|
|
* @defgroup nrf_crypto_hash Cryptographic hash related functions
|
|
* @{
|
|
* @ingroup nrf_crypto
|
|
*
|
|
* @brief Provides cryptographic hash related functionality through nrf_crypto.
|
|
*/
|
|
|
|
#include <stdint.h>
|
|
#include "nrf_crypto_types.h"
|
|
#include "nrf_crypto_hash_shared.h"
|
|
#include "nrf_crypto_hash_backend.h"
|
|
#include "app_util.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**@brief External variable declaration to info structure for SHA-256
|
|
*
|
|
* @note The variable is defined in the nrf_crypto backend that is
|
|
* enabled in the @ref sdk_config.
|
|
*
|
|
*/
|
|
extern const nrf_crypto_hash_info_t g_nrf_crypto_hash_sha256_info;
|
|
|
|
|
|
/**@brief External variable declaration to info structure for SHA-512
|
|
*
|
|
* @note The variable is defined in the nrf_crypto backend that is
|
|
* enabled in the @ref sdk_config.
|
|
*
|
|
*/
|
|
extern const nrf_crypto_hash_info_t g_nrf_crypto_hash_sha512_info;
|
|
|
|
|
|
/**
|
|
* @brief Context type for Hash.
|
|
*
|
|
* @note The size of this type is scaled for the largest Hash backend context that is
|
|
* enabled in @ref sdk_config.
|
|
*/
|
|
typedef nrf_crypto_backend_hash_context_t nrf_crypto_hash_context_t;
|
|
|
|
|
|
/** @brief Type definition for an array holding a SHA-256 hash digest. */
|
|
typedef uint8_t nrf_crypto_hash_sha256_digest_t[NRF_CRYPTO_HASH_SIZE_SHA256];
|
|
|
|
|
|
/** @brief Type definition for an array holding a SHA-512 hash digest. */
|
|
typedef uint8_t nrf_crypto_hash_sha512_digest_t[NRF_CRYPTO_HASH_SIZE_SHA512];
|
|
|
|
|
|
/**@brief Function for initializing the context structure required to compute a hash digest from
|
|
* arbitrary input data.
|
|
*
|
|
* @note The context structure is assumed to be an opaque type defined by the
|
|
* nrf_crypto backend.
|
|
*
|
|
* @note The return codes @ref NRF_ERROR_CRYPTO_FEATURE_UNAVAILABLE and
|
|
* NRF_ERROR_CRYPTO_INTERNAL only happens in cc310 backend.
|
|
*
|
|
* @param[in,out] p_context Pointer to structure holding context information for
|
|
* the hash calculation.
|
|
* @param[in] p_info Pointer to structure holding info about the hash algorithm
|
|
* used to do the computed hash.
|
|
*
|
|
* @retval NRF_SUCCESS The hash initialization was successful.
|
|
* @retval NRF_ERROR_CRYPTO_NOT_INITIALIZED @ref nrf_crypto_init was not called prior to
|
|
* this crypto function.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NULL A NULL pointer was provided for the context
|
|
* structure.
|
|
* @retval NRF_ERROR_CRYPTO_INPUT_NULL The pointer to the info structure was NULL.
|
|
* @retval NRF_ERROR_CRYPTO_FEATURE_UNAVAILABLE The function was called with a hash mode that
|
|
* is unavailable.
|
|
* @retval NRF_ERROR_CRYPTO_INTERNAL An internal error occurred when initializing
|
|
* the constext in the nrf_crypto backend.
|
|
*/
|
|
ret_code_t nrf_crypto_hash_init(nrf_crypto_hash_context_t * const p_context,
|
|
nrf_crypto_hash_info_t const * p_info);
|
|
|
|
|
|
/**@brief Function for updating the hash calculation with partial arbitrary data.
|
|
*
|
|
* @details This function should be called one or more times until all arbituary input data
|
|
* required for the hash calcuation is provided.
|
|
*
|
|
* @note @ref nrf_crypto_hash_init must be called prior to this function to configure the
|
|
* context structure used as input parameter to this function.
|
|
*
|
|
* @note @ref nrf_crypto_hash_finalize must be called after all arbitruary input data
|
|
* has been provided to get the calculated hash digest.
|
|
*
|
|
* @note The context object is assumed to be an opaque type defined by the
|
|
* nrf_crypto backend.
|
|
*
|
|
* @note The return values @ref NRF_ERROR_CRYPTO_BUSY, @ref NRF_ERROR_CRYPTO_INPUT_LOCATION
|
|
* and @ref NRF_ERROR_CRYPTO_INPUT_LOCATION can only occur in CC310 backend.
|
|
*
|
|
* @param[in,out] p_context Pointer to structure holding context information for
|
|
* the hash calculation.
|
|
* @param[in] p_data Pointer to data to be hashed.
|
|
* @param[in] data_size Length of the data to be hashed.
|
|
*
|
|
* @retval NRF_SUCCESS The hash digest was computed successfully.
|
|
* @retval NRF_ERROR_CRYPTO_NOT_INITIALIZED @ref nrf_crypto_init was not called prior to
|
|
* this crypto function.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED The context was not initialized prior to
|
|
* this call or it was corrupted. Please call
|
|
* @ref nrf_crypto_hash_init to initialize it.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NULL A NULL pointer was provided for the context
|
|
* structure.
|
|
* @retval NRF_ERROR_CRYPTO_INPUT_NULL p_data was NULL.
|
|
* @retval NRF_ERROR_CRYPTO_INPUT_LOCATION Input data not in RAM.
|
|
* @retval NRF_ERROR_CRYPTO_BUSY The function could not be called because the
|
|
* nrf_crypto backend was busy. Please rerun the
|
|
* cryptographic routine at a later time.
|
|
* @retval NRF_ERROR_CRYPTO_INTERNAL An internal error occurred in the nrf_crypto
|
|
* backend.
|
|
*/
|
|
ret_code_t nrf_crypto_hash_update(nrf_crypto_hash_context_t * const p_context,
|
|
uint8_t const * p_data,
|
|
size_t data_size);
|
|
|
|
/**@brief Function for finalizing computation of a hash digest from arbitrary data.
|
|
*
|
|
* @details This function is called to get the calculated
|
|
*
|
|
* @note @ref nrf_crypto_hash_init must be called prior to this function to configure the
|
|
* context structure used as input parameter to this function.
|
|
*
|
|
* @note The input data for the calculated hash digest must be provided by calling
|
|
* @ref nrf_crypto_hash_update one or more times.
|
|
*
|
|
* @note The context object is assumed to be an opaque type defined by the
|
|
* nrf_crypto backend.
|
|
*
|
|
* @note The return values @ref NRF_ERROR_CRYPTO_BUSY and @ref NRF_ERROR_CRYPTO_INPUT_LOCATION
|
|
* can only occur in CC310 backend.
|
|
*
|
|
*
|
|
* @param[in] p_context Pointer to structure holding context information for
|
|
* the hash calculation.
|
|
* @param[out] p_digest Pointer to buffer holding the calculated hash digest.
|
|
* @param[in,out] p_digest_size Pointer to a variable holding the length of the calculated hash.
|
|
* Set this to the length of buffer that p_digest is pointing to.
|
|
*
|
|
* @retval NRF_SUCCESS The hash digest was computed successfully.
|
|
* @retval NRF_ERROR_CRYPTO_NOT_INITIALIZED @ref nrf_crypto_init was not called prior to
|
|
* this crypto function.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED The context was not initialized prior to
|
|
* this call or it was corrupted. Please call
|
|
* @ref nrf_crypto_hash_init to initialize it.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NULL A NULL pointer was provided for the context
|
|
* structure.
|
|
* @retval NRF_ERROR_CRYPTO_OUTPUT_NULL p_digest or p_digest_size was NULL.
|
|
* @retval NRF_ERROR_CRYPTO_OUTPUT_LENGTH The length of p_digest was too small for
|
|
* the hash digest result.
|
|
* @retval NRF_ERROR_CRYPTO_BUSY The function could not be called because the
|
|
* nrf_crypto backend was busy. Please rerun the
|
|
* cryptographic routine at a later time.
|
|
* @retval NRF_ERROR_CRYPTO_INTERNAL An internal error occurred in the nrf_crypto
|
|
* backend.
|
|
*/
|
|
ret_code_t nrf_crypto_hash_finalize(nrf_crypto_hash_context_t * const p_context,
|
|
uint8_t * p_digest,
|
|
size_t * const p_digest_size);
|
|
|
|
|
|
/**@brief Function for computing a hash from arbitrary data in a single integrated step.
|
|
*
|
|
* @details This function calculates the hash digest from arbitruary data in a single integrated step.
|
|
* This means calling init, update and finalize in one step.
|
|
*
|
|
* @note The context object is assumed to be an opaque type defined by the
|
|
* nrf_crypto backend.
|
|
*
|
|
* @note The return values @ref NRF_ERROR_CRYPTO_BUSY, @ref NRF_ERROR_CRYPTO_INPUT_LOCATION
|
|
* and @ref NRF_ERROR_CRYPTO_INPUT_LOCATION can only occur in CC310 backend.
|
|
*
|
|
* @param[in,out] p_context Pointer to structure holding context information for
|
|
* the hash calculation. If this
|
|
* is set to NULL, it will be allocated by the user configurable
|
|
* allocate/free function @ref NRF_CRYPTO_ALLOC and
|
|
* @ref NRF_CRYPTO_FREE.
|
|
* @param[in] p_info Pointer to structure holding info about hash algorithm
|
|
* for the computed hash.
|
|
* @param[in] p_data Pointer to data to be hashed.
|
|
* @param[in] data_size Length of the data to be hashed.
|
|
* @param[out] p_digest Pointer to buffer holding the calculated hash digest.
|
|
* @param[in,out] p_digest_size Pointer to a variable holding the length of the calculated hash.
|
|
* Set this to the length of buffer that p_digest is pointing to.
|
|
*
|
|
* @retval NRF_SUCCESS The hash initialization was successful.
|
|
* @retval NRF_ERROR_CRYPTO_NOT_INITIALIZED @ref nrf_crypto_init was not called prior to
|
|
* this crypto function.
|
|
* @retval NRF_ERROR_CRYPTO_CONTEXT_NULL A NULL pointer was provided for the context
|
|
* structure.
|
|
* @retval NRF_ERROR_CRYPTO_INPUT_NULL p_info or p_data was NULL.
|
|
* @retval NRF_ERROR_CRYPTO_INPUT_LOCATION Input data not in RAM.
|
|
* @retval NRF_ERROR_CRYPTO_OUTPUT_NULL p_digest or p_digest_size was NULL.
|
|
* @retval NRF_ERROR_CRYPTO_OUTPUT_LENGTH The length of p_digest was too small for
|
|
* the hash digest result.
|
|
* @retval NRF_ERROR_CRYPTO_BUSY The function could not be called because the
|
|
* nrf_crypto backend was busy. Please rerun the
|
|
* cryptographic routine at a later time.
|
|
* @retval NRF_ERROR_CRYPTO_ALLOC_FAILED Unable to allocate memory for the context.
|
|
* @retval NRF_ERROR_CRYPTO_INTERNAL An internal error occurred in the nrf_crypto
|
|
* backend.
|
|
*/
|
|
ret_code_t nrf_crypto_hash_calculate(nrf_crypto_hash_context_t * const p_context,
|
|
nrf_crypto_hash_info_t const * p_info,
|
|
uint8_t const * p_data,
|
|
size_t data_size,
|
|
uint8_t * p_digest,
|
|
size_t * const p_digest_size);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/**@} */
|
|
|
|
#endif // NRF_CRYPTO_HASH_H__
|