mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-11-23 16:55:47 +01:00
0338ded2f4
Explain what the function does, why one would use it, how to use it, how to handle its input, and what the status codes mean.
118 lines
4.3 KiB
C
118 lines
4.3 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 MBED_RANDOM_SEED_ITS_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 );
|
|
|
|
|
|
#if ( defined(MBEDTLS_ENTROPY_NV_SEED) && defined(MBEDTLS_PSA_HAS_ITS_IO) )
|
|
/**
|
|
* \brief Inject an initial entropy seed for the random generator.
|
|
*
|
|
* 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, the file is not created, and you may call this
|
|
* function again after correcting the reason for the error.
|
|
*
|
|
* \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.
|
|
*
|
|
* \param seed[in] Buffer containing the seed value to inject.
|
|
* \param seed_size Size of the \p seed buffer.
|
|
* The minimum size of the seed is
|
|
* #MBEDTLS_ENTROPY_MIN_PLATFORM.
|
|
*
|
|
* \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 not large enough.
|
|
* \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);
|
|
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PSA_CRYPTO_EXTRA_H */
|