blob: 86d9954ce791a9f8023ef8488ece429ec39a240f [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto_extra.h
3 *
4 * \brief PSA cryptography module: Mbed TLS vendor extensions
Gilles Peskine07c91f52018-06-28 18:02:53 +02005 *
6 * \note This file may not be included directly. Applications must
7 * include psa/crypto.h.
8 *
9 * This file is reserved for vendor-specific definitions.
Gilles Peskinee59236f2018-01-27 23:32:46 +010010 */
11/*
12 * Copyright (C) 2018, ARM Limited, All Rights Reserved
13 * SPDX-License-Identifier: Apache-2.0
14 *
15 * Licensed under the Apache License, Version 2.0 (the "License"); you may
16 * not use this file except in compliance with the License.
17 * You may obtain a copy of the License at
18 *
19 * http://www.apache.org/licenses/LICENSE-2.0
20 *
21 * Unless required by applicable law or agreed to in writing, software
22 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
23 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24 * See the License for the specific language governing permissions and
25 * limitations under the License.
26 *
27 * This file is part of mbed TLS (https://tls.mbed.org)
28 */
29
30#ifndef PSA_CRYPTO_EXTRA_H
31#define PSA_CRYPTO_EXTRA_H
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
Netanel Gonen2bcd3122018-11-19 11:53:02 +020037/* UID for secure storage seed */
avolinski0d2c2662018-11-21 17:31:07 +020038#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
Netanel Gonen2bcd3122018-11-19 11:53:02 +020039
Jaeden Amero5e6d24c2019-02-21 10:41:29 +000040/*
41 * Deprecated PSA Crypto error code definitions
42 */
43#if !defined(MBEDTLS_DEPRECATED_REMOVED)
44#define PSA_ERROR_UNKNOWN_ERROR \
45 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
46#endif
47
48#if !defined(MBEDTLS_DEPRECATED_REMOVED)
49#define PSA_ERROR_OCCUPIED_SLOT \
50 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
51#endif
52
53#if !defined(MBEDTLS_DEPRECATED_REMOVED)
54#define PSA_ERROR_EMPTY_SLOT \
55 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
56#endif
57
58#if !defined(MBEDTLS_DEPRECATED_REMOVED)
59#define PSA_ERROR_INSUFFICIENT_CAPACITY \
60 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
61#endif
62
Gilles Peskinee59236f2018-01-27 23:32:46 +010063/**
64 * \brief Library deinitialization.
65 *
66 * This function clears all data associated with the PSA layer,
67 * including the whole key store.
68 *
69 * This is an Mbed TLS extension.
70 */
71void mbedtls_psa_crypto_free( void );
72
Netanel Gonen2bcd3122018-11-19 11:53:02 +020073
Netanel Gonen2bcd3122018-11-19 11:53:02 +020074/**
Gilles Peskineee2ffd32018-11-16 11:02:49 +010075 * \brief Inject an initial entropy seed for the random generator into
76 * secure storage.
Gilles Peskine0338ded2018-11-15 18:19:27 +010077 *
78 * This function injects data to be used as a seed for the random generator
79 * used by the PSA Crypto implementation. On devices that lack a trusted
80 * entropy source (preferably a hardware random number generator),
81 * the Mbed PSA Crypto implementation uses this value to seed its
82 * random generator.
83 *
84 * On devices without a trusted entropy source, this function must be
85 * called exactly once in the lifetime of the device. On devices with
86 * a trusted entropy source, calling this function is optional.
87 * In all cases, this function may only be called before calling any
88 * other function in the PSA Crypto API, including psa_crypto_init().
89 *
90 * When this function returns successfully, it populates a file in
91 * persistent storage. Once the file has been created, this function
92 * can no longer succeed.
Gilles Peskineee2ffd32018-11-16 11:02:49 +010093 *
94 * If any error occurs, this function does not change the system state.
95 * You can call this function again after correcting the reason for the
96 * error if possible.
Netanel Gonen2bcd3122018-11-19 11:53:02 +020097 *
98 * \warning This function **can** fail! Callers MUST check the return status.
99 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100100 * \warning If you use this function, you should use it as part of a
101 * factory provisioning process. The value of the injected seed
102 * is critical to the security of the device. It must be
103 * *secret*, *unpredictable* and (statistically) *unique per device*.
104 * You should be generate it randomly using a cryptographically
105 * secure random generator seeded from trusted entropy sources.
106 * You should transmit it securely to the device and ensure
107 * that its value is not leaked or stored anywhere beyond the
108 * needs of transmitting it from the point of generation to
109 * the call of this function, and erase all copies of the value
110 * once this function returns.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200111 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100112 * This is an Mbed TLS extension.
113 *
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200114 * \note This function is only available on the following platforms:
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200115 * * If the compile-time options MBEDTLS_ENTROPY_NV_SEED and
116 * MBEDTLS_PSA_HAS_ITS_IO are both enabled. Note that you
117 * must provide compatible implementations of mbedtls_nv_seed_read
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200118 * and mbedtls_nv_seed_write.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200119 * * In a client-server integration of PSA Cryptography, on the client side,
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200120 * if the server supports this feature.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200121 * \param[in] seed Buffer containing the seed value to inject.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200122 * \param[in] seed_size Size of the \p seed buffer.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200123 * The size of the seed in bytes must be greater
124 * or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
125 * and #MBEDTLS_ENTROPY_BLOCK_SIZE.
126 * It must be less or equal to
127 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200128 *
129 * \retval #PSA_SUCCESS
Gilles Peskine0338ded2018-11-15 18:19:27 +0100130 * The seed value was injected successfully. The random generator
131 * of the PSA Crypto implementation is now ready for use.
132 * You may now call psa_crypto_init() and use the PSA Crypto
133 * implementation.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200134 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100135 * \p seed_size is out of range.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200136 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine0338ded2018-11-15 18:19:27 +0100137 * There was a failure reading or writing from storage.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200138 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine0338ded2018-11-15 18:19:27 +0100139 * The library has already been initialized. It is no longer
140 * possible to call this function.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200141 */
142psa_status_t mbedtls_psa_inject_entropy(const unsigned char *seed,
143 size_t seed_size);
144
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200145
Gilles Peskinee59236f2018-01-27 23:32:46 +0100146#ifdef __cplusplus
147}
148#endif
149
150#endif /* PSA_CRYPTO_EXTRA_H */