ed73355d2e
Pacify Clang >=15 which complained:
```
include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
* \retval #PSA_SUCCESS
~~~~~~~~~~~~~~~~~~~^
```
This commit performs the following systematic replacement:
```
perl -i -0777 -p -e 's/([\\@])(retval +\S+)\n(?! *\*? *([^\n \\*\/]|\\[cp]\b))/$1$2 ${1}emptydescription\n/g' $(git ls-files '*.[hc]' '*.function' '*.jinja')
```
i.e. add an `\emptydescription` argument to `\retval` commands (or
`@retval`, which we don't normally used) that are followed by a single word,
unless the next line looks like it contains text which would be the
description.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
276 lines
12 KiB
C
276 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
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
* not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#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 */
|