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>
609 lines
25 KiB
C
609 lines
25 KiB
C
/*
|
|
* PSA crypto core internal interfaces
|
|
*/
|
|
/*
|
|
* 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_CORE_H
|
|
#define PSA_CRYPTO_CORE_H
|
|
|
|
#include "mbedtls/build_info.h"
|
|
|
|
#include "psa/crypto.h"
|
|
#include "psa/crypto_se_driver.h"
|
|
|
|
/** Constant-time buffer comparison
|
|
*
|
|
* \param[in] a Left-hand buffer for comparison.
|
|
* \param[in] b Right-hand buffer for comparison.
|
|
* \param n Amount of bytes to compare.
|
|
*
|
|
* \return 0 if the buffer contents are equal, non-zero otherwise
|
|
*/
|
|
static inline int mbedtls_psa_safer_memcmp(
|
|
const uint8_t *a, const uint8_t *b, size_t n)
|
|
{
|
|
size_t i;
|
|
unsigned char diff = 0;
|
|
|
|
for (i = 0; i < n; i++) {
|
|
diff |= a[i] ^ b[i];
|
|
}
|
|
|
|
return diff;
|
|
}
|
|
|
|
/** The data structure representing a key slot, containing key material
|
|
* and metadata for one key.
|
|
*/
|
|
typedef struct {
|
|
psa_core_key_attributes_t attr;
|
|
|
|
/*
|
|
* Number of locks on the key slot held by the library.
|
|
*
|
|
* This counter is incremented by one each time a library function
|
|
* retrieves through one of the dedicated internal API a pointer to the
|
|
* key slot.
|
|
*
|
|
* This counter is decremented by one each time a library function stops
|
|
* accessing the key slot and states it by calling the
|
|
* psa_unlock_key_slot() API.
|
|
*
|
|
* This counter is used to prevent resetting the key slot while the library
|
|
* may access it. For example, such control is needed in the following
|
|
* scenarios:
|
|
* . In case of key slot starvation, all key slots contain the description
|
|
* of a key, and the library asks for the description of a persistent
|
|
* key not present in the key slots, the key slots currently accessed by
|
|
* the library cannot be reclaimed to free a key slot to load the
|
|
* persistent key.
|
|
* . In case of a multi-threaded application where one thread asks to close
|
|
* or purge or destroy a key while it is in used by the library through
|
|
* another thread.
|
|
*/
|
|
size_t lock_count;
|
|
|
|
/* Dynamically allocated key data buffer.
|
|
* Format as specified in psa_export_key(). */
|
|
struct key_data {
|
|
uint8_t *data;
|
|
size_t bytes;
|
|
} key;
|
|
} psa_key_slot_t;
|
|
|
|
/* A mask of key attribute flags used only internally.
|
|
* Currently there aren't any. */
|
|
#define PSA_KA_MASK_INTERNAL_ONLY ( \
|
|
0)
|
|
|
|
/** Test whether a key slot is occupied.
|
|
*
|
|
* A key slot is occupied iff the key type is nonzero. This works because
|
|
* no valid key can have 0 as its key type.
|
|
*
|
|
* \param[in] slot The key slot to test.
|
|
*
|
|
* \return 1 if the slot is occupied, 0 otherwise.
|
|
*/
|
|
static inline int psa_is_key_slot_occupied(const psa_key_slot_t *slot)
|
|
{
|
|
return slot->attr.type != 0;
|
|
}
|
|
|
|
/** Test whether a key slot is locked.
|
|
*
|
|
* A key slot is locked iff its lock counter is strictly greater than 0.
|
|
*
|
|
* \param[in] slot The key slot to test.
|
|
*
|
|
* \return 1 if the slot is locked, 0 otherwise.
|
|
*/
|
|
static inline int psa_is_key_slot_locked(const psa_key_slot_t *slot)
|
|
{
|
|
return slot->lock_count > 0;
|
|
}
|
|
|
|
/** Retrieve flags from psa_key_slot_t::attr::core::flags.
|
|
*
|
|
* \param[in] slot The key slot to query.
|
|
* \param mask The mask of bits to extract.
|
|
*
|
|
* \return The key attribute flags in the given slot,
|
|
* bitwise-anded with \p mask.
|
|
*/
|
|
static inline uint16_t psa_key_slot_get_flags(const psa_key_slot_t *slot,
|
|
uint16_t mask)
|
|
{
|
|
return slot->attr.flags & mask;
|
|
}
|
|
|
|
/** Set flags in psa_key_slot_t::attr::core::flags.
|
|
*
|
|
* \param[in,out] slot The key slot to modify.
|
|
* \param mask The mask of bits to modify.
|
|
* \param value The new value of the selected bits.
|
|
*/
|
|
static inline void psa_key_slot_set_flags(psa_key_slot_t *slot,
|
|
uint16_t mask,
|
|
uint16_t value)
|
|
{
|
|
slot->attr.flags = ((~mask & slot->attr.flags) |
|
|
(mask & value));
|
|
}
|
|
|
|
/** Turn on flags in psa_key_slot_t::attr::core::flags.
|
|
*
|
|
* \param[in,out] slot The key slot to modify.
|
|
* \param mask The mask of bits to set.
|
|
*/
|
|
static inline void psa_key_slot_set_bits_in_flags(psa_key_slot_t *slot,
|
|
uint16_t mask)
|
|
{
|
|
slot->attr.flags |= mask;
|
|
}
|
|
|
|
/** Turn off flags in psa_key_slot_t::attr::core::flags.
|
|
*
|
|
* \param[in,out] slot The key slot to modify.
|
|
* \param mask The mask of bits to clear.
|
|
*/
|
|
static inline void psa_key_slot_clear_bits(psa_key_slot_t *slot,
|
|
uint16_t mask)
|
|
{
|
|
slot->attr.flags &= ~mask;
|
|
}
|
|
|
|
#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
|
|
/** Get the SE slot number of a key from the key slot storing its description.
|
|
*
|
|
* \param[in] slot The key slot to query. This must be a key slot storing
|
|
* the description of a key of a dynamically registered
|
|
* secure element, otherwise the behaviour is undefined.
|
|
*/
|
|
static inline psa_key_slot_number_t psa_key_slot_get_slot_number(
|
|
const psa_key_slot_t *slot)
|
|
{
|
|
return *((psa_key_slot_number_t *) (slot->key.data));
|
|
}
|
|
#endif
|
|
|
|
/** Get the description of a key given its identifier and policy constraints
|
|
* and lock it.
|
|
*
|
|
* The key must have allow all the usage flags set in \p usage. If \p alg is
|
|
* nonzero, the key must allow operations with this algorithm. If \p alg is
|
|
* zero, the algorithm is not checked.
|
|
*
|
|
* In case of a persistent key, the function loads the description of the key
|
|
* into a key slot if not already done.
|
|
*
|
|
* On success, the returned key slot is locked. It is the responsibility of
|
|
* the caller to unlock the key slot when it does not access it anymore.
|
|
*/
|
|
psa_status_t psa_get_and_lock_key_slot_with_policy(mbedtls_svc_key_id_t key,
|
|
psa_key_slot_t **p_slot,
|
|
psa_key_usage_t usage,
|
|
psa_algorithm_t alg);
|
|
|
|
/** Completely wipe a slot in memory, including its policy.
|
|
*
|
|
* Persistent storage is not affected.
|
|
*
|
|
* \param[in,out] slot The key slot to wipe.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success. This includes the case of a key slot that was
|
|
* already fully wiped.
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
*/
|
|
psa_status_t psa_wipe_key_slot(psa_key_slot_t *slot);
|
|
|
|
/** Try to allocate a buffer to an empty key slot.
|
|
*
|
|
* \param[in,out] slot Key slot to attach buffer to.
|
|
* \param[in] buffer_length Requested size of the buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The buffer has been successfully allocated.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* Not enough memory was available for allocation.
|
|
* \retval #PSA_ERROR_ALREADY_EXISTS
|
|
* Trying to allocate a buffer to a non-empty key slot.
|
|
*/
|
|
psa_status_t psa_allocate_buffer_to_slot(psa_key_slot_t *slot,
|
|
size_t buffer_length);
|
|
|
|
/** Wipe key data from a slot. Preserves metadata such as the policy. */
|
|
psa_status_t psa_remove_key_data_from_memory(psa_key_slot_t *slot);
|
|
|
|
/** Copy key data (in export format) into an empty key slot.
|
|
*
|
|
* This function assumes that the slot does not contain
|
|
* any key material yet. On failure, the slot content is unchanged.
|
|
*
|
|
* \param[in,out] slot Key slot to copy the key into.
|
|
* \param[in] data Buffer containing the key material.
|
|
* \param data_length Size of the key buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The key has been copied successfully.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* Not enough memory was available for allocation of the
|
|
* copy buffer.
|
|
* \retval #PSA_ERROR_ALREADY_EXISTS
|
|
* There was other key material already present in the slot.
|
|
*/
|
|
psa_status_t psa_copy_key_material_into_slot(psa_key_slot_t *slot,
|
|
const uint8_t *data,
|
|
size_t data_length);
|
|
|
|
/** Convert an mbed TLS error code to a PSA error code
|
|
*
|
|
* \note This function is provided solely for the convenience of
|
|
* Mbed TLS and may be removed at any time without notice.
|
|
*
|
|
* \param ret An mbed TLS-thrown error code
|
|
*
|
|
* \return The corresponding PSA error code
|
|
*/
|
|
psa_status_t mbedtls_to_psa_error(int ret);
|
|
|
|
/** Import a key in binary format.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* import_key entry point. This function behaves as an import_key
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* \param[in] attributes The attributes for the key to import.
|
|
* \param[in] data The buffer containing the key data in import
|
|
* format.
|
|
* \param[in] data_length Size of the \p data buffer in bytes.
|
|
* \param[out] key_buffer The buffer to contain the key data in output
|
|
* format upon successful return.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This
|
|
* size is greater or equal to \p data_length.
|
|
* \param[out] key_buffer_length The length of the data written in \p
|
|
* key_buffer in bytes.
|
|
* \param[out] bits The key size in number of bits.
|
|
*
|
|
* \retval #PSA_SUCCESS The key was imported successfully.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The key data is not correctly formatted.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
*/
|
|
psa_status_t psa_import_key_into_slot(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *data, size_t data_length,
|
|
uint8_t *key_buffer, size_t key_buffer_size,
|
|
size_t *key_buffer_length, size_t *bits);
|
|
|
|
/** Export a key in binary format
|
|
*
|
|
* \note The signature of this function is that of a PSA driver export_key
|
|
* entry point. This function behaves as an export_key entry point as
|
|
* defined in the PSA driver interface specification.
|
|
*
|
|
* \param[in] attributes The attributes for the key to export.
|
|
* \param[in] key_buffer Material or context of the key to export.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[out] data Buffer where the key data is to be written.
|
|
* \param[in] data_size Size of the \p data buffer in bytes.
|
|
* \param[out] data_length On success, the number of bytes written in
|
|
* \p data
|
|
*
|
|
* \retval #PSA_SUCCESS The key was exported successfully.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
*/
|
|
psa_status_t psa_export_key_internal(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
uint8_t *data, size_t data_size, size_t *data_length);
|
|
|
|
/** Export a public key or the public part of a key pair in binary format.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* export_public_key entry point. This function behaves as an
|
|
* export_public_key entry point as defined in the PSA driver interface
|
|
* specification.
|
|
*
|
|
* \param[in] attributes The attributes for the key to export.
|
|
* \param[in] key_buffer Material or context of the key to export.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[out] data Buffer where the key data is to be written.
|
|
* \param[in] data_size Size of the \p data buffer in bytes.
|
|
* \param[out] data_length On success, the number of bytes written in
|
|
* \p data
|
|
*
|
|
* \retval #PSA_SUCCESS The public key was exported successfully.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
*/
|
|
psa_status_t psa_export_public_key_internal(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
uint8_t *data, size_t data_size, size_t *data_length);
|
|
|
|
/**
|
|
* \brief Generate a key.
|
|
*
|
|
* \note The signature of the function is that of a PSA driver generate_key
|
|
* entry point.
|
|
*
|
|
* \param[in] attributes The attributes for the key to generate.
|
|
* \param[out] key_buffer Buffer where the key data is to be written.
|
|
* \param[in] key_buffer_size Size of \p key_buffer in bytes.
|
|
* \param[out] key_buffer_length On success, the number of bytes written in
|
|
* \p key_buffer.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The key was generated successfully.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* Key size in bits or type not supported.
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of \p key_buffer is too small.
|
|
*/
|
|
psa_status_t psa_generate_key_internal(const psa_key_attributes_t *attributes,
|
|
uint8_t *key_buffer,
|
|
size_t key_buffer_size,
|
|
size_t *key_buffer_length);
|
|
|
|
/** Sign a message with a private key. For hash-and-sign algorithms,
|
|
* this includes the hashing step.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* sign_message entry point. This function behaves as a sign_message
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* \note This function will call the driver for psa_sign_hash
|
|
* and go through driver dispatch again.
|
|
*
|
|
* \param[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[in] alg A signature algorithm that is compatible with
|
|
* the type of the key.
|
|
* \param[in] input The input message to sign.
|
|
* \param[in] input_length Size of the \p input buffer in bytes.
|
|
* \param[out] signature Buffer where the signature is to be written.
|
|
* \param[in] signature_size Size of the \p signature buffer in bytes.
|
|
* \param[out] signature_length On success, the number of bytes
|
|
* that make up the returned signature value.
|
|
*
|
|
* \retval #PSA_SUCCESS \emptydescription
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of the \p signature buffer is too small. You can
|
|
* determine a sufficient buffer size by calling
|
|
* #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
|
|
* where \c key_type and \c key_bits are the type and bit-size
|
|
* respectively of the key.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
|
|
*/
|
|
psa_status_t psa_sign_message_builtin(
|
|
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 *signature, size_t signature_size, size_t *signature_length);
|
|
|
|
/** Verify the signature of a message with a public key, using
|
|
* a hash-and-sign verification algorithm.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* verify_message entry point. This function behaves as a verify_message
|
|
* entry point as defined in the PSA driver interface specification for
|
|
* transparent drivers.
|
|
*
|
|
* \note This function will call the driver for psa_verify_hash
|
|
* and go through driver dispatch again.
|
|
*
|
|
* \param[in] attributes The attributes of the key to use for the
|
|
* operation.
|
|
* \param[in] key_buffer The buffer containing the key context.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[in] alg A signature algorithm that is compatible with
|
|
* the type of the key.
|
|
* \param[in] input The message whose signature is to be verified.
|
|
* \param[in] input_length Size of the \p input buffer in bytes.
|
|
* \param[in] signature Buffer containing the signature to verify.
|
|
* \param[in] signature_length Size of the \p signature buffer in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The signature is valid.
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
|
* The calculation was performed successfully, but the passed
|
|
* signature is not a valid signature.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
*/
|
|
psa_status_t psa_verify_message_builtin(
|
|
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,
|
|
const uint8_t *signature, size_t signature_length);
|
|
|
|
/** Sign an already-calculated hash with a private key.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* sign_hash entry point. This function behaves as a sign_hash
|
|
* 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[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[in] alg A signature algorithm that is compatible with
|
|
* the type of the key.
|
|
* \param[in] hash The hash or message to sign.
|
|
* \param[in] hash_length Size of the \p hash buffer in bytes.
|
|
* \param[out] signature Buffer where the signature is to be written.
|
|
* \param[in] signature_size Size of the \p signature buffer in bytes.
|
|
* \param[out] signature_length On success, the number of bytes
|
|
* that make up the returned signature value.
|
|
*
|
|
* \retval #PSA_SUCCESS \emptydescription
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* The size of the \p signature buffer is too small. You can
|
|
* determine a sufficient buffer size by calling
|
|
* #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
|
|
* where \c key_type and \c key_bits are the type and bit-size
|
|
* respectively of the key.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription
|
|
*/
|
|
psa_status_t psa_sign_hash_builtin(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
|
|
uint8_t *signature, size_t signature_size, size_t *signature_length);
|
|
|
|
/**
|
|
* \brief Verify the signature a hash or short message using a public key.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* verify_hash entry point. This function behaves as a verify_hash
|
|
* 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[in] key_buffer_size Size of the \p key_buffer buffer in bytes.
|
|
* \param[in] alg A signature algorithm that is compatible with
|
|
* the type of the key.
|
|
* \param[in] hash The hash or message whose signature is to be
|
|
* verified.
|
|
* \param[in] hash_length Size of the \p hash buffer in bytes.
|
|
* \param[in] signature Buffer containing the signature to verify.
|
|
* \param[in] signature_length Size of the \p signature buffer in bytes.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The signature is valid.
|
|
* \retval #PSA_ERROR_INVALID_SIGNATURE
|
|
* The calculation was performed successfully, but the passed
|
|
* signature is not a valid signature.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT \emptydescription
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
*/
|
|
psa_status_t psa_verify_hash_builtin(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer, size_t key_buffer_size,
|
|
psa_algorithm_t alg, const uint8_t *hash, size_t hash_length,
|
|
const uint8_t *signature, size_t signature_length);
|
|
|
|
/**
|
|
* \brief Validate the key bit size for unstructured keys.
|
|
*
|
|
* \note Check that the bit size is acceptable for a given key type for
|
|
* unstructured keys.
|
|
*
|
|
* \param[in] type The key type
|
|
* \param[in] bits The number of bits of the key
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The key type and size are valid.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* The size in bits of the key is not valid.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* The type and/or the size in bits of the key or the combination of
|
|
* the two is not supported.
|
|
*/
|
|
psa_status_t psa_validate_unstructured_key_bit_size(psa_key_type_t type,
|
|
size_t bits);
|
|
|
|
/** Perform a key agreement and return the raw shared secret, using
|
|
built-in raw key agreement functions.
|
|
*
|
|
* \note The signature of this function is that of a PSA driver
|
|
* key_agreement entry point. This function behaves as a key_agreement
|
|
* 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 private key
|
|
* context.
|
|
* \param[in] key_buffer_size Size of the \p key_buffer buffer in
|
|
* bytes.
|
|
* \param[in] alg A key agreement algorithm that is
|
|
* compatible with the type of the key.
|
|
* \param[in] peer_key The buffer containing the key context
|
|
* of the peer's public key.
|
|
* \param[in] peer_key_length Size of the \p peer_key buffer in
|
|
* bytes.
|
|
* \param[out] shared_secret The buffer to which the shared secret
|
|
* is to be written.
|
|
* \param[in] shared_secret_size Size of the \p shared_secret buffer in
|
|
* bytes.
|
|
* \param[out] shared_secret_length On success, the number of bytes that make
|
|
* up the returned shared secret.
|
|
* \retval #PSA_SUCCESS
|
|
* Success. Shared secret successfully calculated.
|
|
* \retval #PSA_ERROR_INVALID_HANDLE \emptydescription
|
|
* \retval #PSA_ERROR_NOT_PERMITTED \emptydescription
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* \p alg is not a key agreement algorithm, or
|
|
* \p private_key is not compatible with \p alg,
|
|
* or \p peer_key is not valid for \p alg or not compatible with
|
|
* \p private_key.
|
|
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
|
|
* \p shared_secret_size is too small
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p alg is not a supported key agreement algorithm.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
|
|
* \retval #PSA_ERROR_BAD_STATE \emptydescription
|
|
*/
|
|
psa_status_t psa_key_agreement_raw_builtin(
|
|
const psa_key_attributes_t *attributes,
|
|
const uint8_t *key_buffer,
|
|
size_t key_buffer_size,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *peer_key,
|
|
size_t peer_key_length,
|
|
uint8_t *shared_secret,
|
|
size_t shared_secret_size,
|
|
size_t *shared_secret_length);
|
|
|
|
#endif /* PSA_CRYPTO_CORE_H */
|