3be6b7f553
Validated by
perl -ne 'if (/^\/\*\*/) {%param=(); @p=()} if (/\\param.*? (\w+)/) {$param{$1}=1} while (/\\p \*?(\w+)/g) {push @p,[$1,ARGV->input_line_number()]} if (/^\ \*\//) {foreach (@p) {if (!$param{$_->[0]}) {printf "%s:%d: bad \\p %s\n", $ARGV, $_->[1], $_->[0]}}} close ARGV if eof' include/psa/*.h
186 lines
7.8 KiB
C
186 lines
7.8 KiB
C
/**
|
|
* \file psa/crypto_extra.h
|
|
*
|
|
* \brief PSA cryptography module: Mbed TLS vendor extensions
|
|
*
|
|
* \note This file may not be included directly. Applications must
|
|
* include psa/crypto.h.
|
|
*
|
|
* This file is reserved for vendor-specific definitions.
|
|
*/
|
|
/*
|
|
* Copyright (C) 2018, ARM Limited, All Rights Reserved
|
|
* 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.
|
|
*
|
|
* This file is part of mbed TLS (https://tls.mbed.org)
|
|
*/
|
|
|
|
#ifndef PSA_CRYPTO_EXTRA_H
|
|
#define PSA_CRYPTO_EXTRA_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* UID for secure storage seed */
|
|
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
|
|
|
|
/**
|
|
* \brief Library deinitialization.
|
|
*
|
|
* This function clears all data associated with the PSA layer,
|
|
* including the whole key store.
|
|
*
|
|
* This is an Mbed TLS extension.
|
|
*/
|
|
void mbedtls_psa_crypto_free( void );
|
|
|
|
|
|
/**
|
|
* \brief Inject an initial entropy seed for the random generator into
|
|
* secure storage.
|
|
*
|
|
* This function injects data to be used as a seed for the random generator
|
|
* used by the PSA Crypto implementation. On devices that lack a trusted
|
|
* entropy source (preferably a hardware random number generator),
|
|
* the Mbed PSA Crypto implementation uses this value to seed its
|
|
* random generator.
|
|
*
|
|
* On devices without a trusted entropy source, this function must be
|
|
* called exactly once in the lifetime of the device. On devices with
|
|
* a trusted entropy source, calling this function is optional.
|
|
* In all cases, this function may only be called before calling any
|
|
* other function in the PSA Crypto API, including psa_crypto_init().
|
|
*
|
|
* When this function returns successfully, it populates a file in
|
|
* persistent storage. Once the file has been created, this function
|
|
* can no longer succeed.
|
|
*
|
|
* If any error occurs, this function does not change the system state.
|
|
* You can call this function again after correcting the reason for the
|
|
* error if possible.
|
|
*
|
|
* \warning This function **can** fail! Callers MUST check the return status.
|
|
*
|
|
* \warning If you use this function, you should use it as part of a
|
|
* factory provisioning process. The value of the injected seed
|
|
* is critical to the security of the device. It must be
|
|
* *secret*, *unpredictable* and (statistically) *unique per device*.
|
|
* You should be generate it randomly using a cryptographically
|
|
* secure random generator seeded from trusted entropy sources.
|
|
* You should transmit it securely to the device and ensure
|
|
* that its value is not leaked or stored anywhere beyond the
|
|
* needs of transmitting it from the point of generation to
|
|
* the call of this function, and erase all copies of the value
|
|
* once this function returns.
|
|
*
|
|
* This is an Mbed TLS extension.
|
|
*
|
|
* \note This function is only available on the following platforms:
|
|
* * If the compile-time options MBEDTLS_ENTROPY_NV_SEED and
|
|
* MBEDTLS_PSA_HAS_ITS_IO are both enabled. Note that you
|
|
* must provide compatible implementations of mbedtls_nv_seed_read
|
|
* and mbedtls_nv_seed_write.
|
|
* * In a client-server integration of PSA Cryptography, on the client side,
|
|
* if the server supports this feature.
|
|
* \param[in] seed Buffer containing the seed value to inject.
|
|
* \param[in] seed_size Size of the \p seed buffer.
|
|
* The size of the seed in bytes must be greater
|
|
* or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
|
|
* and #MBEDTLS_ENTROPY_BLOCK_SIZE.
|
|
* It must be less or equal to
|
|
* #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* The seed value was injected successfully. The random generator
|
|
* of the PSA Crypto implementation is now ready for use.
|
|
* You may now call psa_crypto_init() and use the PSA Crypto
|
|
* implementation.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* \p seed_size is out of range.
|
|
* \retval #PSA_ERROR_STORAGE_FAILURE
|
|
* \retval `PSA_ITS_ERROR_XXX`
|
|
* There was a failure reading or writing from storage.
|
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
* The library has already been initialized. It is no longer
|
|
* possible to call this function.
|
|
*/
|
|
psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
|
|
size_t seed_size);
|
|
|
|
/** Set up a key derivation operation.
|
|
*
|
|
* FIMXE This function is no longer part of the official API. Its prototype
|
|
* is only kept around for the sake of tests that haven't been updated yet.
|
|
*
|
|
* A key derivation algorithm takes three inputs: a secret input \p handle and
|
|
* two non-secret inputs \p label and p salt.
|
|
* The result of this function is a byte generator which can
|
|
* be used to produce keys and other cryptographic material.
|
|
*
|
|
* The role of \p label and \p salt is as follows:
|
|
* - For HKDF (#PSA_ALG_HKDF), \p salt is the salt used in the "extract" step
|
|
* and \p label is the info string used in the "expand" step.
|
|
*
|
|
* \param[in,out] generator The generator object to set up. It must have
|
|
* been initialized as per the documentation for
|
|
* #psa_crypto_generator_t and not yet in use.
|
|
* \param handle Handle to the secret key.
|
|
* \param alg The key derivation algorithm to compute
|
|
* (\c PSA_ALG_XXX value such that
|
|
* #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
|
|
* \param[in] salt Salt to use.
|
|
* \param salt_length Size of the \p salt buffer in bytes.
|
|
* \param[in] label Label to use.
|
|
* \param label_length Size of the \p label buffer in bytes.
|
|
* \param capacity The maximum number of bytes that the
|
|
* generator will be able to provide.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
* \retval #PSA_ERROR_EMPTY_SLOT
|
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* \c key is not compatible with \c alg,
|
|
* or \p capacity is too large for the specified algorithm and key.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \c alg is not supported or is not a key derivation algorithm.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
|
|
* \retval #PSA_ERROR_HARDWARE_FAILURE
|
|
* \retval #PSA_ERROR_TAMPERING_DETECTED
|
|
* \retval #PSA_ERROR_BAD_STATE
|
|
* The library has not been previously initialized by psa_crypto_init().
|
|
* It is implementation-dependent whether a failure to initialize
|
|
* results in this error code.
|
|
*/
|
|
psa_status_t psa_key_derivation(psa_crypto_generator_t *generator,
|
|
psa_key_handle_t handle,
|
|
psa_algorithm_t alg,
|
|
const uint8_t *salt,
|
|
size_t salt_length,
|
|
const uint8_t *label,
|
|
size_t label_length,
|
|
size_t capacity);
|
|
|
|
/* FIXME Deprecated. Remove this as soon as all the tests are updated. */
|
|
#define PSA_ALG_SELECT_RAW ((psa_algorithm_t)0x31000001)
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PSA_CRYPTO_EXTRA_H */
|