blob: 130ce7544beb93fa3b9baec646a6136075a8a2cc [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
Jaeden Amero81cefed2019-02-25 08:51:27 +000033#include "mbedtls/platform_util.h"
34
Gilles Peskinee59236f2018-01-27 23:32:46 +010035#ifdef __cplusplus
36extern "C" {
37#endif
38
Netanel Gonen2bcd3122018-11-19 11:53:02 +020039/* UID for secure storage seed */
avolinski0d2c2662018-11-21 17:31:07 +020040#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
Netanel Gonen2bcd3122018-11-19 11:53:02 +020041
Jaeden Amero5e6d24c2019-02-21 10:41:29 +000042/*
43 * Deprecated PSA Crypto error code definitions
44 */
45#if !defined(MBEDTLS_DEPRECATED_REMOVED)
46#define PSA_ERROR_UNKNOWN_ERROR \
47 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
48#endif
49
50#if !defined(MBEDTLS_DEPRECATED_REMOVED)
51#define PSA_ERROR_OCCUPIED_SLOT \
52 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
53#endif
54
55#if !defined(MBEDTLS_DEPRECATED_REMOVED)
56#define PSA_ERROR_EMPTY_SLOT \
57 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
58#endif
59
60#if !defined(MBEDTLS_DEPRECATED_REMOVED)
61#define PSA_ERROR_INSUFFICIENT_CAPACITY \
62 MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
63#endif
64
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020065/** \addtogroup attributes
66 * @{
67 */
68
69/** \brief Declare the enrollment algorithm for a key.
70 *
71 * An operation on a key may indifferently use the algorithm set with
72 * psa_set_key_algorithm() or with this function.
73 *
74 * \param[out] attributes The attribute structure to write to.
75 * \param alg2 A second algorithm that the key may be used
76 * for, in addition to the algorithm set with
77 * psa_set_key_algorithm().
78 *
79 * \warning Setting an enrollment algorithm is not recommended, because
80 * using the same key with different algorithms can allow some
81 * attacks based on arithmetic relations between different
82 * computations made with the same key, or can escalate harmless
83 * side channels into exploitable ones. Use this function only
Gilles Peskinef25c9ec2019-05-22 11:45:59 +020084 * if it is necessary to support a protocol for which it has been
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020085 * verified that the usage of the key with multiple algorithms
86 * is safe.
87 */
88static inline void psa_set_key_enrollment_algorithm(
89 psa_key_attributes_t *attributes,
90 psa_algorithm_t alg2)
91{
Gilles Peskine7e0cff92019-07-30 13:48:52 +020092 attributes->core.policy.alg2 = alg2;
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020093}
94
95/** Retrieve the enrollment algorithm policy from key attributes.
96 *
97 * \param[in] attributes The key attribute structure to query.
98 *
99 * \return The enrollment algorithm stored in the attribute structure.
100 */
101static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
102 const psa_key_attributes_t *attributes)
103{
Gilles Peskine7e0cff92019-07-30 13:48:52 +0200104 return( attributes->core.policy.alg2 );
Gilles Peskine96f0b3b2019-05-10 19:33:38 +0200105}
106
Gilles Peskinec8000c02019-08-02 20:15:51 +0200107#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
108
109/** Retrieve the slot number where a key is stored.
110 *
111 * A slot number is only defined for keys that are stored in a secure
112 * element.
113 *
114 * This information is only useful if the secure element is not entirely
115 * managed through the PSA Cryptography API. It is up to the secure
116 * element driver to decide how PSA slot numbers map to any other interface
117 * that the secure element may have.
118 *
119 * \param[in] attributes The key attribute structure to query.
120 * \param[out] slot_number On success, the slot number containing the key.
121 *
122 * \retval #PSA_SUCCESS
123 * The key is located in a secure element, and \p *slot_number
124 * indicates the slot number that contains it.
125 * \retval #PSA_ERROR_NOT_PERMITTED
126 * The caller is not permitted to query the slot number.
127 * Mbed Crypto currently does not return this error.
128 * \retval #PSA_ERROR_INVALID_ARGUMENT
129 * The key is not located in a secure element.
130 */
131psa_status_t psa_get_key_slot_number(
132 const psa_key_attributes_t *attributes,
133 psa_key_slot_number_t *slot_number );
134
135/** Choose the slot number where a key is stored.
136 *
137 * This function declares a slot number in the specified attribute
138 * structure.
139 *
140 * A slot number is only meaningful for keys that are stored in a secure
141 * element. It is up to the secure element driver to decide how PSA slot
142 * numbers map to any other interface that the secure element may have.
143 *
144 * \note Setting a slot number in key attributes for a key creation can
145 * cause the following errors when creating the key:
146 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
147 * not support choosing a specific slot number.
148 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
149 * choose slot numbers in general or to choose this specific slot.
150 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
151 * valid in general or not valid for this specific key.
152 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
153 * selected slot.
154 *
155 * \param[out] attributes The attribute structure to write to.
156 * \param slot_number The slot number to set.
157 */
158static inline void psa_set_key_slot_number(
159 psa_key_attributes_t *attributes,
160 psa_key_slot_number_t slot_number )
161{
162 attributes->core.flags |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
163 attributes->slot_number = slot_number;
164}
165
Gilles Peskine5fe5e272019-08-02 20:30:01 +0200166/** Remove the slot number attribute from a key attribute structure.
167 *
168 * This function undoes the action of psa_set_key_slot_number().
169 *
170 * \param[out] attributes The attribute structure to write to.
171 */
172static inline void psa_clear_key_slot_number(
173 psa_key_attributes_t *attributes )
174{
175 attributes->core.flags &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
176}
177
Gilles Peskinec8000c02019-08-02 20:15:51 +0200178#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
179
Gilles Peskine96f0b3b2019-05-10 19:33:38 +0200180/**@}*/
181
Gilles Peskinee59236f2018-01-27 23:32:46 +0100182/**
183 * \brief Library deinitialization.
184 *
185 * This function clears all data associated with the PSA layer,
186 * including the whole key store.
187 *
188 * This is an Mbed TLS extension.
189 */
190void mbedtls_psa_crypto_free( void );
191
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200192/** \brief Statistics about
193 * resource consumption related to the PSA keystore.
194 *
195 * \note The content of this structure is not part of the stable API and ABI
196 * of Mbed Crypto and may change arbitrarily from version to version.
197 */
198typedef struct mbedtls_psa_stats_s
199{
200 /** Number of slots containing key material for a volatile key. */
201 size_t volatile_slots;
202 /** Number of slots containing key material for a key which is in
203 * internal persistent storage. */
204 size_t persistent_slots;
205 /** Number of slots containing a reference to a key in a
206 * secure element. */
207 size_t external_slots;
208 /** Number of slots which are occupied, but do not contain
209 * key material yet. */
210 size_t half_filled_slots;
211 /** Number of slots that contain cache data. */
212 size_t cache_slots;
213 /** Number of slots that are not used for anything. */
214 size_t empty_slots;
215 /** Largest key id value among open keys in internal persistent storage. */
216 psa_key_id_t max_open_internal_key_id;
217 /** Largest key id value among open keys in secure elements. */
218 psa_key_id_t max_open_external_key_id;
219} mbedtls_psa_stats_t;
220
221/** \brief Get statistics about
222 * resource consumption related to the PSA keystore.
223 *
224 * \note When Mbed Crypto is built as part of a service, with isolation
225 * between the application and the keystore, the service may or
226 * may not expose this function.
227 */
228void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200229
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200230/**
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100231 * \brief Inject an initial entropy seed for the random generator into
232 * secure storage.
Gilles Peskine0338ded2018-11-15 18:19:27 +0100233 *
234 * This function injects data to be used as a seed for the random generator
235 * used by the PSA Crypto implementation. On devices that lack a trusted
236 * entropy source (preferably a hardware random number generator),
237 * the Mbed PSA Crypto implementation uses this value to seed its
238 * random generator.
239 *
240 * On devices without a trusted entropy source, this function must be
241 * called exactly once in the lifetime of the device. On devices with
242 * a trusted entropy source, calling this function is optional.
243 * In all cases, this function may only be called before calling any
244 * other function in the PSA Crypto API, including psa_crypto_init().
245 *
246 * When this function returns successfully, it populates a file in
247 * persistent storage. Once the file has been created, this function
248 * can no longer succeed.
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100249 *
250 * If any error occurs, this function does not change the system state.
251 * You can call this function again after correcting the reason for the
252 * error if possible.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200253 *
254 * \warning This function **can** fail! Callers MUST check the return status.
255 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100256 * \warning If you use this function, you should use it as part of a
257 * factory provisioning process. The value of the injected seed
258 * is critical to the security of the device. It must be
259 * *secret*, *unpredictable* and (statistically) *unique per device*.
260 * You should be generate it randomly using a cryptographically
261 * secure random generator seeded from trusted entropy sources.
262 * You should transmit it securely to the device and ensure
263 * that its value is not leaked or stored anywhere beyond the
264 * needs of transmitting it from the point of generation to
265 * the call of this function, and erase all copies of the value
266 * once this function returns.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200267 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100268 * This is an Mbed TLS extension.
269 *
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200270 * \note This function is only available on the following platforms:
Gilles Peskinee3dbdd82019-02-25 11:04:06 +0100271 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
272 * Note that you must provide compatible implementations of
273 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200274 * * In a client-server integration of PSA Cryptography, on the client side,
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200275 * if the server supports this feature.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200276 * \param[in] seed Buffer containing the seed value to inject.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200277 * \param[in] seed_size Size of the \p seed buffer.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200278 * The size of the seed in bytes must be greater
279 * or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
280 * and #MBEDTLS_ENTROPY_BLOCK_SIZE.
281 * It must be less or equal to
282 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200283 *
284 * \retval #PSA_SUCCESS
Gilles Peskine0338ded2018-11-15 18:19:27 +0100285 * The seed value was injected successfully. The random generator
286 * of the PSA Crypto implementation is now ready for use.
287 * You may now call psa_crypto_init() and use the PSA Crypto
288 * implementation.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200289 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100290 * \p seed_size is out of range.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200291 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine0338ded2018-11-15 18:19:27 +0100292 * There was a failure reading or writing from storage.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200293 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine0338ded2018-11-15 18:19:27 +0100294 * The library has already been initialized. It is no longer
295 * possible to call this function.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200296 */
Gilles Peskine7228da22019-07-15 11:06:15 +0200297psa_status_t mbedtls_psa_inject_entropy(uint8_t *seed,
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200298 size_t seed_size);
299
Janos Follath71a4c912019-06-11 09:14:47 +0100300#if defined(PSA_PRE_1_0_KEY_DERIVATION)
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100301/** Set up a key derivation operation.
302 *
303 * FIMXE This function is no longer part of the official API. Its prototype
304 * is only kept around for the sake of tests that haven't been updated yet.
305 *
Gilles Peskine3be6b7f2019-03-05 19:32:26 +0100306 * A key derivation algorithm takes three inputs: a secret input \p handle and
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100307 * two non-secret inputs \p label and p salt.
308 * The result of this function is a byte generator which can
309 * be used to produce keys and other cryptographic material.
310 *
311 * The role of \p label and \p salt is as follows:
312 * - For HKDF (#PSA_ALG_HKDF), \p salt is the salt used in the "extract" step
313 * and \p label is the info string used in the "expand" step.
314 *
Gilles Peskinecf7292e2019-05-16 17:53:40 +0200315 * \param[in,out] operation The key derivation object to set up. It must
316 * have been initialized as per the documentation
317 * for #psa_key_derivation_operation_t and not
318 * yet be in use.
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100319 * \param handle Handle to the secret key.
320 * \param alg The key derivation algorithm to compute
321 * (\c PSA_ALG_XXX value such that
322 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
323 * \param[in] salt Salt to use.
324 * \param salt_length Size of the \p salt buffer in bytes.
325 * \param[in] label Label to use.
326 * \param label_length Size of the \p label buffer in bytes.
327 * \param capacity The maximum number of bytes that the
Gilles Peskine35675b62019-05-16 17:26:11 +0200328 * operation will be able to provide.
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100329 *
330 * \retval #PSA_SUCCESS
331 * Success.
332 * \retval #PSA_ERROR_INVALID_HANDLE
333 * \retval #PSA_ERROR_EMPTY_SLOT
334 * \retval #PSA_ERROR_NOT_PERMITTED
335 * \retval #PSA_ERROR_INVALID_ARGUMENT
336 * \c key is not compatible with \c alg,
337 * or \p capacity is too large for the specified algorithm and key.
338 * \retval #PSA_ERROR_NOT_SUPPORTED
339 * \c alg is not supported or is not a key derivation algorithm.
340 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
341 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
342 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200343 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100344 * \retval #PSA_ERROR_BAD_STATE
345 * The library has not been previously initialized by psa_crypto_init().
346 * It is implementation-dependent whether a failure to initialize
347 * results in this error code.
348 */
Gilles Peskine35675b62019-05-16 17:26:11 +0200349psa_status_t psa_key_derivation(psa_key_derivation_operation_t *operation,
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100350 psa_key_handle_t handle,
351 psa_algorithm_t alg,
352 const uint8_t *salt,
353 size_t salt_length,
354 const uint8_t *label,
355 size_t label_length,
356 size_t capacity);
Janos Follath71a4c912019-06-11 09:14:47 +0100357#endif /* PSA_PRE_1_0_KEY_DERIVATION */
Gilles Peskine5dcd3ce2019-01-18 16:41:31 +0100358
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200359/** \addtogroup crypto_types
360 * @{
361 */
362
Gilles Peskinea1302192019-05-16 13:58:24 +0200363/** DSA public key.
364 *
365 * The import and export format is the
366 * representation of the public key `y = g^x mod p` as a big-endian byte
367 * string. The length of the byte string is the length of the base prime `p`
368 * in bytes.
369 */
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200370#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x60020000)
Gilles Peskinea1302192019-05-16 13:58:24 +0200371
372/** DSA key pair (private and public key).
373 *
374 * The import and export format is the
375 * representation of the private key `x` as a big-endian byte string. The
376 * length of the byte string is the private key size in bytes (leading zeroes
377 * are not stripped).
378 *
379 * Determinstic DSA key derivation with psa_generate_derived_key follows
380 * FIPS 186-4 §B.1.2: interpret the byte string as integer
381 * in big-endian order. Discard it if it is not in the range
382 * [0, *N* - 2] where *N* is the boundary of the private key domain
383 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
384 * or the order of the curve's base point for ECC).
385 * Add 1 to the resulting integer and use this as the private key *x*.
386 *
387 */
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200388#define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t)0x70020000)
Gilles Peskinea1302192019-05-16 13:58:24 +0200389
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200390/** Whether a key type is an DSA key (pair or public-only). */
391#define PSA_KEY_TYPE_IS_DSA(type) \
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200392 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200393
394#define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x10040000)
395/** DSA signature with hashing.
396 *
397 * This is the signature scheme defined by FIPS 186-4,
398 * with a random per-message secret number (*k*).
399 *
400 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
401 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
402 * This includes #PSA_ALG_ANY_HASH
403 * when specifying the algorithm in a usage policy.
404 *
405 * \return The corresponding DSA signature algorithm.
406 * \return Unspecified if \p hash_alg is not a supported
407 * hash algorithm.
408 */
409#define PSA_ALG_DSA(hash_alg) \
410 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
411#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x10050000)
412#define PSA_ALG_DSA_DETERMINISTIC_FLAG ((psa_algorithm_t)0x00010000)
413/** Deterministic DSA signature with hashing.
414 *
415 * This is the deterministic variant defined by RFC 6979 of
416 * the signature scheme defined by FIPS 186-4.
417 *
418 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
419 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
420 * This includes #PSA_ALG_ANY_HASH
421 * when specifying the algorithm in a usage policy.
422 *
423 * \return The corresponding DSA signature algorithm.
424 * \return Unspecified if \p hash_alg is not a supported
425 * hash algorithm.
426 */
427#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
428 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
429#define PSA_ALG_IS_DSA(alg) \
430 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
431 PSA_ALG_DSA_BASE)
432#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
433 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
434#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
435 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
436#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
437 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
438
439
440/* We need to expand the sample definition of this macro from
441 * the API definition. */
442#undef PSA_ALG_IS_HASH_AND_SIGN
443#define PSA_ALG_IS_HASH_AND_SIGN(alg) \
444 (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
445 PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg))
446
447/**@}*/
448
Gilles Peskine24f10f82019-05-16 12:18:32 +0200449/** \addtogroup attributes
450 * @{
451 */
452
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200453/** Custom Diffie-Hellman group.
454 *
455 * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200456 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM), the group data comes
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200457 * from domain parameters set by psa_set_key_domain_parameters().
458 */
459/* This value is reserved for private use in the TLS named group registry. */
460#define PSA_DH_GROUP_CUSTOM ((psa_dh_group_t) 0x01fc)
461
462
Gilles Peskine24f10f82019-05-16 12:18:32 +0200463/**
464 * \brief Set domain parameters for a key.
465 *
466 * Some key types require additional domain parameters in addition to
467 * the key type identifier and the key size. Use this function instead
468 * of psa_set_key_type() when you need to specify domain parameters.
469 *
470 * The format for the required domain parameters varies based on the key type.
471 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200472 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200473 * the domain parameter data consists of the public exponent,
474 * represented as a big-endian integer with no leading zeros.
475 * This information is used when generating an RSA key pair.
476 * When importing a key, the public exponent is read from the imported
477 * key data and the exponent recorded in the attribute structure is ignored.
478 * As an exception, the public exponent 65537 is represented by an empty
479 * byte string.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200480 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200481 * the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
482 * ```
483 * Dss-Parms ::= SEQUENCE {
484 * p INTEGER,
485 * q INTEGER,
486 * g INTEGER
487 * }
488 * ```
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200489 * - For Diffie-Hellman key exchange keys
490 * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200491 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM)), the
Gilles Peskine24f10f82019-05-16 12:18:32 +0200492 * `DomainParameters` format as defined by RFC 3279 §2.3.3.
493 * ```
494 * DomainParameters ::= SEQUENCE {
495 * p INTEGER, -- odd prime, p=jq +1
496 * g INTEGER, -- generator, g
497 * q INTEGER, -- factor of p-1
498 * j INTEGER OPTIONAL, -- subgroup factor
499 * validationParms ValidationParms OPTIONAL
500 * }
501 * ValidationParms ::= SEQUENCE {
502 * seed BIT STRING,
503 * pgenCounter INTEGER
504 * }
505 * ```
506 *
507 * \note This function may allocate memory or other resources.
508 * Once you have called this function on an attribute structure,
509 * you must call psa_reset_key_attributes() to free these resources.
510 *
511 * \note This is an experimental extension to the interface. It may change
512 * in future versions of the library.
513 *
514 * \param[in,out] attributes Attribute structure where the specified domain
515 * parameters will be stored.
516 * If this function fails, the content of
517 * \p attributes is not modified.
518 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
519 * \param[in] data Buffer containing the key domain parameters.
520 * The content of this buffer is interpreted
521 * according to \p type as described above.
522 * \param data_length Size of the \p data buffer in bytes.
523 *
524 * \retval #PSA_SUCCESS
525 * \retval #PSA_ERROR_INVALID_ARGUMENT
526 * \retval #PSA_ERROR_NOT_SUPPORTED
527 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
528 */
529psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
530 psa_key_type_t type,
531 const uint8_t *data,
532 size_t data_length);
533
534/**
535 * \brief Get domain parameters for a key.
536 *
537 * Get the domain parameters for a key with this function, if any. The format
538 * of the domain parameters written to \p data is specified in the
539 * documentation for psa_set_key_domain_parameters().
540 *
541 * \note This is an experimental extension to the interface. It may change
542 * in future versions of the library.
543 *
544 * \param[in] attributes The key attribute structure to query.
545 * \param[out] data On success, the key domain parameters.
546 * \param data_size Size of the \p data buffer in bytes.
547 * The buffer is guaranteed to be large
548 * enough if its size in bytes is at least
549 * the value given by
550 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
551 * \param[out] data_length On success, the number of bytes
552 * that make up the key domain parameters data.
553 *
554 * \retval #PSA_SUCCESS
555 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
556 */
557psa_status_t psa_get_key_domain_parameters(
558 const psa_key_attributes_t *attributes,
559 uint8_t *data,
560 size_t data_size,
561 size_t *data_length);
562
563/** Safe output buffer size for psa_get_key_domain_parameters().
564 *
565 * This macro returns a compile-time constant if its arguments are
566 * compile-time constants.
567 *
568 * \warning This function may call its arguments multiple times or
569 * zero times, so you should not pass arguments that contain
570 * side effects.
571 *
572 * \note This is an experimental extension to the interface. It may change
573 * in future versions of the library.
574 *
575 * \param key_type A supported key type.
576 * \param key_bits The size of the key in bits.
577 *
578 * \return If the parameters are valid and supported, return
579 * a buffer size in bytes that guarantees that
580 * psa_get_key_domain_parameters() will not fail with
581 * #PSA_ERROR_BUFFER_TOO_SMALL.
582 * If the parameters are a valid combination that is not supported
Gilles Peskine27a983d2019-05-16 17:24:53 +0200583 * by the implementation, this macro shall return either a
Gilles Peskine24f10f82019-05-16 12:18:32 +0200584 * sensible size or 0.
585 * If the parameters are not valid, the
586 * return value is unspecified.
587 */
588#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
589 (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
590 PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
591 PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
592 0)
593#define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
594 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
595#define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
596 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
597
598/**@}*/
599
Gilles Peskinee59236f2018-01-27 23:32:46 +0100600#ifdef __cplusplus
601}
602#endif
603
604#endif /* PSA_CRYPTO_EXTRA_H */