212 lines
8.9 KiB
C++
212 lines
8.9 KiB
C++
|
/*
|
||
|
|
* PSA hashing layer on top of Mbed TLS software crypto
|
||
|
|
*/
|
||
|
|
/*
|
||
|
|
* Copyright The Mbed TLS Contributors
|
||
|
|
* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef PSA_CRYPTO_HASH_H
|
||
|
|
#define PSA_CRYPTO_HASH_H
|
||
|
|
|
||
|
|
#include <psa/crypto.h>
|
||
|
|
|
||
|
|
/** Calculate the hash (digest) of a message using Mbed TLS routines.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_compute
|
||
|
|
* entry point. This function behaves as a hash_compute entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
|
||
|
|
* such that #PSA_ALG_IS_HASH(\p alg) is true).
|
||
|
|
* \param[in] input Buffer containing the message to hash.
|
||
|
|
* \param input_length Size of the \p input buffer in bytes.
|
||
|
|
* \param[out] hash Buffer where the hash is to be written.
|
||
|
|
* \param hash_size Size of the \p hash buffer in bytes.
|
||
|
|
* \param[out] hash_length On success, the number of bytes
|
||
|
|
* that make up the hash value. This is always
|
||
|
|
* #PSA_HASH_LENGTH(\p alg).
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
|
|
* \p alg is not supported
|
||
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||
|
|
* \p hash_size is too small
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_compute(
|
||
|
|
psa_algorithm_t alg,
|
||
|
|
const uint8_t *input,
|
||
|
|
size_t input_length,
|
||
|
|
uint8_t *hash,
|
||
|
|
size_t hash_size,
|
||
|
|
size_t *hash_length);
|
||
|
|
|
||
|
|
/** Set up a multipart hash operation using Mbed TLS routines.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_setup
|
||
|
|
* entry point. This function behaves as a hash_setup entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* If an error occurs at any step after a call to mbedtls_psa_hash_setup(), the
|
||
|
|
* operation will need to be reset by a call to mbedtls_psa_hash_abort(). The
|
||
|
|
* core may call mbedtls_psa_hash_abort() at any time after the operation
|
||
|
|
* has been initialized.
|
||
|
|
*
|
||
|
|
* After a successful call to mbedtls_psa_hash_setup(), the core must
|
||
|
|
* eventually terminate the operation. The following events terminate an
|
||
|
|
* operation:
|
||
|
|
* - A successful call to mbedtls_psa_hash_finish() or mbedtls_psa_hash_verify().
|
||
|
|
* - A call to mbedtls_psa_hash_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation The operation object to set up. It must have
|
||
|
|
* been initialized to all-zero and not yet be in use.
|
||
|
|
* \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
|
||
|
|
* such that #PSA_ALG_IS_HASH(\p alg) is true).
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
|
|
* \p alg is not supported
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be inactive).
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_setup(
|
||
|
|
mbedtls_psa_hash_operation_t *operation,
|
||
|
|
psa_algorithm_t alg);
|
||
|
|
|
||
|
|
/** Clone an Mbed TLS hash operation.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_clone
|
||
|
|
* entry point. This function behaves as a hash_clone entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* This function copies the state of an ongoing hash operation to
|
||
|
|
* a new operation object. In other words, this function is equivalent
|
||
|
|
* to calling mbedtls_psa_hash_setup() on \p target_operation with the same
|
||
|
|
* algorithm that \p source_operation was set up for, then
|
||
|
|
* mbedtls_psa_hash_update() on \p target_operation with the same input that
|
||
|
|
* that was passed to \p source_operation. After this function returns, the
|
||
|
|
* two objects are independent, i.e. subsequent calls involving one of
|
||
|
|
* the objects do not affect the other object.
|
||
|
|
*
|
||
|
|
* \param[in] source_operation The active hash operation to clone.
|
||
|
|
* \param[in,out] target_operation The operation object to set up.
|
||
|
|
* It must be initialized but not active.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS \emptydescription
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The \p source_operation state is not valid (it must be active).
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The \p target_operation state is not valid (it must be inactive).
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_clone(
|
||
|
|
const mbedtls_psa_hash_operation_t *source_operation,
|
||
|
|
mbedtls_psa_hash_operation_t *target_operation);
|
||
|
|
|
||
|
|
/** Add a message fragment to a multipart Mbed TLS hash operation.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_update
|
||
|
|
* entry point. This function behaves as a hash_update entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* The application must call mbedtls_psa_hash_setup() before calling this function.
|
||
|
|
*
|
||
|
|
* If this function returns an error status, the operation enters an error
|
||
|
|
* state and must be aborted by calling mbedtls_psa_hash_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Active hash operation.
|
||
|
|
* \param[in] input Buffer containing the message fragment to hash.
|
||
|
|
* \param input_length Size of the \p input buffer in bytes.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be active).
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_update(
|
||
|
|
mbedtls_psa_hash_operation_t *operation,
|
||
|
|
const uint8_t *input,
|
||
|
|
size_t input_length);
|
||
|
|
|
||
|
|
/** Finish the calculation of the Mbed TLS-calculated hash of a message.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_finish
|
||
|
|
* entry point. This function behaves as a hash_finish entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* The application must call mbedtls_psa_hash_setup() before calling this function.
|
||
|
|
* This function calculates the hash of the message formed by concatenating
|
||
|
|
* the inputs passed to preceding calls to mbedtls_psa_hash_update().
|
||
|
|
*
|
||
|
|
* When this function returns successfully, the operation becomes inactive.
|
||
|
|
* If this function returns an error status, the operation enters an error
|
||
|
|
* state and must be aborted by calling mbedtls_psa_hash_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Active hash operation.
|
||
|
|
* \param[out] hash Buffer where the hash is to be written.
|
||
|
|
* \param hash_size Size of the \p hash buffer in bytes.
|
||
|
|
* \param[out] hash_length On success, the number of bytes
|
||
|
|
* that make up the hash value. This is always
|
||
|
|
* #PSA_HASH_LENGTH(\c alg) where \c alg is the
|
||
|
|
* hash algorithm that is calculated.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be active).
|
||
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||
|
|
* The size of the \p hash buffer is too small. You can determine a
|
||
|
|
* sufficient buffer size by calling #PSA_HASH_LENGTH(\c alg)
|
||
|
|
* where \c alg is the hash algorithm that is calculated.
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_finish(
|
||
|
|
mbedtls_psa_hash_operation_t *operation,
|
||
|
|
uint8_t *hash,
|
||
|
|
size_t hash_size,
|
||
|
|
size_t *hash_length);
|
||
|
|
|
||
|
|
/** Abort an Mbed TLS hash operation.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver hash_abort
|
||
|
|
* entry point. This function behaves as a hash_abort entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* Aborting an operation frees all associated resources except for the
|
||
|
|
* \p operation structure itself. Once aborted, the operation object
|
||
|
|
* can be reused for another operation by calling
|
||
|
|
* mbedtls_psa_hash_setup() again.
|
||
|
|
*
|
||
|
|
* You may call this function any time after the operation object has
|
||
|
|
* been initialized by one of the methods described in #psa_hash_operation_t.
|
||
|
|
*
|
||
|
|
* In particular, calling mbedtls_psa_hash_abort() after the operation has been
|
||
|
|
* terminated by a call to mbedtls_psa_hash_abort(), mbedtls_psa_hash_finish() or
|
||
|
|
* mbedtls_psa_hash_verify() is safe and has no effect.
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Initialized hash operation.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_hash_abort(
|
||
|
|
mbedtls_psa_hash_operation_t *operation);
|
||
|
|
|
||
|
|
#endif /* PSA_CRYPTO_HASH_H */
|