265 lines
12 KiB
C++
265 lines
12 KiB
C++
|
/*
|
||
|
|
* PSA MAC 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_MAC_H
|
||
|
|
#define PSA_CRYPTO_MAC_H
|
||
|
|
|
||
|
|
#include <psa/crypto.h>
|
||
|
|
|
||
|
|
/** Calculate the MAC (message authentication code) of a message using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver mac_compute
|
||
|
|
* entry point. This function behaves as a mac_compute entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* \param[in] attributes The attributes of the key to use for the
|
||
|
|
* operation.
|
||
|
|
* \param[in] key_buffer The buffer containing the key to use for
|
||
|
|
* computing the MAC. This buffer contains the key
|
||
|
|
* in export representation as defined by
|
||
|
|
* psa_export_key() (i.e. the raw key bytes).
|
||
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
||
|
|
* \param alg The MAC algorithm to use (\c PSA_ALG_XXX value
|
||
|
|
* such that #PSA_ALG_IS_MAC(\p alg) is true).
|
||
|
|
* \param[in] input Buffer containing the input message.
|
||
|
|
* \param input_length Size of the \p input buffer in bytes.
|
||
|
|
* \param[out] mac Buffer where the MAC value is to be written.
|
||
|
|
* \param mac_size Size of the \p mac buffer in bytes.
|
||
|
|
* \param[out] mac_length On success, the number of bytes
|
||
|
|
* that make up the MAC value.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
|
|
* \p alg is not supported.
|
||
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||
|
|
* \p mac_size is too small
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_compute(
|
||
|
|
const psa_key_attributes_t *attributes,
|
||
|
|
const uint8_t *key_buffer,
|
||
|
|
size_t key_buffer_size,
|
||
|
|
psa_algorithm_t alg,
|
||
|
|
const uint8_t *input,
|
||
|
|
size_t input_length,
|
||
|
|
uint8_t *mac,
|
||
|
|
size_t mac_size,
|
||
|
|
size_t *mac_length);
|
||
|
|
|
||
|
|
/** Set up a multipart MAC calculation operation using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver mac_sign_setup
|
||
|
|
* entry point. This function behaves as a mac_sign_setup entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* \param[in,out] operation The operation object to set up. It must have
|
||
|
|
* been initialized and not yet in use.
|
||
|
|
* \param[in] attributes The attributes of the key to use for the
|
||
|
|
* operation.
|
||
|
|
* \param[in] key_buffer The buffer containing the key to use for
|
||
|
|
* computing the MAC. This buffer contains the key
|
||
|
|
* in export representation as defined by
|
||
|
|
* psa_export_key() (i.e. the raw key bytes).
|
||
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
||
|
|
* \param alg The MAC algorithm to use (\c PSA_ALG_XXX value
|
||
|
|
* such that #PSA_ALG_IS_MAC(\p alg) is true).
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
|
|
* \p alg is not supported.
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be inactive).
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_sign_setup(
|
||
|
|
mbedtls_psa_mac_operation_t *operation,
|
||
|
|
const psa_key_attributes_t *attributes,
|
||
|
|
const uint8_t *key_buffer,
|
||
|
|
size_t key_buffer_size,
|
||
|
|
psa_algorithm_t alg);
|
||
|
|
|
||
|
|
/** Set up a multipart MAC verification operation using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver mac_verify_setup
|
||
|
|
* entry point. This function behaves as a mac_verify_setup entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* \param[in,out] operation The operation object to set up. It must have
|
||
|
|
* been initialized and not yet in use.
|
||
|
|
* \param[in] attributes The attributes of the key to use for the
|
||
|
|
* operation.
|
||
|
|
* \param[in] key_buffer The buffer containing the key to use for
|
||
|
|
* computing the MAC. This buffer contains the key
|
||
|
|
* in export representation as defined by
|
||
|
|
* psa_export_key() (i.e. the raw key bytes).
|
||
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
||
|
|
* \param alg The MAC algorithm to use (\c PSA_ALG_XXX value
|
||
|
|
* such that #PSA_ALG_IS_MAC(\p alg) is true).
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
||
|
|
* \p alg is not supported.
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be inactive).
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_verify_setup(
|
||
|
|
mbedtls_psa_mac_operation_t *operation,
|
||
|
|
const psa_key_attributes_t *attributes,
|
||
|
|
const uint8_t *key_buffer,
|
||
|
|
size_t key_buffer_size,
|
||
|
|
psa_algorithm_t alg);
|
||
|
|
|
||
|
|
/** Add a message fragment to a multipart MAC operation using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver mac_update
|
||
|
|
* entry point. This function behaves as a mac_update entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* The PSA core calls mbedtls_psa_mac_sign_setup() or
|
||
|
|
* mbedtls_psa_mac_verify_setup() before calling this function.
|
||
|
|
*
|
||
|
|
* If this function returns an error status, the PSA core aborts the
|
||
|
|
* operation by calling mbedtls_psa_mac_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Active MAC operation.
|
||
|
|
* \param[in] input Buffer containing the message fragment to add to
|
||
|
|
* the MAC calculation.
|
||
|
|
* \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_mac_update(
|
||
|
|
mbedtls_psa_mac_operation_t *operation,
|
||
|
|
const uint8_t *input,
|
||
|
|
size_t input_length);
|
||
|
|
|
||
|
|
/** Finish the calculation of the MAC of a message using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver mac_sign_finish
|
||
|
|
* entry point. This function behaves as a mac_sign_finish entry point as
|
||
|
|
* defined in the PSA driver interface specification for transparent
|
||
|
|
* drivers.
|
||
|
|
*
|
||
|
|
* The PSA core calls mbedtls_psa_mac_sign_setup() before calling this function.
|
||
|
|
* This function calculates the MAC of the message formed by concatenating
|
||
|
|
* the inputs passed to preceding calls to mbedtls_psa_mac_update().
|
||
|
|
*
|
||
|
|
* Whether this function returns successfully or not, the PSA core subsequently
|
||
|
|
* aborts the operation by calling mbedtls_psa_mac_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Active MAC operation.
|
||
|
|
* \param[out] mac Buffer where the MAC value is to be written.
|
||
|
|
* \param mac_size Output size requested for the MAC algorithm. The PSA
|
||
|
|
* core guarantees this is a valid MAC length for the
|
||
|
|
* algorithm and key combination passed to
|
||
|
|
* mbedtls_psa_mac_sign_setup(). It also guarantees the
|
||
|
|
* \p mac buffer is large enough to contain the
|
||
|
|
* requested output size.
|
||
|
|
* \param[out] mac_length On success, the number of bytes output to buffer
|
||
|
|
* \p mac, which will be equal to the requested length
|
||
|
|
* \p mac_size.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* Success.
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be an active mac sign
|
||
|
|
* operation).
|
||
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
||
|
|
* The size of the \p mac buffer is too small. A sufficient buffer size
|
||
|
|
* can be determined by calling PSA_MAC_LENGTH().
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_sign_finish(
|
||
|
|
mbedtls_psa_mac_operation_t *operation,
|
||
|
|
uint8_t *mac,
|
||
|
|
size_t mac_size,
|
||
|
|
size_t *mac_length);
|
||
|
|
|
||
|
|
/** Finish the calculation of the MAC of a message and compare it with
|
||
|
|
* an expected value using Mbed TLS.
|
||
|
|
*
|
||
|
|
* \note The signature of this function is that of a PSA driver
|
||
|
|
* mac_verify_finish entry point. This function behaves as a
|
||
|
|
* mac_verify_finish entry point as defined in the PSA driver interface
|
||
|
|
* specification for transparent drivers.
|
||
|
|
*
|
||
|
|
* The PSA core calls mbedtls_psa_mac_verify_setup() before calling this
|
||
|
|
* function. This function calculates the MAC of the message formed by
|
||
|
|
* concatenating the inputs passed to preceding calls to
|
||
|
|
* mbedtls_psa_mac_update(). It then compares the calculated MAC with the
|
||
|
|
* expected MAC passed as a parameter to this function.
|
||
|
|
*
|
||
|
|
* Whether this function returns successfully or not, the PSA core subsequently
|
||
|
|
* aborts the operation by calling mbedtls_psa_mac_abort().
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Active MAC operation.
|
||
|
|
* \param[in] mac Buffer containing the expected MAC value.
|
||
|
|
* \param mac_length Length in bytes of the expected MAC value. The PSA
|
||
|
|
* core guarantees that this length is a valid MAC
|
||
|
|
* length for the algorithm and key combination passed
|
||
|
|
* to mbedtls_psa_mac_verify_setup().
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS
|
||
|
|
* The expected MAC is identical to the actual MAC of the message.
|
||
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
||
|
|
* The MAC of the message was calculated successfully, but it
|
||
|
|
* differs from the expected MAC.
|
||
|
|
* \retval #PSA_ERROR_BAD_STATE
|
||
|
|
* The operation state is not valid (it must be an active mac verify
|
||
|
|
* operation).
|
||
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_verify_finish(
|
||
|
|
mbedtls_psa_mac_operation_t *operation,
|
||
|
|
const uint8_t *mac,
|
||
|
|
size_t mac_length);
|
||
|
|
|
||
|
|
/** Abort a MAC operation using Mbed TLS.
|
||
|
|
*
|
||
|
|
* 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_mac_sign_setup() or mbedtls_psa_mac_verify_setup() again.
|
||
|
|
*
|
||
|
|
* The PSA core may call this function any time after the operation object has
|
||
|
|
* been initialized by one of the methods described in
|
||
|
|
* #mbedtls_psa_mac_operation_t.
|
||
|
|
*
|
||
|
|
* In particular, calling mbedtls_psa_mac_abort() after the operation has been
|
||
|
|
* terminated by a call to mbedtls_psa_mac_abort(),
|
||
|
|
* mbedtls_psa_mac_sign_finish() or mbedtls_psa_mac_verify_finish() is safe and
|
||
|
|
* has no effect.
|
||
|
|
*
|
||
|
|
* \param[in,out] operation Initialized MAC operation.
|
||
|
|
*
|
||
|
|
* \retval #PSA_SUCCESS \emptydescription
|
||
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
||
|
|
*/
|
||
|
|
psa_status_t mbedtls_psa_mac_abort(
|
||
|
|
mbedtls_psa_mac_operation_t *operation);
|
||
|
|
|
||
|
|
#endif /* PSA_CRYPTO_MAC_H */
|