mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-10-19 08:31:27 +00:00
87a5e565f4
This commit starts a migration to a new interface for key creation.
Today, the application allocates a handle, then fills its metadata,
and finally injects key material. The new interface fills metadata
into a temporary structure, and a handle is allocated at the same time
it gets filled with both metadata and key material.
This commit was obtained by moving the declaration of the old-style
functions to crypto_extra.h and renaming them with the to_handle
suffix, adding declarations for the new-style functions in crypto.h
under their new name, and running
perl -i -pe 's/\bpsa_(import|copy|generator_import|generate)_key\b/$&_to_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
perl -i -pe 's/\bpsa_get_key_lifetime\b/$&_from_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
Many functions that are specific to the old interface, and which will
not remain under the same name with the new interface, are still in
crypto.h for now.
All functional tests should still pass. The documentation may have
some broken links.
297 lines
12 KiB
C
297 lines
12 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
|
|
|
|
#include "mbedtls/platform_util.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* UID for secure storage seed */
|
|
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
|
|
|
|
/*
|
|
* Deprecated PSA Crypto error code definitions
|
|
*/
|
|
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
|
|
#define PSA_ERROR_UNKNOWN_ERROR \
|
|
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
|
|
#endif
|
|
|
|
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
|
|
#define PSA_ERROR_OCCUPIED_SLOT \
|
|
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
|
|
#endif
|
|
|
|
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
|
|
#define PSA_ERROR_EMPTY_SLOT \
|
|
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
|
|
#endif
|
|
|
|
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
|
|
#define PSA_ERROR_INSUFFICIENT_CAPACITY \
|
|
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
|
|
#endif
|
|
|
|
/**
|
|
* \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 option MBEDTLS_PSA_INJECT_ENTROPY is 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
|
|
* 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)
|
|
|
|
/** \defgroup to_handle Key creation to allocated handle
|
|
* @{
|
|
*
|
|
* The functions in this section are legacy interfaces where the properties
|
|
* of a key object are set after allocating a handle, in constrast with the
|
|
* preferred interface where key objects are created atomically from
|
|
* a structure that represents the properties.
|
|
*/
|
|
|
|
/** Create a new persistent key slot.
|
|
*
|
|
* Create a new persistent key slot and return a handle to it. The handle
|
|
* remains valid until the application calls psa_close_key() or terminates.
|
|
* The application can open the key again with psa_open_key() until it
|
|
* removes the key by calling psa_destroy_key().
|
|
*
|
|
* \param lifetime The lifetime of the key. This designates a storage
|
|
* area where the key material is stored. This must not
|
|
* be #PSA_KEY_LIFETIME_VOLATILE.
|
|
* \param id The persistent identifier of the key.
|
|
* \param[out] handle On success, a handle to the newly created key slot.
|
|
* When key material is later created in this key slot,
|
|
* it will be saved to the specified persistent location.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success. The application can now use the value of `*handle`
|
|
* to access the newly allocated key slot.
|
|
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
|
|
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
|
|
* \retval #PSA_ERROR_ALREADY_EXISTS
|
|
* There is already a key with the identifier \p id in the storage
|
|
* area designated by \p lifetime.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
|
|
* \retval #PSA_ERROR_INVALID_ARGUMENT
|
|
* \p id is invalid for the specified lifetime.
|
|
* \retval #PSA_ERROR_NOT_SUPPORTED
|
|
* \p lifetime is not supported.
|
|
* \retval #PSA_ERROR_NOT_PERMITTED
|
|
* \p lifetime is valid, but the application does not have the
|
|
* permission to create a key there.
|
|
*/
|
|
psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
|
|
psa_key_id_t id,
|
|
psa_key_handle_t *handle);
|
|
|
|
/** \brief Retrieve the lifetime of an open key.
|
|
*
|
|
* \param handle Handle to query.
|
|
* \param[out] lifetime On success, the lifetime value.
|
|
*
|
|
* \retval #PSA_SUCCESS
|
|
* Success.
|
|
* \retval #PSA_ERROR_INVALID_HANDLE
|
|
* \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_get_key_lifetime_from_handle(psa_key_handle_t handle,
|
|
psa_key_lifetime_t *lifetime);
|
|
|
|
psa_status_t psa_import_key_to_handle(psa_key_handle_t handle,
|
|
psa_key_type_t type,
|
|
const uint8_t *data,
|
|
size_t data_length);
|
|
|
|
psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
|
|
psa_key_handle_t target_handle,
|
|
const psa_key_policy_t *constraint);
|
|
|
|
psa_status_t psa_generator_import_key_to_handle(psa_key_handle_t handle,
|
|
psa_key_type_t type,
|
|
size_t bits,
|
|
psa_crypto_generator_t *generator);
|
|
|
|
psa_status_t psa_generate_key_to_handle(psa_key_handle_t handle,
|
|
psa_key_type_t type,
|
|
size_t bits,
|
|
const void *extra,
|
|
size_t extra_size);
|
|
|
|
/**@}*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* PSA_CRYPTO_EXTRA_H */
|