blob: 3611c4136f992893b7a1ca38eb24a03995fd6e31 [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/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020012 * Copyright The Mbed TLS Contributors
Gilles Peskinee59236f2018-01-27 23:32:46 +010013 * 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.
Gilles Peskinee59236f2018-01-27 23:32:46 +010026 */
27
28#ifndef PSA_CRYPTO_EXTRA_H
29#define PSA_CRYPTO_EXTRA_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020030#include "mbedtls/private_access.h"
Gilles Peskinee59236f2018-01-27 23:32:46 +010031
Jaeden Amero81cefed2019-02-25 08:51:27 +000032#include "mbedtls/platform_util.h"
33
Gilles Peskine7a894f22019-11-26 16:06:46 +010034#include "crypto_compat.h"
35
Gilles Peskinee59236f2018-01-27 23:32:46 +010036#ifdef __cplusplus
37extern "C" {
38#endif
39
Netanel Gonen2bcd3122018-11-19 11:53:02 +020040/* UID for secure storage seed */
avolinski0d2c2662018-11-21 17:31:07 +020041#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
Netanel Gonen2bcd3122018-11-19 11:53:02 +020042
Steven Cooreman1f968fd2021-02-15 14:00:24 +010043/* See config.h for definition */
Steven Cooreman863470a2021-02-15 14:03:19 +010044#if !defined(MBEDTLS_PSA_KEY_SLOT_COUNT)
45#define MBEDTLS_PSA_KEY_SLOT_COUNT 32
Steven Cooreman1f968fd2021-02-15 14:00:24 +010046#endif
Jaeden Amero5e6d24c2019-02-21 10:41:29 +000047
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020048/** \addtogroup attributes
49 * @{
50 */
51
52/** \brief Declare the enrollment algorithm for a key.
53 *
54 * An operation on a key may indifferently use the algorithm set with
55 * psa_set_key_algorithm() or with this function.
56 *
57 * \param[out] attributes The attribute structure to write to.
58 * \param alg2 A second algorithm that the key may be used
59 * for, in addition to the algorithm set with
60 * psa_set_key_algorithm().
61 *
62 * \warning Setting an enrollment algorithm is not recommended, because
63 * using the same key with different algorithms can allow some
64 * attacks based on arithmetic relations between different
65 * computations made with the same key, or can escalate harmless
66 * side channels into exploitable ones. Use this function only
Gilles Peskinef25c9ec2019-05-22 11:45:59 +020067 * if it is necessary to support a protocol for which it has been
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020068 * verified that the usage of the key with multiple algorithms
69 * is safe.
70 */
71static inline void psa_set_key_enrollment_algorithm(
72 psa_key_attributes_t *attributes,
73 psa_algorithm_t alg2)
74{
Mateusz Starzyk846f0212021-05-19 19:44:07 +020075 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) = alg2;
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020076}
77
78/** Retrieve the enrollment algorithm policy from key attributes.
79 *
80 * \param[in] attributes The key attribute structure to query.
81 *
82 * \return The enrollment algorithm stored in the attribute structure.
83 */
84static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
85 const psa_key_attributes_t *attributes)
86{
Mateusz Starzyk846f0212021-05-19 19:44:07 +020087 return( attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(policy).MBEDTLS_PRIVATE(alg2) );
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020088}
89
Gilles Peskinec8000c02019-08-02 20:15:51 +020090#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
91
92/** Retrieve the slot number where a key is stored.
93 *
94 * A slot number is only defined for keys that are stored in a secure
95 * element.
96 *
97 * This information is only useful if the secure element is not entirely
98 * managed through the PSA Cryptography API. It is up to the secure
99 * element driver to decide how PSA slot numbers map to any other interface
100 * that the secure element may have.
101 *
102 * \param[in] attributes The key attribute structure to query.
103 * \param[out] slot_number On success, the slot number containing the key.
104 *
105 * \retval #PSA_SUCCESS
106 * The key is located in a secure element, and \p *slot_number
107 * indicates the slot number that contains it.
108 * \retval #PSA_ERROR_NOT_PERMITTED
109 * The caller is not permitted to query the slot number.
110 * Mbed Crypto currently does not return this error.
111 * \retval #PSA_ERROR_INVALID_ARGUMENT
112 * The key is not located in a secure element.
113 */
114psa_status_t psa_get_key_slot_number(
115 const psa_key_attributes_t *attributes,
116 psa_key_slot_number_t *slot_number );
117
118/** Choose the slot number where a key is stored.
119 *
120 * This function declares a slot number in the specified attribute
121 * structure.
122 *
123 * A slot number is only meaningful for keys that are stored in a secure
124 * element. It is up to the secure element driver to decide how PSA slot
125 * numbers map to any other interface that the secure element may have.
126 *
127 * \note Setting a slot number in key attributes for a key creation can
128 * cause the following errors when creating the key:
129 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
130 * not support choosing a specific slot number.
131 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
132 * choose slot numbers in general or to choose this specific slot.
133 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
134 * valid in general or not valid for this specific key.
135 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
136 * selected slot.
137 *
138 * \param[out] attributes The attribute structure to write to.
139 * \param slot_number The slot number to set.
140 */
141static inline void psa_set_key_slot_number(
142 psa_key_attributes_t *attributes,
143 psa_key_slot_number_t slot_number )
144{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200145 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(flags) |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
146 attributes->MBEDTLS_PRIVATE(slot_number) = slot_number;
Gilles Peskinec8000c02019-08-02 20:15:51 +0200147}
148
Gilles Peskine5fe5e272019-08-02 20:30:01 +0200149/** Remove the slot number attribute from a key attribute structure.
150 *
151 * This function undoes the action of psa_set_key_slot_number().
152 *
153 * \param[out] attributes The attribute structure to write to.
154 */
155static inline void psa_clear_key_slot_number(
156 psa_key_attributes_t *attributes )
157{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200158 attributes->MBEDTLS_PRIVATE(core).MBEDTLS_PRIVATE(flags) &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
Gilles Peskine5fe5e272019-08-02 20:30:01 +0200159}
160
Gilles Peskined7729582019-08-05 15:55:54 +0200161/** Register a key that is already present in a secure element.
162 *
163 * The key must be located in a secure element designated by the
164 * lifetime field in \p attributes, in the slot set with
165 * psa_set_key_slot_number() in the attribute structure.
166 * This function makes the key available through the key identifier
167 * specified in \p attributes.
168 *
169 * \param[in] attributes The attributes of the existing key.
170 *
171 * \retval #PSA_SUCCESS
172 * The key was successfully registered.
173 * Note that depending on the design of the driver, this may or may
174 * not guarantee that a key actually exists in the designated slot
175 * and is compatible with the specified attributes.
176 * \retval #PSA_ERROR_ALREADY_EXISTS
177 * There is already a key with the identifier specified in
178 * \p attributes.
Gilles Peskine3efcebb2019-10-01 14:18:35 +0200179 * \retval #PSA_ERROR_NOT_SUPPORTED
180 * The secure element driver for the specified lifetime does not
181 * support registering a key.
Gilles Peskined7729582019-08-05 15:55:54 +0200182 * \retval #PSA_ERROR_INVALID_ARGUMENT
Ronald Crond3b458c2021-03-31 17:51:29 +0200183 * The identifier in \p attributes is invalid, namely the identifier is
184 * not in the user range.
185 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskined7729582019-08-05 15:55:54 +0200186 * \p attributes specifies a lifetime which is not located
187 * in a secure element.
188 * \retval #PSA_ERROR_INVALID_ARGUMENT
189 * No slot number is specified in \p attributes,
190 * or the specified slot number is not valid.
191 * \retval #PSA_ERROR_NOT_PERMITTED
192 * The caller is not authorized to register the specified key slot.
193 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
gabor-mezei-arm452b0a32020-11-09 17:42:55 +0100194 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskined7729582019-08-05 15:55:54 +0200195 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
gabor-mezei-arm452b0a32020-11-09 17:42:55 +0100196 * \retval #PSA_ERROR_DATA_INVALID
197 * \retval #PSA_ERROR_DATA_CORRUPT
Gilles Peskined7729582019-08-05 15:55:54 +0200198 * \retval #PSA_ERROR_CORRUPTION_DETECTED
199 * \retval #PSA_ERROR_BAD_STATE
200 * The library has not been previously initialized by psa_crypto_init().
201 * It is implementation-dependent whether a failure to initialize
202 * results in this error code.
203 */
204psa_status_t mbedtls_psa_register_se_key(
205 const psa_key_attributes_t *attributes);
206
Gilles Peskinec8000c02019-08-02 20:15:51 +0200207#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
208
Gilles Peskine96f0b3b2019-05-10 19:33:38 +0200209/**@}*/
210
Gilles Peskinee59236f2018-01-27 23:32:46 +0100211/**
212 * \brief Library deinitialization.
213 *
214 * This function clears all data associated with the PSA layer,
215 * including the whole key store.
216 *
217 * This is an Mbed TLS extension.
218 */
219void mbedtls_psa_crypto_free( void );
220
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200221/** \brief Statistics about
222 * resource consumption related to the PSA keystore.
223 *
224 * \note The content of this structure is not part of the stable API and ABI
225 * of Mbed Crypto and may change arbitrarily from version to version.
226 */
227typedef struct mbedtls_psa_stats_s
228{
229 /** Number of slots containing key material for a volatile key. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200230 size_t MBEDTLS_PRIVATE(volatile_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200231 /** Number of slots containing key material for a key which is in
232 * internal persistent storage. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200233 size_t MBEDTLS_PRIVATE(persistent_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200234 /** Number of slots containing a reference to a key in a
235 * secure element. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200236 size_t MBEDTLS_PRIVATE(external_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200237 /** Number of slots which are occupied, but do not contain
238 * key material yet. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200239 size_t MBEDTLS_PRIVATE(half_filled_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200240 /** Number of slots that contain cache data. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200241 size_t MBEDTLS_PRIVATE(cache_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200242 /** Number of slots that are not used for anything. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200243 size_t MBEDTLS_PRIVATE(empty_slots);
Ronald Cron1ad1eee2020-11-15 14:21:04 +0100244 /** Number of slots that are locked. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200245 size_t MBEDTLS_PRIVATE(locked_slots);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200246 /** Largest key id value among open keys in internal persistent storage. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200247 psa_key_id_t MBEDTLS_PRIVATE(max_open_internal_key_id);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200248 /** Largest key id value among open keys in secure elements. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200249 psa_key_id_t MBEDTLS_PRIVATE(max_open_external_key_id);
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200250} mbedtls_psa_stats_t;
251
252/** \brief Get statistics about
253 * resource consumption related to the PSA keystore.
254 *
255 * \note When Mbed Crypto is built as part of a service, with isolation
256 * between the application and the keystore, the service may or
257 * may not expose this function.
258 */
259void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200260
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200261/**
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100262 * \brief Inject an initial entropy seed for the random generator into
263 * secure storage.
Gilles Peskine0338ded2018-11-15 18:19:27 +0100264 *
265 * This function injects data to be used as a seed for the random generator
266 * used by the PSA Crypto implementation. On devices that lack a trusted
267 * entropy source (preferably a hardware random number generator),
268 * the Mbed PSA Crypto implementation uses this value to seed its
269 * random generator.
270 *
271 * On devices without a trusted entropy source, this function must be
272 * called exactly once in the lifetime of the device. On devices with
273 * a trusted entropy source, calling this function is optional.
274 * In all cases, this function may only be called before calling any
275 * other function in the PSA Crypto API, including psa_crypto_init().
276 *
277 * When this function returns successfully, it populates a file in
278 * persistent storage. Once the file has been created, this function
279 * can no longer succeed.
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100280 *
281 * If any error occurs, this function does not change the system state.
282 * You can call this function again after correcting the reason for the
283 * error if possible.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200284 *
285 * \warning This function **can** fail! Callers MUST check the return status.
286 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100287 * \warning If you use this function, you should use it as part of a
288 * factory provisioning process. The value of the injected seed
289 * is critical to the security of the device. It must be
290 * *secret*, *unpredictable* and (statistically) *unique per device*.
291 * You should be generate it randomly using a cryptographically
292 * secure random generator seeded from trusted entropy sources.
293 * You should transmit it securely to the device and ensure
294 * that its value is not leaked or stored anywhere beyond the
295 * needs of transmitting it from the point of generation to
296 * the call of this function, and erase all copies of the value
297 * once this function returns.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200298 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100299 * This is an Mbed TLS extension.
300 *
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200301 * \note This function is only available on the following platforms:
Gilles Peskinee3dbdd82019-02-25 11:04:06 +0100302 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
303 * Note that you must provide compatible implementations of
304 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200305 * * In a client-server integration of PSA Cryptography, on the client side,
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200306 * if the server supports this feature.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200307 * \param[in] seed Buffer containing the seed value to inject.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200308 * \param[in] seed_size Size of the \p seed buffer.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200309 * The size of the seed in bytes must be greater
Chris Jones3848e312021-03-11 16:17:59 +0000310 * or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE
311 * and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM
312 * in `library/entropy_poll.h` in the Mbed TLS source
313 * code.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200314 * It must be less or equal to
315 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200316 *
317 * \retval #PSA_SUCCESS
Gilles Peskine0338ded2018-11-15 18:19:27 +0100318 * The seed value was injected successfully. The random generator
319 * of the PSA Crypto implementation is now ready for use.
320 * You may now call psa_crypto_init() and use the PSA Crypto
321 * implementation.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200322 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100323 * \p seed_size is out of range.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200324 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine0338ded2018-11-15 18:19:27 +0100325 * There was a failure reading or writing from storage.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200326 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine0338ded2018-11-15 18:19:27 +0100327 * The library has already been initialized. It is no longer
328 * possible to call this function.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200329 */
Jaeden Ameroc7529c92019-08-19 11:08:04 +0100330psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200331 size_t seed_size);
332
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200333/** \addtogroup crypto_types
334 * @{
335 */
336
Gilles Peskinea1302192019-05-16 13:58:24 +0200337/** DSA public key.
338 *
339 * The import and export format is the
340 * representation of the public key `y = g^x mod p` as a big-endian byte
341 * string. The length of the byte string is the length of the base prime `p`
342 * in bytes.
343 */
Gilles Peskine7cfcb3f2019-12-04 18:58:44 +0100344#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002)
Gilles Peskinea1302192019-05-16 13:58:24 +0200345
346/** DSA key pair (private and public key).
347 *
348 * The import and export format is the
349 * representation of the private key `x` as a big-endian byte string. The
350 * length of the byte string is the private key size in bytes (leading zeroes
351 * are not stripped).
352 *
353 * Determinstic DSA key derivation with psa_generate_derived_key follows
354 * FIPS 186-4 §B.1.2: interpret the byte string as integer
355 * in big-endian order. Discard it if it is not in the range
356 * [0, *N* - 2] where *N* is the boundary of the private key domain
357 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
358 * or the order of the curve's base point for ECC).
359 * Add 1 to the resulting integer and use this as the private key *x*.
360 *
361 */
Gilles Peskine7cfcb3f2019-12-04 18:58:44 +0100362#define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t)0x7002)
Gilles Peskinea1302192019-05-16 13:58:24 +0200363
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200364/** Whether a key type is an DSA key (pair or public-only). */
365#define PSA_KEY_TYPE_IS_DSA(type) \
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200366 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200367
Bence Szépkútia2945512020-12-03 21:40:17 +0100368#define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x06000400)
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200369/** DSA signature with hashing.
370 *
371 * This is the signature scheme defined by FIPS 186-4,
372 * with a random per-message secret number (*k*).
373 *
374 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
375 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
376 * This includes #PSA_ALG_ANY_HASH
377 * when specifying the algorithm in a usage policy.
378 *
379 * \return The corresponding DSA signature algorithm.
380 * \return Unspecified if \p hash_alg is not a supported
381 * hash algorithm.
382 */
383#define PSA_ALG_DSA(hash_alg) \
384 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
Bence Szépkútia2945512020-12-03 21:40:17 +0100385#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x06000500)
Gilles Peskine972630e2019-11-29 11:55:48 +0100386#define PSA_ALG_DSA_DETERMINISTIC_FLAG PSA_ALG_ECDSA_DETERMINISTIC_FLAG
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200387/** Deterministic DSA signature with hashing.
388 *
389 * This is the deterministic variant defined by RFC 6979 of
390 * the signature scheme defined by FIPS 186-4.
391 *
392 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
393 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
394 * This includes #PSA_ALG_ANY_HASH
395 * when specifying the algorithm in a usage policy.
396 *
397 * \return The corresponding DSA signature algorithm.
398 * \return Unspecified if \p hash_alg is not a supported
399 * hash algorithm.
400 */
401#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
402 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
403#define PSA_ALG_IS_DSA(alg) \
404 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
405 PSA_ALG_DSA_BASE)
406#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
407 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
408#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
409 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
410#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
411 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
412
413
414/* We need to expand the sample definition of this macro from
415 * the API definition. */
Gilles Peskine6d400852021-02-24 21:39:52 +0100416#undef PSA_ALG_IS_VENDOR_HASH_AND_SIGN
417#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) \
418 PSA_ALG_IS_DSA(alg)
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200419
420/**@}*/
421
Gilles Peskine24f10f82019-05-16 12:18:32 +0200422/** \addtogroup attributes
423 * @{
424 */
425
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200426/** Custom Diffie-Hellman group.
427 *
Paul Elliott75e27032020-06-03 15:17:39 +0100428 * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
429 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM), the group data comes
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200430 * from domain parameters set by psa_set_key_domain_parameters().
431 */
Paul Elliott75e27032020-06-03 15:17:39 +0100432#define PSA_DH_FAMILY_CUSTOM ((psa_dh_family_t) 0x7e)
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200433
434
Gilles Peskine24f10f82019-05-16 12:18:32 +0200435/**
436 * \brief Set domain parameters for a key.
437 *
438 * Some key types require additional domain parameters in addition to
439 * the key type identifier and the key size. Use this function instead
440 * of psa_set_key_type() when you need to specify domain parameters.
441 *
442 * The format for the required domain parameters varies based on the key type.
443 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200444 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200445 * the domain parameter data consists of the public exponent,
446 * represented as a big-endian integer with no leading zeros.
447 * This information is used when generating an RSA key pair.
448 * When importing a key, the public exponent is read from the imported
449 * key data and the exponent recorded in the attribute structure is ignored.
450 * As an exception, the public exponent 65537 is represented by an empty
451 * byte string.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200452 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200453 * the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
454 * ```
455 * Dss-Parms ::= SEQUENCE {
456 * p INTEGER,
457 * q INTEGER,
458 * g INTEGER
459 * }
460 * ```
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200461 * - For Diffie-Hellman key exchange keys
Paul Elliott75e27032020-06-03 15:17:39 +0100462 * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_FAMILY_CUSTOM) or
463 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_FAMILY_CUSTOM)), the
Gilles Peskine24f10f82019-05-16 12:18:32 +0200464 * `DomainParameters` format as defined by RFC 3279 §2.3.3.
465 * ```
466 * DomainParameters ::= SEQUENCE {
467 * p INTEGER, -- odd prime, p=jq +1
468 * g INTEGER, -- generator, g
469 * q INTEGER, -- factor of p-1
470 * j INTEGER OPTIONAL, -- subgroup factor
471 * validationParms ValidationParms OPTIONAL
472 * }
473 * ValidationParms ::= SEQUENCE {
474 * seed BIT STRING,
475 * pgenCounter INTEGER
476 * }
477 * ```
478 *
479 * \note This function may allocate memory or other resources.
480 * Once you have called this function on an attribute structure,
481 * you must call psa_reset_key_attributes() to free these resources.
482 *
483 * \note This is an experimental extension to the interface. It may change
484 * in future versions of the library.
485 *
486 * \param[in,out] attributes Attribute structure where the specified domain
487 * parameters will be stored.
488 * If this function fails, the content of
489 * \p attributes is not modified.
490 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
491 * \param[in] data Buffer containing the key domain parameters.
492 * The content of this buffer is interpreted
493 * according to \p type as described above.
494 * \param data_length Size of the \p data buffer in bytes.
495 *
496 * \retval #PSA_SUCCESS
497 * \retval #PSA_ERROR_INVALID_ARGUMENT
498 * \retval #PSA_ERROR_NOT_SUPPORTED
499 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
500 */
501psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
502 psa_key_type_t type,
503 const uint8_t *data,
504 size_t data_length);
505
506/**
507 * \brief Get domain parameters for a key.
508 *
509 * Get the domain parameters for a key with this function, if any. The format
510 * of the domain parameters written to \p data is specified in the
511 * documentation for psa_set_key_domain_parameters().
512 *
513 * \note This is an experimental extension to the interface. It may change
514 * in future versions of the library.
515 *
516 * \param[in] attributes The key attribute structure to query.
517 * \param[out] data On success, the key domain parameters.
518 * \param data_size Size of the \p data buffer in bytes.
519 * The buffer is guaranteed to be large
520 * enough if its size in bytes is at least
521 * the value given by
522 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
523 * \param[out] data_length On success, the number of bytes
524 * that make up the key domain parameters data.
525 *
526 * \retval #PSA_SUCCESS
527 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
528 */
529psa_status_t psa_get_key_domain_parameters(
530 const psa_key_attributes_t *attributes,
531 uint8_t *data,
532 size_t data_size,
533 size_t *data_length);
534
535/** Safe output buffer size for psa_get_key_domain_parameters().
536 *
537 * This macro returns a compile-time constant if its arguments are
538 * compile-time constants.
539 *
540 * \warning This function may call its arguments multiple times or
541 * zero times, so you should not pass arguments that contain
542 * side effects.
543 *
544 * \note This is an experimental extension to the interface. It may change
545 * in future versions of the library.
546 *
547 * \param key_type A supported key type.
548 * \param key_bits The size of the key in bits.
549 *
550 * \return If the parameters are valid and supported, return
551 * a buffer size in bytes that guarantees that
552 * psa_get_key_domain_parameters() will not fail with
553 * #PSA_ERROR_BUFFER_TOO_SMALL.
554 * If the parameters are a valid combination that is not supported
Gilles Peskine27a983d2019-05-16 17:24:53 +0200555 * by the implementation, this macro shall return either a
Gilles Peskine24f10f82019-05-16 12:18:32 +0200556 * sensible size or 0.
557 * If the parameters are not valid, the
558 * return value is unspecified.
559 */
560#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
561 (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
562 PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
563 PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
564 0)
565#define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
566 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
567#define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
568 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
569
570/**@}*/
571
Gilles Peskine5055b232019-12-12 17:49:31 +0100572/** \defgroup psa_tls_helpers TLS helper functions
573 * @{
574 */
575
576#if defined(MBEDTLS_ECP_C)
577#include <mbedtls/ecp.h>
578
579/** Convert an ECC curve identifier from the Mbed TLS encoding to PSA.
580 *
581 * \note This function is provided solely for the convenience of
582 * Mbed TLS and may be removed at any time without notice.
583 *
584 * \param grpid An Mbed TLS elliptic curve identifier
585 * (`MBEDTLS_ECP_DP_xxx`).
586 * \param[out] bits On success, the bit size of the curve.
587 *
588 * \return The corresponding PSA elliptic curve identifier
Paul Elliott8ff510a2020-06-02 17:19:28 +0100589 * (`PSA_ECC_FAMILY_xxx`).
Gilles Peskine5055b232019-12-12 17:49:31 +0100590 * \return \c 0 on failure (\p grpid is not recognized).
591 */
Paul Elliott8ff510a2020-06-02 17:19:28 +0100592static inline psa_ecc_family_t mbedtls_ecc_group_to_psa( mbedtls_ecp_group_id grpid,
Darryl Green2f0eb512020-04-24 15:21:14 +0100593 size_t *bits )
594{
595 switch( grpid )
596 {
597 case MBEDTLS_ECP_DP_SECP192R1:
598 *bits = 192;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100599 return( PSA_ECC_FAMILY_SECP_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100600 case MBEDTLS_ECP_DP_SECP224R1:
601 *bits = 224;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100602 return( PSA_ECC_FAMILY_SECP_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100603 case MBEDTLS_ECP_DP_SECP256R1:
604 *bits = 256;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100605 return( PSA_ECC_FAMILY_SECP_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100606 case MBEDTLS_ECP_DP_SECP384R1:
607 *bits = 384;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100608 return( PSA_ECC_FAMILY_SECP_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100609 case MBEDTLS_ECP_DP_SECP521R1:
610 *bits = 521;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100611 return( PSA_ECC_FAMILY_SECP_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100612 case MBEDTLS_ECP_DP_BP256R1:
613 *bits = 256;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100614 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100615 case MBEDTLS_ECP_DP_BP384R1:
616 *bits = 384;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100617 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100618 case MBEDTLS_ECP_DP_BP512R1:
619 *bits = 512;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100620 return( PSA_ECC_FAMILY_BRAINPOOL_P_R1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100621 case MBEDTLS_ECP_DP_CURVE25519:
622 *bits = 255;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100623 return( PSA_ECC_FAMILY_MONTGOMERY );
Darryl Green2f0eb512020-04-24 15:21:14 +0100624 case MBEDTLS_ECP_DP_SECP192K1:
625 *bits = 192;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100626 return( PSA_ECC_FAMILY_SECP_K1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100627 case MBEDTLS_ECP_DP_SECP224K1:
628 *bits = 224;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100629 return( PSA_ECC_FAMILY_SECP_K1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100630 case MBEDTLS_ECP_DP_SECP256K1:
631 *bits = 256;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100632 return( PSA_ECC_FAMILY_SECP_K1 );
Darryl Green2f0eb512020-04-24 15:21:14 +0100633 case MBEDTLS_ECP_DP_CURVE448:
634 *bits = 448;
Paul Elliott8ff510a2020-06-02 17:19:28 +0100635 return( PSA_ECC_FAMILY_MONTGOMERY );
Darryl Green2f0eb512020-04-24 15:21:14 +0100636 default:
637 *bits = 0;
638 return( 0 );
639 }
640}
Gilles Peskine5055b232019-12-12 17:49:31 +0100641
642/** Convert an ECC curve identifier from the PSA encoding to Mbed TLS.
643 *
644 * \note This function is provided solely for the convenience of
645 * Mbed TLS and may be removed at any time without notice.
646 *
647 * \param curve A PSA elliptic curve identifier
Paul Elliott8ff510a2020-06-02 17:19:28 +0100648 * (`PSA_ECC_FAMILY_xxx`).
Gilles Peskine2fa6b5f2021-01-27 15:44:45 +0100649 * \param bits The bit-length of a private key on \p curve.
650 * \param bits_is_sloppy If true, \p bits may be the bit-length rounded up
651 * to the nearest multiple of 8. This allows the caller
652 * to infer the exact curve from the length of a key
653 * which is supplied as a byte string.
Gilles Peskine5055b232019-12-12 17:49:31 +0100654 *
655 * \return The corresponding Mbed TLS elliptic curve identifier
656 * (`MBEDTLS_ECP_DP_xxx`).
657 * \return #MBEDTLS_ECP_DP_NONE if \c curve is not recognized.
Gilles Peskine2fa6b5f2021-01-27 15:44:45 +0100658 * \return #MBEDTLS_ECP_DP_NONE if \p bits is not
Gilles Peskine5055b232019-12-12 17:49:31 +0100659 * correct for \p curve.
660 */
Paul Elliott8ff510a2020-06-02 17:19:28 +0100661mbedtls_ecp_group_id mbedtls_ecc_group_of_psa( psa_ecc_family_t curve,
Gilles Peskine2fa6b5f2021-01-27 15:44:45 +0100662 size_t bits,
663 int bits_is_sloppy );
Gilles Peskine5055b232019-12-12 17:49:31 +0100664#endif /* MBEDTLS_ECP_C */
665
666/**@}*/
667
Gilles Peskineb8af2282020-11-13 18:00:34 +0100668/** \defgroup psa_external_rng External random generator
669 * @{
670 */
671
672#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
673/** External random generator function, implemented by the platform.
674 *
675 * When the compile-time option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled,
676 * this function replaces Mbed TLS's entropy and DRBG modules for all
677 * random generation triggered via PSA crypto interfaces.
678 *
Gilles Peskineb663a602020-11-18 15:27:37 +0100679 * \note This random generator must deliver random numbers with cryptographic
680 * quality and high performance. It must supply unpredictable numbers
681 * with a uniform distribution. The implementation of this function
682 * is responsible for ensuring that the random generator is seeded
683 * with sufficient entropy. If you have a hardware TRNG which is slow
684 * or delivers non-uniform output, declare it as an entropy source
685 * with mbedtls_entropy_add_source() instead of enabling this option.
686 *
Gilles Peskineb8af2282020-11-13 18:00:34 +0100687 * \param[in,out] context Pointer to the random generator context.
688 * This is all-bits-zero on the first call
689 * and preserved between successive calls.
690 * \param[out] output Output buffer. On success, this buffer
691 * contains random data with a uniform
692 * distribution.
693 * \param output_size The size of the \p output buffer in bytes.
694 * \param[out] output_length On success, set this value to \p output_size.
695 *
696 * \retval #PSA_SUCCESS
Gilles Peskinee995b9b2020-11-30 12:08:00 +0100697 * Success. The output buffer contains \p output_size bytes of
698 * cryptographic-quality random data, and \c *output_length is
699 * set to \p output_size.
700 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
701 * The random generator requires extra entropy and there is no
702 * way to obtain entropy under current environment conditions.
703 * This error should not happen under normal circumstances since
704 * this function is responsible for obtaining as much entropy as
705 * it needs. However implementations of this function may return
706 * #PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain
707 * entropy without blocking indefinitely.
Gilles Peskineb8af2282020-11-13 18:00:34 +0100708 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskinee995b9b2020-11-30 12:08:00 +0100709 * A failure of the random generator hardware that isn't covered
710 * by #PSA_ERROR_INSUFFICIENT_ENTROPY.
Gilles Peskineb8af2282020-11-13 18:00:34 +0100711 */
712psa_status_t mbedtls_psa_external_get_random(
713 mbedtls_psa_external_random_context_t *context,
714 uint8_t *output, size_t output_size, size_t *output_length );
715#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
716
717/**@}*/
718
Steven Cooreman6801f082021-02-19 17:21:22 +0100719/** \defgroup psa_builtin_keys Built-in keys
720 * @{
721 */
722
723/** The minimum value for a key identifier that is built into the
724 * implementation.
725 *
726 * The range of key identifiers from #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN
727 * to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX within the range from
728 * #PSA_KEY_ID_VENDOR_MIN and #PSA_KEY_ID_VENDOR_MAX and must not intersect
729 * with any other set of implementation-chosen key identifiers.
730 *
731 * This value is part of the library's ABI since changing it would invalidate
732 * the values of built-in key identifiers in applications.
733 */
734#define MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ((psa_key_id_t)0x7fff0000)
735
736/** The maximum value for a key identifier that is built into the
737 * implementation.
738 *
739 * See #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN for more information.
740 */
741#define MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ((psa_key_id_t)0x7fffefff)
742
743/** A slot number identifying a key in a driver.
744 *
745 * Values of this type are used to identify built-in keys.
746 */
747typedef uint64_t psa_drv_slot_number_t;
748
749#if defined(MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS)
750/** Test whether a key identifier belongs to the builtin key range.
751 *
752 * \param key_id Key identifier to test.
753 *
754 * \retval 1
755 * The key identifier is a builtin key identifier.
756 * \retval 0
757 * The key identifier is not a builtin key identifier.
758 */
759static inline int psa_key_id_is_builtin( psa_key_id_t key_id )
760{
761 return( ( key_id >= MBEDTLS_PSA_KEY_ID_BUILTIN_MIN ) &&
762 ( key_id <= MBEDTLS_PSA_KEY_ID_BUILTIN_MAX ) );
763}
764
Steven Cooremanb938b0b2021-04-06 13:08:42 +0200765/** Platform function to obtain the location and slot number of a built-in key.
Steven Cooreman6801f082021-02-19 17:21:22 +0100766 *
767 * An application-specific implementation of this function must be provided if
Steven Cooreman203bcbb2021-03-18 17:17:40 +0100768 * #MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled. This would typically be provided
Steven Cooreman6801f082021-02-19 17:21:22 +0100769 * as part of a platform's system image.
770 *
Steven Cooremanc8b95342021-03-18 20:48:06 +0100771 * #MBEDTLS_SVC_KEY_ID_GET_KEY_ID(\p key_id) needs to be in the range from
Steven Cooreman6801f082021-02-19 17:21:22 +0100772 * #MBEDTLS_PSA_KEY_ID_BUILTIN_MIN to #MBEDTLS_PSA_KEY_ID_BUILTIN_MAX.
773 *
774 * In a multi-application configuration
775 * (\c MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER is defined),
776 * this function should check that #MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(\p key_id)
777 * is allowed to use the given key.
778 *
Steven Cooremanc8b95342021-03-18 20:48:06 +0100779 * \param key_id The key ID for which to retrieve the
780 * location and slot attributes.
781 * \param[out] lifetime On success, the lifetime associated with the key
782 * corresponding to \p key_id. Lifetime is a
783 * combination of which driver contains the key,
Steven Cooreman31e27af2021-04-14 10:32:05 +0200784 * and with what persistence level the key is
785 * intended to be used. If the platform
786 * implementation does not contain specific
787 * information about the intended key persistence
788 * level, the persistence level may be reported as
789 * #PSA_KEY_PERSISTENCE_DEFAULT.
Steven Cooremanc8b95342021-03-18 20:48:06 +0100790 * \param[out] slot_number On success, the slot number known to the driver
791 * registered at the lifetime location reported
Steven Cooremanb938b0b2021-04-06 13:08:42 +0200792 * through \p lifetime which corresponds to the
Steven Cooreman6801f082021-02-19 17:21:22 +0100793 * requested built-in key.
794 *
795 * \retval #PSA_SUCCESS
796 * The requested key identifier designates a built-in key.
797 * In a multi-application configuration, the requested owner
798 * is allowed to access it.
799 * \retval #PSA_ERROR_DOES_NOT_EXIST
800 * The requested key identifier is not a built-in key which is known
801 * to this function. If a key exists in the key storage with this
802 * identifier, the data from the storage will be used.
Steven Cooreman203bcbb2021-03-18 17:17:40 +0100803 * \return (any other error)
Steven Cooreman6801f082021-02-19 17:21:22 +0100804 * Any other error is propagated to the function that requested the key.
805 * Common errors include:
806 * - #PSA_ERROR_NOT_PERMITTED: the key exists but the requested owner
807 * is not allowed to access it.
808 */
809psa_status_t mbedtls_psa_platform_get_builtin_key(
Steven Cooremanc8b95342021-03-18 20:48:06 +0100810 mbedtls_svc_key_id_t key_id,
811 psa_key_lifetime_t *lifetime,
812 psa_drv_slot_number_t *slot_number );
Steven Cooreman6801f082021-02-19 17:21:22 +0100813#endif /* MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS */
814
815/** @} */
816
Gilles Peskinee59236f2018-01-27 23:32:46 +0100817#ifdef __cplusplus
818}
819#endif
820
821#endif /* PSA_CRYPTO_EXTRA_H */