mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-11-03 20:33:16 +03:00
ec1eff386c
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>
152 lines
7.6 KiB
C
152 lines
7.6 KiB
C
/*
|
|
* PSA AEAD driver entry points
|
|
*/
|
|
/*
|
|
* 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_AEAD_H
|
|
#define PSA_CRYPTO_AEAD_H
|
|
|
|
#include <psa/crypto.h>
|
|
|
|
/**
|
|
* \brief Process an authenticated encryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_encrypt entry point. This function behaves as an aead_encrypt
|
|
* 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 context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param alg The AEAD algorithm to compute.
|
|
* \param[in] nonce Nonce or IV to use.
|
|
* \param nonce_length Size of the nonce buffer in bytes. This must
|
|
* be appropriate for the selected algorithm.
|
|
* The default nonce size is
|
|
* PSA_AEAD_NONCE_LENGTH(key_type, alg) where
|
|
* key_type is the type of key.
|
|
* \param[in] additional_data Additional data that will be authenticated
|
|
* but not encrypted.
|
|
* \param additional_data_length Size of additional_data in bytes.
|
|
* \param[in] plaintext Data that will be authenticated and encrypted.
|
|
* \param plaintext_length Size of plaintext in bytes.
|
|
* \param[out] ciphertext Output buffer for the authenticated and
|
|
* encrypted data. The additional data is not
|
|
* part of this output. For algorithms where the
|
|
* encrypted data and the authentication tag are
|
|
* defined as separate outputs, the
|
|
* authentication tag is appended to the
|
|
* encrypted data.
|
|
* \param ciphertext_size Size of the ciphertext buffer in bytes. This
|
|
* must be appropriate for the selected algorithm
|
|
* and key:
|
|
* - A sufficient output size is
|
|
* PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg,
|
|
* plaintext_length) where key_type is the type
|
|
* of key.
|
|
* - PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(
|
|
* plaintext_length) evaluates to the maximum
|
|
* ciphertext size of any supported AEAD
|
|
* encryption.
|
|
* \param[out] ciphertext_length On success, the size of the output in the
|
|
* ciphertext buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS Success.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p alg is not supported.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* ciphertext_size is too small.
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_encrypt(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *nonce, size_t nonce_length,
|
|
const uint8_t *additional_data, size_t additional_data_length,
|
|
const uint8_t *plaintext, size_t plaintext_length,
|
|
uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length);
|
|
|
|
/**
|
|
* \brief Process an authenticated decryption operation.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* aead_decrypt entry point. This function behaves as an aead_decrypt
|
|
* 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 context.
|
|
* \param key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param alg The AEAD algorithm to compute.
|
|
* \param[in] nonce Nonce or IV to use.
|
|
* \param nonce_length Size of the nonce buffer in bytes. This must
|
|
* be appropriate for the selected algorithm.
|
|
* The default nonce size is
|
|
* PSA_AEAD_NONCE_LENGTH(key_type, alg) where
|
|
* key_type is the type of key.
|
|
* \param[in] additional_data Additional data that has been authenticated
|
|
* but not encrypted.
|
|
* \param additional_data_length Size of additional_data in bytes.
|
|
* \param[in] ciphertext Data that has been authenticated and
|
|
* encrypted. For algorithms where the encrypted
|
|
* data and the authentication tag are defined
|
|
* as separate inputs, the buffer contains
|
|
* encrypted data followed by the authentication
|
|
* tag.
|
|
* \param ciphertext_length Size of ciphertext in bytes.
|
|
* \param[out] plaintext Output buffer for the decrypted data.
|
|
* \param plaintext_size Size of the plaintext buffer in bytes. This
|
|
* must be appropriate for the selected algorithm
|
|
* and key:
|
|
* - A sufficient output size is
|
|
* PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg,
|
|
* ciphertext_length) where key_type is the
|
|
* type of key.
|
|
* - PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(
|
|
* ciphertext_length) evaluates to the maximum
|
|
* plaintext size of any supported AEAD
|
|
* decryption.
|
|
* \param[out] plaintext_length On success, the size of the output in the
|
|
* plaintext buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS Success.
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
|
* The cipher is not authentic.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p alg is not supported.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* plaintext_size is too small.
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
*/
|
|
psa_status_t mbedtls_psa_aead_decrypt(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *nonce, size_t nonce_length,
|
|
const uint8_t *additional_data, size_t additional_data_length,
|
|
const uint8_t *ciphertext, size_t ciphertext_length,
|
|
uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length);
|
|
|
|
#endif /* PSA_CRYPTO_AEAD_H */
|