blob: 62b4c2ee4af3b18ec987024b5f8dc722060a3108 [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 Peskine7a894f22019-11-26 16:06:46 +010035#include "crypto_compat.h"
36
Gilles Peskinee59236f2018-01-27 23:32:46 +010037#ifdef __cplusplus
38extern "C" {
39#endif
40
Netanel Gonen2bcd3122018-11-19 11:53:02 +020041/* UID for secure storage seed */
avolinski0d2c2662018-11-21 17:31:07 +020042#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
Netanel Gonen2bcd3122018-11-19 11:53:02 +020043
Jaeden Amero5e6d24c2019-02-21 10:41:29 +000044
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020045/** \addtogroup attributes
46 * @{
47 */
48
49/** \brief Declare the enrollment algorithm for a key.
50 *
51 * An operation on a key may indifferently use the algorithm set with
52 * psa_set_key_algorithm() or with this function.
53 *
54 * \param[out] attributes The attribute structure to write to.
55 * \param alg2 A second algorithm that the key may be used
56 * for, in addition to the algorithm set with
57 * psa_set_key_algorithm().
58 *
59 * \warning Setting an enrollment algorithm is not recommended, because
60 * using the same key with different algorithms can allow some
61 * attacks based on arithmetic relations between different
62 * computations made with the same key, or can escalate harmless
63 * side channels into exploitable ones. Use this function only
Gilles Peskinef25c9ec2019-05-22 11:45:59 +020064 * if it is necessary to support a protocol for which it has been
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020065 * verified that the usage of the key with multiple algorithms
66 * is safe.
67 */
68static inline void psa_set_key_enrollment_algorithm(
69 psa_key_attributes_t *attributes,
70 psa_algorithm_t alg2)
71{
Gilles Peskine7e0cff92019-07-30 13:48:52 +020072 attributes->core.policy.alg2 = alg2;
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020073}
74
75/** Retrieve the enrollment algorithm policy from key attributes.
76 *
77 * \param[in] attributes The key attribute structure to query.
78 *
79 * \return The enrollment algorithm stored in the attribute structure.
80 */
81static inline psa_algorithm_t psa_get_key_enrollment_algorithm(
82 const psa_key_attributes_t *attributes)
83{
Gilles Peskine7e0cff92019-07-30 13:48:52 +020084 return( attributes->core.policy.alg2 );
Gilles Peskine96f0b3b2019-05-10 19:33:38 +020085}
86
Gilles Peskinec8000c02019-08-02 20:15:51 +020087#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
88
89/** Retrieve the slot number where a key is stored.
90 *
91 * A slot number is only defined for keys that are stored in a secure
92 * element.
93 *
94 * This information is only useful if the secure element is not entirely
95 * managed through the PSA Cryptography API. It is up to the secure
96 * element driver to decide how PSA slot numbers map to any other interface
97 * that the secure element may have.
98 *
99 * \param[in] attributes The key attribute structure to query.
100 * \param[out] slot_number On success, the slot number containing the key.
101 *
102 * \retval #PSA_SUCCESS
103 * The key is located in a secure element, and \p *slot_number
104 * indicates the slot number that contains it.
105 * \retval #PSA_ERROR_NOT_PERMITTED
106 * The caller is not permitted to query the slot number.
107 * Mbed Crypto currently does not return this error.
108 * \retval #PSA_ERROR_INVALID_ARGUMENT
109 * The key is not located in a secure element.
110 */
111psa_status_t psa_get_key_slot_number(
112 const psa_key_attributes_t *attributes,
113 psa_key_slot_number_t *slot_number );
114
115/** Choose the slot number where a key is stored.
116 *
117 * This function declares a slot number in the specified attribute
118 * structure.
119 *
120 * A slot number is only meaningful for keys that are stored in a secure
121 * element. It is up to the secure element driver to decide how PSA slot
122 * numbers map to any other interface that the secure element may have.
123 *
124 * \note Setting a slot number in key attributes for a key creation can
125 * cause the following errors when creating the key:
126 * - #PSA_ERROR_NOT_SUPPORTED if the selected secure element does
127 * not support choosing a specific slot number.
128 * - #PSA_ERROR_NOT_PERMITTED if the caller is not permitted to
129 * choose slot numbers in general or to choose this specific slot.
130 * - #PSA_ERROR_INVALID_ARGUMENT if the chosen slot number is not
131 * valid in general or not valid for this specific key.
132 * - #PSA_ERROR_ALREADY_EXISTS if there is already a key in the
133 * selected slot.
134 *
135 * \param[out] attributes The attribute structure to write to.
136 * \param slot_number The slot number to set.
137 */
138static inline void psa_set_key_slot_number(
139 psa_key_attributes_t *attributes,
140 psa_key_slot_number_t slot_number )
141{
142 attributes->core.flags |= MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
143 attributes->slot_number = slot_number;
144}
145
Gilles Peskine5fe5e272019-08-02 20:30:01 +0200146/** Remove the slot number attribute from a key attribute structure.
147 *
148 * This function undoes the action of psa_set_key_slot_number().
149 *
150 * \param[out] attributes The attribute structure to write to.
151 */
152static inline void psa_clear_key_slot_number(
153 psa_key_attributes_t *attributes )
154{
155 attributes->core.flags &= ~MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER;
156}
157
Gilles Peskined7729582019-08-05 15:55:54 +0200158/** Register a key that is already present in a secure element.
159 *
160 * The key must be located in a secure element designated by the
161 * lifetime field in \p attributes, in the slot set with
162 * psa_set_key_slot_number() in the attribute structure.
163 * This function makes the key available through the key identifier
164 * specified in \p attributes.
165 *
166 * \param[in] attributes The attributes of the existing key.
167 *
168 * \retval #PSA_SUCCESS
169 * The key was successfully registered.
170 * Note that depending on the design of the driver, this may or may
171 * not guarantee that a key actually exists in the designated slot
172 * and is compatible with the specified attributes.
173 * \retval #PSA_ERROR_ALREADY_EXISTS
174 * There is already a key with the identifier specified in
175 * \p attributes.
Gilles Peskine3efcebb2019-10-01 14:18:35 +0200176 * \retval #PSA_ERROR_NOT_SUPPORTED
177 * The secure element driver for the specified lifetime does not
178 * support registering a key.
Gilles Peskined7729582019-08-05 15:55:54 +0200179 * \retval #PSA_ERROR_INVALID_ARGUMENT
180 * \p attributes specifies a lifetime which is not located
181 * in a secure element.
182 * \retval #PSA_ERROR_INVALID_ARGUMENT
183 * No slot number is specified in \p attributes,
184 * or the specified slot number is not valid.
185 * \retval #PSA_ERROR_NOT_PERMITTED
186 * The caller is not authorized to register the specified key slot.
187 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
188 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
189 * \retval #PSA_ERROR_HARDWARE_FAILURE
190 * \retval #PSA_ERROR_CORRUPTION_DETECTED
191 * \retval #PSA_ERROR_BAD_STATE
192 * The library has not been previously initialized by psa_crypto_init().
193 * It is implementation-dependent whether a failure to initialize
194 * results in this error code.
195 */
196psa_status_t mbedtls_psa_register_se_key(
197 const psa_key_attributes_t *attributes);
198
Gilles Peskinec8000c02019-08-02 20:15:51 +0200199#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
200
Gilles Peskine96f0b3b2019-05-10 19:33:38 +0200201/**@}*/
202
Gilles Peskinee59236f2018-01-27 23:32:46 +0100203/**
204 * \brief Library deinitialization.
205 *
206 * This function clears all data associated with the PSA layer,
207 * including the whole key store.
208 *
209 * This is an Mbed TLS extension.
210 */
211void mbedtls_psa_crypto_free( void );
212
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200213/** \brief Statistics about
214 * resource consumption related to the PSA keystore.
215 *
216 * \note The content of this structure is not part of the stable API and ABI
217 * of Mbed Crypto and may change arbitrarily from version to version.
218 */
219typedef struct mbedtls_psa_stats_s
220{
221 /** Number of slots containing key material for a volatile key. */
222 size_t volatile_slots;
223 /** Number of slots containing key material for a key which is in
224 * internal persistent storage. */
225 size_t persistent_slots;
226 /** Number of slots containing a reference to a key in a
227 * secure element. */
228 size_t external_slots;
229 /** Number of slots which are occupied, but do not contain
230 * key material yet. */
231 size_t half_filled_slots;
232 /** Number of slots that contain cache data. */
233 size_t cache_slots;
234 /** Number of slots that are not used for anything. */
235 size_t empty_slots;
236 /** Largest key id value among open keys in internal persistent storage. */
Jaeden Amero6fa62a52019-08-20 17:43:48 +0100237 psa_app_key_id_t max_open_internal_key_id;
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200238 /** Largest key id value among open keys in secure elements. */
Jaeden Amero6fa62a52019-08-20 17:43:48 +0100239 psa_app_key_id_t max_open_external_key_id;
Gilles Peskine4bac9a42019-05-23 20:32:30 +0200240} mbedtls_psa_stats_t;
241
242/** \brief Get statistics about
243 * resource consumption related to the PSA keystore.
244 *
245 * \note When Mbed Crypto is built as part of a service, with isolation
246 * between the application and the keystore, the service may or
247 * may not expose this function.
248 */
249void mbedtls_psa_get_stats( mbedtls_psa_stats_t *stats );
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200250
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200251/**
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100252 * \brief Inject an initial entropy seed for the random generator into
253 * secure storage.
Gilles Peskine0338ded2018-11-15 18:19:27 +0100254 *
255 * This function injects data to be used as a seed for the random generator
256 * used by the PSA Crypto implementation. On devices that lack a trusted
257 * entropy source (preferably a hardware random number generator),
258 * the Mbed PSA Crypto implementation uses this value to seed its
259 * random generator.
260 *
261 * On devices without a trusted entropy source, this function must be
262 * called exactly once in the lifetime of the device. On devices with
263 * a trusted entropy source, calling this function is optional.
264 * In all cases, this function may only be called before calling any
265 * other function in the PSA Crypto API, including psa_crypto_init().
266 *
267 * When this function returns successfully, it populates a file in
268 * persistent storage. Once the file has been created, this function
269 * can no longer succeed.
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100270 *
271 * If any error occurs, this function does not change the system state.
272 * You can call this function again after correcting the reason for the
273 * error if possible.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200274 *
275 * \warning This function **can** fail! Callers MUST check the return status.
276 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100277 * \warning If you use this function, you should use it as part of a
278 * factory provisioning process. The value of the injected seed
279 * is critical to the security of the device. It must be
280 * *secret*, *unpredictable* and (statistically) *unique per device*.
281 * You should be generate it randomly using a cryptographically
282 * secure random generator seeded from trusted entropy sources.
283 * You should transmit it securely to the device and ensure
284 * that its value is not leaked or stored anywhere beyond the
285 * needs of transmitting it from the point of generation to
286 * the call of this function, and erase all copies of the value
287 * once this function returns.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200288 *
Gilles Peskine0338ded2018-11-15 18:19:27 +0100289 * This is an Mbed TLS extension.
290 *
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200291 * \note This function is only available on the following platforms:
Gilles Peskinee3dbdd82019-02-25 11:04:06 +0100292 * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
293 * Note that you must provide compatible implementations of
294 * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200295 * * In a client-server integration of PSA Cryptography, on the client side,
Netanel Gonen1d7195f2018-11-22 16:24:48 +0200296 * if the server supports this feature.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200297 * \param[in] seed Buffer containing the seed value to inject.
Gilles Peskine0cfaed12018-11-22 17:11:45 +0200298 * \param[in] seed_size Size of the \p seed buffer.
Netanel Gonen596e65e2018-11-22 18:41:43 +0200299 * The size of the seed in bytes must be greater
300 * or equal to both #MBEDTLS_ENTROPY_MIN_PLATFORM
301 * and #MBEDTLS_ENTROPY_BLOCK_SIZE.
302 * It must be less or equal to
303 * #MBEDTLS_ENTROPY_MAX_SEED_SIZE.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200304 *
305 * \retval #PSA_SUCCESS
Gilles Peskine0338ded2018-11-15 18:19:27 +0100306 * The seed value was injected successfully. The random generator
307 * of the PSA Crypto implementation is now ready for use.
308 * You may now call psa_crypto_init() and use the PSA Crypto
309 * implementation.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200310 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskineee2ffd32018-11-16 11:02:49 +0100311 * \p seed_size is out of range.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200312 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine0338ded2018-11-15 18:19:27 +0100313 * There was a failure reading or writing from storage.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200314 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine0338ded2018-11-15 18:19:27 +0100315 * The library has already been initialized. It is no longer
316 * possible to call this function.
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200317 */
Jaeden Ameroc7529c92019-08-19 11:08:04 +0100318psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed,
Netanel Gonen2bcd3122018-11-19 11:53:02 +0200319 size_t seed_size);
320
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200321/** \addtogroup crypto_types
322 * @{
323 */
324
Gilles Peskinea1302192019-05-16 13:58:24 +0200325/** DSA public key.
326 *
327 * The import and export format is the
328 * representation of the public key `y = g^x mod p` as a big-endian byte
329 * string. The length of the byte string is the length of the base prime `p`
330 * in bytes.
331 */
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200332#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x60020000)
Gilles Peskinea1302192019-05-16 13:58:24 +0200333
334/** DSA key pair (private and public key).
335 *
336 * The import and export format is the
337 * representation of the private key `x` as a big-endian byte string. The
338 * length of the byte string is the private key size in bytes (leading zeroes
339 * are not stripped).
340 *
341 * Determinstic DSA key derivation with psa_generate_derived_key follows
342 * FIPS 186-4 §B.1.2: interpret the byte string as integer
343 * in big-endian order. Discard it if it is not in the range
344 * [0, *N* - 2] where *N* is the boundary of the private key domain
345 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
346 * or the order of the curve's base point for ECC).
347 * Add 1 to the resulting integer and use this as the private key *x*.
348 *
349 */
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200350#define PSA_KEY_TYPE_DSA_KEY_PAIR ((psa_key_type_t)0x70020000)
Gilles Peskinea1302192019-05-16 13:58:24 +0200351
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200352/** Whether a key type is an DSA key (pair or public-only). */
353#define PSA_KEY_TYPE_IS_DSA(type) \
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200354 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY)
Gilles Peskinee38ab1a2019-05-16 13:51:50 +0200355
356#define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x10040000)
357/** DSA signature with hashing.
358 *
359 * This is the signature scheme defined by FIPS 186-4,
360 * with a random per-message secret number (*k*).
361 *
362 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
363 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
364 * This includes #PSA_ALG_ANY_HASH
365 * when specifying the algorithm in a usage policy.
366 *
367 * \return The corresponding DSA signature algorithm.
368 * \return Unspecified if \p hash_alg is not a supported
369 * hash algorithm.
370 */
371#define PSA_ALG_DSA(hash_alg) \
372 (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
373#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x10050000)
374#define PSA_ALG_DSA_DETERMINISTIC_FLAG ((psa_algorithm_t)0x00010000)
375/** Deterministic DSA signature with hashing.
376 *
377 * This is the deterministic variant defined by RFC 6979 of
378 * the signature scheme defined by FIPS 186-4.
379 *
380 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
381 * #PSA_ALG_IS_HASH(\p hash_alg) is true).
382 * This includes #PSA_ALG_ANY_HASH
383 * when specifying the algorithm in a usage policy.
384 *
385 * \return The corresponding DSA signature algorithm.
386 * \return Unspecified if \p hash_alg is not a supported
387 * hash algorithm.
388 */
389#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
390 (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
391#define PSA_ALG_IS_DSA(alg) \
392 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
393 PSA_ALG_DSA_BASE)
394#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
395 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
396#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
397 (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
398#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
399 (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
400
401
402/* We need to expand the sample definition of this macro from
403 * the API definition. */
404#undef PSA_ALG_IS_HASH_AND_SIGN
405#define PSA_ALG_IS_HASH_AND_SIGN(alg) \
406 (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
407 PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg))
408
409/**@}*/
410
Gilles Peskine24f10f82019-05-16 12:18:32 +0200411/** \addtogroup attributes
412 * @{
413 */
414
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200415/** Custom Diffie-Hellman group.
416 *
417 * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200418 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM), the group data comes
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200419 * from domain parameters set by psa_set_key_domain_parameters().
420 */
Gilles Peskine43326f02019-10-09 16:43:39 +0200421/* This value is a deprecated value meaning an explicit curve in the IANA
422 * registry. */
423#define PSA_DH_GROUP_CUSTOM ((psa_dh_group_t) 0xff01)
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200424
425
Gilles Peskine24f10f82019-05-16 12:18:32 +0200426/**
427 * \brief Set domain parameters for a key.
428 *
429 * Some key types require additional domain parameters in addition to
430 * the key type identifier and the key size. Use this function instead
431 * of psa_set_key_type() when you need to specify domain parameters.
432 *
433 * The format for the required domain parameters varies based on the key type.
434 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200435 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200436 * the domain parameter data consists of the public exponent,
437 * represented as a big-endian integer with no leading zeros.
438 * This information is used when generating an RSA key pair.
439 * When importing a key, the public exponent is read from the imported
440 * key data and the exponent recorded in the attribute structure is ignored.
441 * As an exception, the public exponent 65537 is represented by an empty
442 * byte string.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200443 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEY_PAIR),
Gilles Peskine24f10f82019-05-16 12:18:32 +0200444 * the `Dss-Parms` format as defined by RFC 3279 §2.3.2.
445 * ```
446 * Dss-Parms ::= SEQUENCE {
447 * p INTEGER,
448 * q INTEGER,
449 * g INTEGER
450 * }
451 * ```
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200452 * - For Diffie-Hellman key exchange keys
453 * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200454 * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM)), the
Gilles Peskine24f10f82019-05-16 12:18:32 +0200455 * `DomainParameters` format as defined by RFC 3279 §2.3.3.
456 * ```
457 * DomainParameters ::= SEQUENCE {
458 * p INTEGER, -- odd prime, p=jq +1
459 * g INTEGER, -- generator, g
460 * q INTEGER, -- factor of p-1
461 * j INTEGER OPTIONAL, -- subgroup factor
462 * validationParms ValidationParms OPTIONAL
463 * }
464 * ValidationParms ::= SEQUENCE {
465 * seed BIT STRING,
466 * pgenCounter INTEGER
467 * }
468 * ```
469 *
470 * \note This function may allocate memory or other resources.
471 * Once you have called this function on an attribute structure,
472 * you must call psa_reset_key_attributes() to free these resources.
473 *
474 * \note This is an experimental extension to the interface. It may change
475 * in future versions of the library.
476 *
477 * \param[in,out] attributes Attribute structure where the specified domain
478 * parameters will be stored.
479 * If this function fails, the content of
480 * \p attributes is not modified.
481 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
482 * \param[in] data Buffer containing the key domain parameters.
483 * The content of this buffer is interpreted
484 * according to \p type as described above.
485 * \param data_length Size of the \p data buffer in bytes.
486 *
487 * \retval #PSA_SUCCESS
488 * \retval #PSA_ERROR_INVALID_ARGUMENT
489 * \retval #PSA_ERROR_NOT_SUPPORTED
490 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
491 */
492psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
493 psa_key_type_t type,
494 const uint8_t *data,
495 size_t data_length);
496
497/**
498 * \brief Get domain parameters for a key.
499 *
500 * Get the domain parameters for a key with this function, if any. The format
501 * of the domain parameters written to \p data is specified in the
502 * documentation for psa_set_key_domain_parameters().
503 *
504 * \note This is an experimental extension to the interface. It may change
505 * in future versions of the library.
506 *
507 * \param[in] attributes The key attribute structure to query.
508 * \param[out] data On success, the key domain parameters.
509 * \param data_size Size of the \p data buffer in bytes.
510 * The buffer is guaranteed to be large
511 * enough if its size in bytes is at least
512 * the value given by
513 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
514 * \param[out] data_length On success, the number of bytes
515 * that make up the key domain parameters data.
516 *
517 * \retval #PSA_SUCCESS
518 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
519 */
520psa_status_t psa_get_key_domain_parameters(
521 const psa_key_attributes_t *attributes,
522 uint8_t *data,
523 size_t data_size,
524 size_t *data_length);
525
526/** Safe output buffer size for psa_get_key_domain_parameters().
527 *
528 * This macro returns a compile-time constant if its arguments are
529 * compile-time constants.
530 *
531 * \warning This function may call its arguments multiple times or
532 * zero times, so you should not pass arguments that contain
533 * side effects.
534 *
535 * \note This is an experimental extension to the interface. It may change
536 * in future versions of the library.
537 *
538 * \param key_type A supported key type.
539 * \param key_bits The size of the key in bits.
540 *
541 * \return If the parameters are valid and supported, return
542 * a buffer size in bytes that guarantees that
543 * psa_get_key_domain_parameters() will not fail with
544 * #PSA_ERROR_BUFFER_TOO_SMALL.
545 * If the parameters are a valid combination that is not supported
Gilles Peskine27a983d2019-05-16 17:24:53 +0200546 * by the implementation, this macro shall return either a
Gilles Peskine24f10f82019-05-16 12:18:32 +0200547 * sensible size or 0.
548 * If the parameters are not valid, the
549 * return value is unspecified.
550 */
551#define PSA_KEY_DOMAIN_PARAMETERS_SIZE(key_type, key_bits) \
552 (PSA_KEY_TYPE_IS_RSA(key_type) ? sizeof(int) : \
553 PSA_KEY_TYPE_IS_DH(key_type) ? PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
554 PSA_KEY_TYPE_IS_DSA(key_type) ? PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) : \
555 0)
556#define PSA_DH_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
557 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 3 /*without optional parts*/)
558#define PSA_DSA_KEY_DOMAIN_PARAMETERS_SIZE(key_bits) \
559 (4 + (PSA_BITS_TO_BYTES(key_bits) + 5) * 2 /*p, g*/ + 34 /*q*/)
560
561/**@}*/
562
Gilles Peskinee59236f2018-01-27 23:32:46 +0100563#ifdef __cplusplus
564}
565#endif
566
567#endif /* PSA_CRYPTO_EXTRA_H */