/src/mbedtls/include/psa/crypto_values.h
Line | Count | Source (jump to first uncovered line) |
1 | | /** |
2 | | * \file psa/crypto_values.h |
3 | | * |
4 | | * \brief PSA cryptography module: macros to build and analyze integer values. |
5 | | * |
6 | | * \note This file may not be included directly. Applications must |
7 | | * include psa/crypto.h. Drivers must include the appropriate driver |
8 | | * header file. |
9 | | * |
10 | | * This file contains portable definitions of macros to build and analyze |
11 | | * values of integral types that encode properties of cryptographic keys, |
12 | | * designations of cryptographic algorithms, and error codes returned by |
13 | | * the library. |
14 | | * |
15 | | * Note that many of the constants defined in this file are embedded in |
16 | | * the persistent key store, as part of key metadata (including usage |
17 | | * policies). As a consequence, they must not be changed (unless the storage |
18 | | * format version changes). |
19 | | * |
20 | | * This header file only defines preprocessor macros. |
21 | | */ |
22 | | /* |
23 | | * Copyright The Mbed TLS Contributors |
24 | | * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later |
25 | | */ |
26 | | |
27 | | #ifndef PSA_CRYPTO_VALUES_H |
28 | | #define PSA_CRYPTO_VALUES_H |
29 | | #include "mbedtls/private_access.h" |
30 | | |
31 | | /** \defgroup error Error codes |
32 | | * @{ |
33 | | */ |
34 | | |
35 | | /* PSA error codes */ |
36 | | |
37 | | /* Error codes are standardized across PSA domains (framework, crypto, storage, |
38 | | * etc.). Do not change the values in this section or even the expansions |
39 | | * of each macro: it must be possible to `#include` both this header |
40 | | * and some other PSA component's headers in the same C source, |
41 | | * which will lead to duplicate definitions of the `PSA_SUCCESS` and |
42 | | * `PSA_ERROR_xxx` macros, which is ok if and only if the macros expand |
43 | | * to the same sequence of tokens. |
44 | | * |
45 | | * If you must add a new |
46 | | * value, check with the Arm PSA framework group to pick one that other |
47 | | * domains aren't already using. */ |
48 | | |
49 | | /* Tell uncrustify not to touch the constant definitions, otherwise |
50 | | * it might change the spacing to something that is not PSA-compliant |
51 | | * (e.g. adding a space after casts). |
52 | | * |
53 | | * *INDENT-OFF* |
54 | | */ |
55 | | |
56 | | /** The action was completed successfully. */ |
57 | 0 | #define PSA_SUCCESS ((psa_status_t)0) |
58 | | |
59 | | /** An error occurred that does not correspond to any defined |
60 | | * failure cause. |
61 | | * |
62 | | * Implementations may use this error code if none of the other standard |
63 | | * error codes are applicable. */ |
64 | 0 | #define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132) |
65 | | |
66 | | /** The requested operation or a parameter is not supported |
67 | | * by this implementation. |
68 | | * |
69 | | * Implementations should return this error code when an enumeration |
70 | | * parameter such as a key type, algorithm, etc. is not recognized. |
71 | | * If a combination of parameters is recognized and identified as |
72 | | * not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */ |
73 | 0 | #define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134) |
74 | | |
75 | | /** The requested action is denied by a policy. |
76 | | * |
77 | | * Implementations should return this error code when the parameters |
78 | | * are recognized as valid and supported, and a policy explicitly |
79 | | * denies the requested operation. |
80 | | * |
81 | | * If a subset of the parameters of a function call identify a |
82 | | * forbidden operation, and another subset of the parameters are |
83 | | * not valid or not supported, it is unspecified whether the function |
84 | | * returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or |
85 | | * #PSA_ERROR_INVALID_ARGUMENT. */ |
86 | 0 | #define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133) |
87 | | |
88 | | /** An output buffer is too small. |
89 | | * |
90 | | * Applications can call the \c PSA_xxx_SIZE macro listed in the function |
91 | | * description to determine a sufficient buffer size. |
92 | | * |
93 | | * Implementations should preferably return this error code only |
94 | | * in cases when performing the operation with a larger output |
95 | | * buffer would succeed. However implementations may return this |
96 | | * error if a function has invalid or unsupported parameters in addition |
97 | | * to the parameters that determine the necessary output buffer size. */ |
98 | 0 | #define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138) |
99 | | |
100 | | /** Asking for an item that already exists |
101 | | * |
102 | | * Implementations should return this error, when attempting |
103 | | * to write an item (like a key) that already exists. */ |
104 | 0 | #define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139) |
105 | | |
106 | | /** Asking for an item that doesn't exist |
107 | | * |
108 | | * Implementations should return this error, if a requested item (like |
109 | | * a key) does not exist. */ |
110 | 0 | #define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140) |
111 | | |
112 | | /** The requested action cannot be performed in the current state. |
113 | | * |
114 | | * Multipart operations return this error when one of the |
115 | | * functions is called out of sequence. Refer to the function |
116 | | * descriptions for permitted sequencing of functions. |
117 | | * |
118 | | * Implementations shall not return this error code to indicate |
119 | | * that a key either exists or not, |
120 | | * but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST |
121 | | * as applicable. |
122 | | * |
123 | | * Implementations shall not return this error code to indicate that a |
124 | | * key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE |
125 | | * instead. */ |
126 | 0 | #define PSA_ERROR_BAD_STATE ((psa_status_t)-137) |
127 | | |
128 | | /** The parameters passed to the function are invalid. |
129 | | * |
130 | | * Implementations may return this error any time a parameter or |
131 | | * combination of parameters are recognized as invalid. |
132 | | * |
133 | | * Implementations shall not return this error code to indicate that a |
134 | | * key identifier is invalid, but shall return #PSA_ERROR_INVALID_HANDLE |
135 | | * instead. |
136 | | */ |
137 | 0 | #define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135) |
138 | | |
139 | | /** There is not enough runtime memory. |
140 | | * |
141 | | * If the action is carried out across multiple security realms, this |
142 | | * error can refer to available memory in any of the security realms. */ |
143 | 0 | #define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141) |
144 | | |
145 | | /** There is not enough persistent storage. |
146 | | * |
147 | | * Functions that modify the key storage return this error code if |
148 | | * there is insufficient storage space on the host media. In addition, |
149 | | * many functions that do not otherwise access storage may return this |
150 | | * error code if the implementation requires a mandatory log entry for |
151 | | * the requested action and the log storage space is full. */ |
152 | 0 | #define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142) |
153 | | |
154 | | /** There was a communication failure inside the implementation. |
155 | | * |
156 | | * This can indicate a communication failure between the application |
157 | | * and an external cryptoprocessor or between the cryptoprocessor and |
158 | | * an external volatile or persistent memory. A communication failure |
159 | | * may be transient or permanent depending on the cause. |
160 | | * |
161 | | * \warning If a function returns this error, it is undetermined |
162 | | * whether the requested action has completed or not. Implementations |
163 | | * should return #PSA_SUCCESS on successful completion whenever |
164 | | * possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE |
165 | | * if the requested action was completed successfully in an external |
166 | | * cryptoprocessor but there was a breakdown of communication before |
167 | | * the cryptoprocessor could report the status to the application. |
168 | | */ |
169 | 0 | #define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145) |
170 | | |
171 | | /** There was a storage failure that may have led to data loss. |
172 | | * |
173 | | * This error indicates that some persistent storage is corrupted. |
174 | | * It should not be used for a corruption of volatile memory |
175 | | * (use #PSA_ERROR_CORRUPTION_DETECTED), for a communication error |
176 | | * between the cryptoprocessor and its external storage (use |
177 | | * #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is |
178 | | * in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE). |
179 | | * |
180 | | * Note that a storage failure does not indicate that any data that was |
181 | | * previously read is invalid. However this previously read data may no |
182 | | * longer be readable from storage. |
183 | | * |
184 | | * When a storage failure occurs, it is no longer possible to ensure |
185 | | * the global integrity of the keystore. Depending on the global |
186 | | * integrity guarantees offered by the implementation, access to other |
187 | | * data may or may not fail even if the data is still readable but |
188 | | * its integrity cannot be guaranteed. |
189 | | * |
190 | | * Implementations should only use this error code to report a |
191 | | * permanent storage corruption. However application writers should |
192 | | * keep in mind that transient errors while reading the storage may be |
193 | | * reported using this error code. */ |
194 | 0 | #define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146) |
195 | | |
196 | | /** A hardware failure was detected. |
197 | | * |
198 | | * A hardware failure may be transient or permanent depending on the |
199 | | * cause. */ |
200 | 0 | #define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147) |
201 | | |
202 | | /** A tampering attempt was detected. |
203 | | * |
204 | | * If an application receives this error code, there is no guarantee |
205 | | * that previously accessed or computed data was correct and remains |
206 | | * confidential. Applications should not perform any security function |
207 | | * and should enter a safe failure state. |
208 | | * |
209 | | * Implementations may return this error code if they detect an invalid |
210 | | * state that cannot happen during normal operation and that indicates |
211 | | * that the implementation's security guarantees no longer hold. Depending |
212 | | * on the implementation architecture and on its security and safety goals, |
213 | | * the implementation may forcibly terminate the application. |
214 | | * |
215 | | * This error code is intended as a last resort when a security breach |
216 | | * is detected and it is unsure whether the keystore data is still |
217 | | * protected. Implementations shall only return this error code |
218 | | * to report an alarm from a tampering detector, to indicate that |
219 | | * the confidentiality of stored data can no longer be guaranteed, |
220 | | * or to indicate that the integrity of previously returned data is now |
221 | | * considered compromised. Implementations shall not use this error code |
222 | | * to indicate a hardware failure that merely makes it impossible to |
223 | | * perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE, |
224 | | * #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE, |
225 | | * #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code |
226 | | * instead). |
227 | | * |
228 | | * This error indicates an attack against the application. Implementations |
229 | | * shall not return this error code as a consequence of the behavior of |
230 | | * the application itself. */ |
231 | 0 | #define PSA_ERROR_CORRUPTION_DETECTED ((psa_status_t)-151) |
232 | | |
233 | | /** There is not enough entropy to generate random data needed |
234 | | * for the requested action. |
235 | | * |
236 | | * This error indicates a failure of a hardware random generator. |
237 | | * Application writers should note that this error can be returned not |
238 | | * only by functions whose purpose is to generate random data, such |
239 | | * as key, IV or nonce generation, but also by functions that execute |
240 | | * an algorithm with a randomized result, as well as functions that |
241 | | * use randomization of intermediate computations as a countermeasure |
242 | | * to certain attacks. |
243 | | * |
244 | | * Implementations should avoid returning this error after psa_crypto_init() |
245 | | * has succeeded. Implementations should generate sufficient |
246 | | * entropy during initialization and subsequently use a cryptographically |
247 | | * secure pseudorandom generator (PRNG). However implementations may return |
248 | | * this error at any time if a policy requires the PRNG to be reseeded |
249 | | * during normal operation. */ |
250 | 0 | #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148) |
251 | | |
252 | | /** The signature, MAC or hash is incorrect. |
253 | | * |
254 | | * Verification functions return this error if the verification |
255 | | * calculations completed successfully, and the value to be verified |
256 | | * was determined to be incorrect. |
257 | | * |
258 | | * If the value to verify has an invalid size, implementations may return |
259 | | * either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */ |
260 | 0 | #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149) |
261 | | |
262 | | /** The decrypted padding is incorrect. |
263 | | * |
264 | | * \warning In some protocols, when decrypting data, it is essential that |
265 | | * the behavior of the application does not depend on whether the padding |
266 | | * is correct, down to precise timing. Applications should prefer |
267 | | * protocols that use authenticated encryption rather than plain |
268 | | * encryption. If the application must perform a decryption of |
269 | | * unauthenticated data, the application writer should take care not |
270 | | * to reveal whether the padding is invalid. |
271 | | * |
272 | | * Implementations should strive to make valid and invalid padding |
273 | | * as close as possible to indistinguishable to an external observer. |
274 | | * In particular, the timing of a decryption operation should not |
275 | | * depend on the validity of the padding. */ |
276 | 0 | #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150) |
277 | | |
278 | | /** Return this error when there's insufficient data when attempting |
279 | | * to read from a resource. */ |
280 | 0 | #define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143) |
281 | | |
282 | | /** This can be returned if a function can no longer operate correctly. |
283 | | * For example, if an essential initialization operation failed or |
284 | | * a mutex operation failed. */ |
285 | 0 | #define PSA_ERROR_SERVICE_FAILURE ((psa_status_t)-144) |
286 | | |
287 | | /** The key identifier is not valid. See also :ref:\`key-handles\`. |
288 | | */ |
289 | 0 | #define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136) |
290 | | |
291 | | /** Stored data has been corrupted. |
292 | | * |
293 | | * This error indicates that some persistent storage has suffered corruption. |
294 | | * It does not indicate the following situations, which have specific error |
295 | | * codes: |
296 | | * |
297 | | * - A corruption of volatile memory - use #PSA_ERROR_CORRUPTION_DETECTED. |
298 | | * - A communication error between the cryptoprocessor and its external |
299 | | * storage - use #PSA_ERROR_COMMUNICATION_FAILURE. |
300 | | * - When the storage is in a valid state but is full - use |
301 | | * #PSA_ERROR_INSUFFICIENT_STORAGE. |
302 | | * - When the storage fails for other reasons - use |
303 | | * #PSA_ERROR_STORAGE_FAILURE. |
304 | | * - When the stored data is not valid - use #PSA_ERROR_DATA_INVALID. |
305 | | * |
306 | | * \note A storage corruption does not indicate that any data that was |
307 | | * previously read is invalid. However this previously read data might no |
308 | | * longer be readable from storage. |
309 | | * |
310 | | * When a storage failure occurs, it is no longer possible to ensure the |
311 | | * global integrity of the keystore. |
312 | | */ |
313 | 0 | #define PSA_ERROR_DATA_CORRUPT ((psa_status_t)-152) |
314 | | |
315 | | /** Data read from storage is not valid for the implementation. |
316 | | * |
317 | | * This error indicates that some data read from storage does not have a valid |
318 | | * format. It does not indicate the following situations, which have specific |
319 | | * error codes: |
320 | | * |
321 | | * - When the storage or stored data is corrupted - use #PSA_ERROR_DATA_CORRUPT |
322 | | * - When the storage fails for other reasons - use #PSA_ERROR_STORAGE_FAILURE |
323 | | * - An invalid argument to the API - use #PSA_ERROR_INVALID_ARGUMENT |
324 | | * |
325 | | * This error is typically a result of either storage corruption on a |
326 | | * cleartext storage backend, or an attempt to read data that was |
327 | | * written by an incompatible version of the library. |
328 | | */ |
329 | 0 | #define PSA_ERROR_DATA_INVALID ((psa_status_t)-153) |
330 | | |
331 | | /** The function that returns this status is defined as interruptible and |
332 | | * still has work to do, thus the user should call the function again with the |
333 | | * same operation context until it either returns #PSA_SUCCESS or any other |
334 | | * error. This is not an error per se, more a notification of status. |
335 | | */ |
336 | 0 | #define PSA_OPERATION_INCOMPLETE ((psa_status_t)-248) |
337 | | |
338 | | /* *INDENT-ON* */ |
339 | | |
340 | | /**@}*/ |
341 | | |
342 | | /** \defgroup crypto_types Key and algorithm types |
343 | | * @{ |
344 | | */ |
345 | | |
346 | | /* Note that key type values, including ECC family and DH group values, are |
347 | | * embedded in the persistent key store, as part of key metadata. As a |
348 | | * consequence, they must not be changed (unless the storage format version |
349 | | * changes). |
350 | | */ |
351 | | |
352 | | /** An invalid key type value. |
353 | | * |
354 | | * Zero is not the encoding of any key type. |
355 | | */ |
356 | 0 | #define PSA_KEY_TYPE_NONE ((psa_key_type_t) 0x0000) |
357 | | |
358 | | /** Vendor-defined key type flag. |
359 | | * |
360 | | * Key types defined by this standard will never have the |
361 | | * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types |
362 | | * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should |
363 | | * respect the bitwise structure used by standard encodings whenever practical. |
364 | | */ |
365 | | #define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t) 0x8000) |
366 | | |
367 | 0 | #define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t) 0x7000) |
368 | 0 | #define PSA_KEY_TYPE_CATEGORY_RAW ((psa_key_type_t) 0x1000) |
369 | 0 | #define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t) 0x2000) |
370 | 0 | #define PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY ((psa_key_type_t) 0x4000) |
371 | 0 | #define PSA_KEY_TYPE_CATEGORY_KEY_PAIR ((psa_key_type_t) 0x7000) |
372 | | |
373 | 0 | #define PSA_KEY_TYPE_CATEGORY_FLAG_PAIR ((psa_key_type_t) 0x3000) |
374 | | |
375 | | /** Whether a key type is vendor-defined. |
376 | | * |
377 | | * See also #PSA_KEY_TYPE_VENDOR_FLAG. |
378 | | */ |
379 | | #define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \ |
380 | | (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0) |
381 | | |
382 | | /** Whether a key type is an unstructured array of bytes. |
383 | | * |
384 | | * This encompasses both symmetric keys and non-key data. |
385 | | */ |
386 | | #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ |
387 | 0 | (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_RAW || \ |
388 | 0 | ((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC) |
389 | | |
390 | | /** Whether a key type is asymmetric: either a key pair or a public key. */ |
391 | | #define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \ |
392 | 0 | (((type) & PSA_KEY_TYPE_CATEGORY_MASK \ |
393 | 0 | & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) == \ |
394 | 0 | PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) |
395 | | /** Whether a key type is the public part of a key pair. */ |
396 | | #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ |
397 | 0 | (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) |
398 | | /** Whether a key type is a key pair containing a private part and a public |
399 | | * part. */ |
400 | | #define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ |
401 | 0 | (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_KEY_PAIR) |
402 | | /** The key pair type corresponding to a public key type. |
403 | | * |
404 | | * You may also pass a key pair type as \p type, it will be left unchanged. |
405 | | * |
406 | | * \param type A public key type or key pair type. |
407 | | * |
408 | | * \return The corresponding key pair type. |
409 | | * If \p type is not a public key or a key pair, |
410 | | * the return value is undefined. |
411 | | */ |
412 | | #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ |
413 | | ((type) | PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) |
414 | | /** The public key type corresponding to a key pair type. |
415 | | * |
416 | | * You may also pass a public key type as \p type, it will be left unchanged. |
417 | | * |
418 | | * \param type A public key type or key pair type. |
419 | | * |
420 | | * \return The corresponding public key type. |
421 | | * If \p type is not a public key or a key pair, |
422 | | * the return value is undefined. |
423 | | */ |
424 | | #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ |
425 | 0 | ((type) & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) |
426 | | |
427 | | /** Raw data. |
428 | | * |
429 | | * A "key" of this type cannot be used for any cryptographic operation. |
430 | | * Applications may use this type to store arbitrary data in the keystore. */ |
431 | 0 | #define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t) 0x1001) |
432 | | |
433 | | /** HMAC key. |
434 | | * |
435 | | * The key policy determines which underlying hash algorithm the key can be |
436 | | * used for. |
437 | | * |
438 | | * HMAC keys should generally have the same size as the underlying hash. |
439 | | * This size can be calculated with #PSA_HASH_LENGTH(\c alg) where |
440 | | * \c alg is the HMAC algorithm or the underlying hash algorithm. */ |
441 | 0 | #define PSA_KEY_TYPE_HMAC ((psa_key_type_t) 0x1100) |
442 | | |
443 | | /** A secret for key derivation. |
444 | | * |
445 | | * This key type is for high-entropy secrets only. For low-entropy secrets, |
446 | | * #PSA_KEY_TYPE_PASSWORD should be used instead. |
447 | | * |
448 | | * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_SECRET or |
449 | | * #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms. |
450 | | * |
451 | | * The key policy determines which key derivation algorithm the key |
452 | | * can be used for. |
453 | | */ |
454 | 0 | #define PSA_KEY_TYPE_DERIVE ((psa_key_type_t) 0x1200) |
455 | | |
456 | | /** A low-entropy secret for password hashing or key derivation. |
457 | | * |
458 | | * This key type is suitable for passwords and passphrases which are typically |
459 | | * intended to be memorizable by humans, and have a low entropy relative to |
460 | | * their size. It can be used for randomly generated or derived keys with |
461 | | * maximum or near-maximum entropy, but #PSA_KEY_TYPE_DERIVE is more suitable |
462 | | * for such keys. It is not suitable for passwords with extremely low entropy, |
463 | | * such as numerical PINs. |
464 | | * |
465 | | * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_PASSWORD input of |
466 | | * key derivation algorithms. Algorithms that accept such an input were |
467 | | * designed to accept low-entropy secret and are known as password hashing or |
468 | | * key stretching algorithms. |
469 | | * |
470 | | * These keys cannot be used as the #PSA_KEY_DERIVATION_INPUT_SECRET input of |
471 | | * key derivation algorithms, as the algorithms that take such an input expect |
472 | | * it to be high-entropy. |
473 | | * |
474 | | * The key policy determines which key derivation algorithm the key can be |
475 | | * used for, among the permissible subset defined above. |
476 | | */ |
477 | 0 | #define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t) 0x1203) |
478 | | |
479 | | /** A secret value that can be used to verify a password hash. |
480 | | * |
481 | | * The key policy determines which key derivation algorithm the key |
482 | | * can be used for, among the same permissible subset as for |
483 | | * #PSA_KEY_TYPE_PASSWORD. |
484 | | */ |
485 | 0 | #define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t) 0x1205) |
486 | | |
487 | | /** A secret value that can be used in when computing a password hash. |
488 | | * |
489 | | * The key policy determines which key derivation algorithm the key |
490 | | * can be used for, among the subset of algorithms that can use pepper. |
491 | | */ |
492 | | #define PSA_KEY_TYPE_PEPPER ((psa_key_type_t) 0x1206) |
493 | | |
494 | | /** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. |
495 | | * |
496 | | * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or |
497 | | * 32 bytes (AES-256). |
498 | | */ |
499 | 0 | #define PSA_KEY_TYPE_AES ((psa_key_type_t) 0x2400) |
500 | | |
501 | | /** Key for a cipher, AEAD or MAC algorithm based on the |
502 | | * ARIA block cipher. */ |
503 | 0 | #define PSA_KEY_TYPE_ARIA ((psa_key_type_t) 0x2406) |
504 | | |
505 | | /** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). |
506 | | * |
507 | | * The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or |
508 | | * 192 bits (3-key 3DES). |
509 | | * |
510 | | * Note that single DES and 2-key 3DES are weak and strongly |
511 | | * deprecated and should only be used to decrypt legacy data. 3-key 3DES |
512 | | * is weak and deprecated and should only be used in legacy protocols. |
513 | | */ |
514 | 0 | #define PSA_KEY_TYPE_DES ((psa_key_type_t) 0x2301) |
515 | | |
516 | | /** Key for a cipher, AEAD or MAC algorithm based on the |
517 | | * Camellia block cipher. */ |
518 | 0 | #define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t) 0x2403) |
519 | | |
520 | | /** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm. |
521 | | * |
522 | | * ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539. |
523 | | * |
524 | | * \note For ChaCha20 and ChaCha20_Poly1305, Mbed TLS only supports |
525 | | * 12-byte nonces. |
526 | | * |
527 | | * \note For ChaCha20, the initial counter value is 0. To encrypt or decrypt |
528 | | * with the initial counter value 1, you can process and discard a |
529 | | * 64-byte block before the real data. |
530 | | */ |
531 | 0 | #define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t) 0x2004) |
532 | | |
533 | | /** RSA public key. |
534 | | * |
535 | | * The size of an RSA key is the bit size of the modulus. |
536 | | */ |
537 | 0 | #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t) 0x4001) |
538 | | /** RSA key pair (private and public key). |
539 | | * |
540 | | * The size of an RSA key is the bit size of the modulus. |
541 | | */ |
542 | 0 | #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t) 0x7001) |
543 | | /** Whether a key type is an RSA key (pair or public-only). */ |
544 | | #define PSA_KEY_TYPE_IS_RSA(type) \ |
545 | 0 | (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY) |
546 | | |
547 | 0 | #define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t) 0x4100) |
548 | 0 | #define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t) 0x7100) |
549 | 0 | #define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t) 0x00ff) |
550 | | /** Elliptic curve key pair. |
551 | | * |
552 | | * The size of an elliptic curve key is the bit size associated with the curve, |
553 | | * i.e. the bit size of *q* for a curve over a field *F<sub>q</sub>*. |
554 | | * See the documentation of `PSA_ECC_FAMILY_xxx` curve families for details. |
555 | | * |
556 | | * \param curve A value of type ::psa_ecc_family_t that |
557 | | * identifies the ECC curve to be used. |
558 | | */ |
559 | | #define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ |
560 | 0 | (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) |
561 | | /** Elliptic curve public key. |
562 | | * |
563 | | * The size of an elliptic curve public key is the same as the corresponding |
564 | | * private key (see #PSA_KEY_TYPE_ECC_KEY_PAIR and the documentation of |
565 | | * `PSA_ECC_FAMILY_xxx` curve families). |
566 | | * |
567 | | * \param curve A value of type ::psa_ecc_family_t that |
568 | | * identifies the ECC curve to be used. |
569 | | */ |
570 | | #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ |
571 | 0 | (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) |
572 | | |
573 | | /** Whether a key type is an elliptic curve key (pair or public-only). */ |
574 | | #define PSA_KEY_TYPE_IS_ECC(type) \ |
575 | 0 | ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ |
576 | 0 | ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) |
577 | | /** Whether a key type is an elliptic curve key pair. */ |
578 | | #define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \ |
579 | 0 | (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ |
580 | 0 | PSA_KEY_TYPE_ECC_KEY_PAIR_BASE) |
581 | | /** Whether a key type is an elliptic curve public key. */ |
582 | | #define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \ |
583 | 0 | (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ |
584 | 0 | PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) |
585 | | |
586 | | /** Extract the curve from an elliptic curve key type. */ |
587 | | #define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \ |
588 | 0 | ((psa_ecc_family_t) (PSA_KEY_TYPE_IS_ECC(type) ? \ |
589 | 0 | ((type) & PSA_KEY_TYPE_ECC_CURVE_MASK) : \ |
590 | 0 | 0)) |
591 | | |
592 | | /** Check if the curve of given family is Weierstrass elliptic curve. */ |
593 | 0 | #define PSA_ECC_FAMILY_IS_WEIERSTRASS(family) ((family & 0xc0) == 0) |
594 | | |
595 | | /** SEC Koblitz curves over prime fields. |
596 | | * |
597 | | * This family comprises the following curves: |
598 | | * secp192k1, secp224k1, secp256k1. |
599 | | * They are defined in _Standards for Efficient Cryptography_, |
600 | | * _SEC 2: Recommended Elliptic Curve Domain Parameters_. |
601 | | * https://www.secg.org/sec2-v2.pdf |
602 | | * |
603 | | * \note For secp224k1, the bit-size is 225 (size of a private value). |
604 | | * |
605 | | * \note Mbed TLS only supports secp192k1 and secp256k1. |
606 | | */ |
607 | 0 | #define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t) 0x17) |
608 | | |
609 | | /** SEC random curves over prime fields. |
610 | | * |
611 | | * This family comprises the following curves: |
612 | | * secp192r1, secp224r1, secp256r1, secp384r1, secp521r1. |
613 | | * They are defined in _Standards for Efficient Cryptography_, |
614 | | * _SEC 2: Recommended Elliptic Curve Domain Parameters_. |
615 | | * https://www.secg.org/sec2-v2.pdf |
616 | | */ |
617 | 0 | #define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t) 0x12) |
618 | | /* SECP160R2 (SEC2 v1, obsolete, not supported in Mbed TLS) */ |
619 | | #define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t) 0x1b) |
620 | | |
621 | | /** SEC Koblitz curves over binary fields. |
622 | | * |
623 | | * This family comprises the following curves: |
624 | | * sect163k1, sect233k1, sect239k1, sect283k1, sect409k1, sect571k1. |
625 | | * They are defined in _Standards for Efficient Cryptography_, |
626 | | * _SEC 2: Recommended Elliptic Curve Domain Parameters_. |
627 | | * https://www.secg.org/sec2-v2.pdf |
628 | | * |
629 | | * \note Mbed TLS does not support any curve in this family. |
630 | | */ |
631 | | #define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t) 0x27) |
632 | | |
633 | | /** SEC random curves over binary fields. |
634 | | * |
635 | | * This family comprises the following curves: |
636 | | * sect163r1, sect233r1, sect283r1, sect409r1, sect571r1. |
637 | | * They are defined in _Standards for Efficient Cryptography_, |
638 | | * _SEC 2: Recommended Elliptic Curve Domain Parameters_. |
639 | | * https://www.secg.org/sec2-v2.pdf |
640 | | * |
641 | | * \note Mbed TLS does not support any curve in this family. |
642 | | */ |
643 | | #define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22) |
644 | | |
645 | | /** SEC additional random curves over binary fields. |
646 | | * |
647 | | * This family comprises the following curve: |
648 | | * sect163r2. |
649 | | * It is defined in _Standards for Efficient Cryptography_, |
650 | | * _SEC 2: Recommended Elliptic Curve Domain Parameters_. |
651 | | * https://www.secg.org/sec2-v2.pdf |
652 | | * |
653 | | * \note Mbed TLS does not support any curve in this family. |
654 | | */ |
655 | | #define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b) |
656 | | |
657 | | /** Brainpool P random curves. |
658 | | * |
659 | | * This family comprises the following curves: |
660 | | * brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, |
661 | | * brainpoolP320r1, brainpoolP384r1, brainpoolP512r1. |
662 | | * It is defined in RFC 5639. |
663 | | * |
664 | | * \note Mbed TLS only supports the 256-bit, 384-bit and 512-bit curves |
665 | | * in this family. |
666 | | */ |
667 | 0 | #define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30) |
668 | | |
669 | | /** Curve25519 and Curve448. |
670 | | * |
671 | | * This family comprises the following Montgomery curves: |
672 | | * - 255-bit: Bernstein et al., |
673 | | * _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006. |
674 | | * The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve. |
675 | | * - 448-bit: Hamburg, |
676 | | * _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. |
677 | | * The algorithm #PSA_ALG_ECDH performs X448 when used with this curve. |
678 | | */ |
679 | 0 | #define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41) |
680 | | |
681 | | /** The twisted Edwards curves Ed25519 and Ed448. |
682 | | * |
683 | | * These curves are suitable for EdDSA (#PSA_ALG_PURE_EDDSA for both curves, |
684 | | * #PSA_ALG_ED25519PH for the 255-bit curve, |
685 | | * #PSA_ALG_ED448PH for the 448-bit curve). |
686 | | * |
687 | | * This family comprises the following twisted Edwards curves: |
688 | | * - 255-bit: Edwards25519, the twisted Edwards curve birationally equivalent |
689 | | * to Curve25519. |
690 | | * Bernstein et al., _Twisted Edwards curves_, Africacrypt 2008. |
691 | | * - 448-bit: Edwards448, the twisted Edwards curve birationally equivalent |
692 | | * to Curve448. |
693 | | * Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. |
694 | | * |
695 | | * \note Mbed TLS does not support Edwards curves yet. |
696 | | */ |
697 | 0 | #define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42) |
698 | | |
699 | 0 | #define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t) 0x4200) |
700 | 0 | #define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t) 0x7200) |
701 | 0 | #define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t) 0x00ff) |
702 | | /** Diffie-Hellman key pair. |
703 | | * |
704 | | * \param group A value of type ::psa_dh_family_t that identifies the |
705 | | * Diffie-Hellman group to be used. |
706 | | */ |
707 | | #define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ |
708 | | (PSA_KEY_TYPE_DH_KEY_PAIR_BASE | (group)) |
709 | | /** Diffie-Hellman public key. |
710 | | * |
711 | | * \param group A value of type ::psa_dh_family_t that identifies the |
712 | | * Diffie-Hellman group to be used. |
713 | | */ |
714 | | #define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ |
715 | | (PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE | (group)) |
716 | | |
717 | | /** Whether a key type is a Diffie-Hellman key (pair or public-only). */ |
718 | | #define PSA_KEY_TYPE_IS_DH(type) \ |
719 | 0 | ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ |
720 | 0 | ~PSA_KEY_TYPE_DH_GROUP_MASK) == PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) |
721 | | /** Whether a key type is a Diffie-Hellman key pair. */ |
722 | | #define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \ |
723 | 0 | (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ |
724 | 0 | PSA_KEY_TYPE_DH_KEY_PAIR_BASE) |
725 | | /** Whether a key type is a Diffie-Hellman public key. */ |
726 | | #define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \ |
727 | 0 | (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ |
728 | 0 | PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) |
729 | | |
730 | | /** Extract the group from a Diffie-Hellman key type. */ |
731 | | #define PSA_KEY_TYPE_DH_GET_FAMILY(type) \ |
732 | | ((psa_dh_family_t) (PSA_KEY_TYPE_IS_DH(type) ? \ |
733 | | ((type) & PSA_KEY_TYPE_DH_GROUP_MASK) : \ |
734 | | 0)) |
735 | | |
736 | | /** Diffie-Hellman groups defined in RFC 7919 Appendix A. |
737 | | * |
738 | | * This family includes groups with the following key sizes (in bits): |
739 | | * 2048, 3072, 4096, 6144, 8192. A given implementation may support |
740 | | * all of these sizes or only a subset. |
741 | | */ |
742 | | #define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03) |
743 | | |
744 | | #define PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) \ |
745 | 0 | (((type) >> 8) & 7) |
746 | | /** The block size of a block cipher. |
747 | | * |
748 | | * \param type A cipher key type (value of type #psa_key_type_t). |
749 | | * |
750 | | * \return The block size for a block cipher, or 1 for a stream cipher. |
751 | | * The return value is undefined if \p type is not a supported |
752 | | * cipher key type. |
753 | | * |
754 | | * \note It is possible to build stream cipher algorithms on top of a block |
755 | | * cipher, for example CTR mode (#PSA_ALG_CTR). |
756 | | * This macro only takes the key type into account, so it cannot be |
757 | | * used to determine the size of the data that #psa_cipher_update() |
758 | | * might buffer for future processing in general. |
759 | | * |
760 | | * \note This macro returns a compile-time constant if its argument is one. |
761 | | * |
762 | | * \warning This macro may evaluate its argument multiple times. |
763 | | */ |
764 | | #define PSA_BLOCK_CIPHER_BLOCK_LENGTH(type) \ |
765 | 0 | (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC ? \ |
766 | 0 | 1u << PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) : \ |
767 | 0 | 0u) |
768 | | |
769 | | /* Note that algorithm values are embedded in the persistent key store, |
770 | | * as part of key metadata. As a consequence, they must not be changed |
771 | | * (unless the storage format version changes). |
772 | | */ |
773 | | |
774 | | /** Vendor-defined algorithm flag. |
775 | | * |
776 | | * Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG |
777 | | * bit set. Vendors who define additional algorithms must use an encoding with |
778 | | * the #PSA_ALG_VENDOR_FLAG bit set and should respect the bitwise structure |
779 | | * used by standard encodings whenever practical. |
780 | | */ |
781 | | #define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t) 0x80000000) |
782 | | |
783 | 0 | #define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t) 0x7f000000) |
784 | 0 | #define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t) 0x02000000) |
785 | 0 | #define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t) 0x03000000) |
786 | 0 | #define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t) 0x04000000) |
787 | 0 | #define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t) 0x05000000) |
788 | 0 | #define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t) 0x06000000) |
789 | 0 | #define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t) 0x07000000) |
790 | 0 | #define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t) 0x08000000) |
791 | 0 | #define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t) 0x09000000) |
792 | | |
793 | | /** Whether an algorithm is vendor-defined. |
794 | | * |
795 | | * See also #PSA_ALG_VENDOR_FLAG. |
796 | | */ |
797 | | #define PSA_ALG_IS_VENDOR_DEFINED(alg) \ |
798 | | (((alg) & PSA_ALG_VENDOR_FLAG) != 0) |
799 | | |
800 | | /** Whether the specified algorithm is a hash algorithm. |
801 | | * |
802 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
803 | | * |
804 | | * \return 1 if \p alg is a hash algorithm, 0 otherwise. |
805 | | * This macro may return either 0 or 1 if \p alg is not a supported |
806 | | * algorithm identifier. |
807 | | */ |
808 | | #define PSA_ALG_IS_HASH(alg) \ |
809 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH) |
810 | | |
811 | | /** Whether the specified algorithm is a MAC algorithm. |
812 | | * |
813 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
814 | | * |
815 | | * \return 1 if \p alg is a MAC algorithm, 0 otherwise. |
816 | | * This macro may return either 0 or 1 if \p alg is not a supported |
817 | | * algorithm identifier. |
818 | | */ |
819 | | #define PSA_ALG_IS_MAC(alg) \ |
820 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC) |
821 | | |
822 | | /** Whether the specified algorithm is a symmetric cipher algorithm. |
823 | | * |
824 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
825 | | * |
826 | | * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise. |
827 | | * This macro may return either 0 or 1 if \p alg is not a supported |
828 | | * algorithm identifier. |
829 | | */ |
830 | | #define PSA_ALG_IS_CIPHER(alg) \ |
831 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER) |
832 | | |
833 | | /** Whether the specified algorithm is an authenticated encryption |
834 | | * with associated data (AEAD) algorithm. |
835 | | * |
836 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
837 | | * |
838 | | * \return 1 if \p alg is an AEAD algorithm, 0 otherwise. |
839 | | * This macro may return either 0 or 1 if \p alg is not a supported |
840 | | * algorithm identifier. |
841 | | */ |
842 | | #define PSA_ALG_IS_AEAD(alg) \ |
843 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD) |
844 | | |
845 | | /** Whether the specified algorithm is an asymmetric signature algorithm, |
846 | | * also known as public-key signature algorithm. |
847 | | * |
848 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
849 | | * |
850 | | * \return 1 if \p alg is an asymmetric signature algorithm, 0 otherwise. |
851 | | * This macro may return either 0 or 1 if \p alg is not a supported |
852 | | * algorithm identifier. |
853 | | */ |
854 | | #define PSA_ALG_IS_SIGN(alg) \ |
855 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN) |
856 | | |
857 | | /** Whether the specified algorithm is an asymmetric encryption algorithm, |
858 | | * also known as public-key encryption algorithm. |
859 | | * |
860 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
861 | | * |
862 | | * \return 1 if \p alg is an asymmetric encryption algorithm, 0 otherwise. |
863 | | * This macro may return either 0 or 1 if \p alg is not a supported |
864 | | * algorithm identifier. |
865 | | */ |
866 | | #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \ |
867 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION) |
868 | | |
869 | | /** Whether the specified algorithm is a key agreement algorithm. |
870 | | * |
871 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
872 | | * |
873 | | * \return 1 if \p alg is a key agreement algorithm, 0 otherwise. |
874 | | * This macro may return either 0 or 1 if \p alg is not a supported |
875 | | * algorithm identifier. |
876 | | */ |
877 | | #define PSA_ALG_IS_KEY_AGREEMENT(alg) \ |
878 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT) |
879 | | |
880 | | /** Whether the specified algorithm is a key derivation algorithm. |
881 | | * |
882 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
883 | | * |
884 | | * \return 1 if \p alg is a key derivation algorithm, 0 otherwise. |
885 | | * This macro may return either 0 or 1 if \p alg is not a supported |
886 | | * algorithm identifier. |
887 | | */ |
888 | | #define PSA_ALG_IS_KEY_DERIVATION(alg) \ |
889 | 0 | (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION) |
890 | | |
891 | | /** Whether the specified algorithm is a key stretching / password hashing |
892 | | * algorithm. |
893 | | * |
894 | | * A key stretching / password hashing algorithm is a key derivation algorithm |
895 | | * that is suitable for use with a low-entropy secret such as a password. |
896 | | * Equivalently, it's a key derivation algorithm that uses a |
897 | | * #PSA_KEY_DERIVATION_INPUT_PASSWORD input step. |
898 | | * |
899 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
900 | | * |
901 | | * \return 1 if \p alg is a key stretching / password hashing algorithm, 0 |
902 | | * otherwise. This macro may return either 0 or 1 if \p alg is not a |
903 | | * supported algorithm identifier. |
904 | | */ |
905 | | #define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \ |
906 | | (PSA_ALG_IS_KEY_DERIVATION(alg) && \ |
907 | | (alg) & PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG) |
908 | | |
909 | | /** An invalid algorithm identifier value. */ |
910 | | /* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */ |
911 | 0 | #define PSA_ALG_NONE ((psa_algorithm_t)0) |
912 | | /* *INDENT-ON* */ |
913 | | |
914 | 0 | #define PSA_ALG_HASH_MASK ((psa_algorithm_t) 0x000000ff) |
915 | | /** MD5 */ |
916 | 0 | #define PSA_ALG_MD5 ((psa_algorithm_t) 0x02000003) |
917 | | /** PSA_ALG_RIPEMD160 */ |
918 | 0 | #define PSA_ALG_RIPEMD160 ((psa_algorithm_t) 0x02000004) |
919 | | /** SHA1 */ |
920 | 0 | #define PSA_ALG_SHA_1 ((psa_algorithm_t) 0x02000005) |
921 | | /** SHA2-224 */ |
922 | 0 | #define PSA_ALG_SHA_224 ((psa_algorithm_t) 0x02000008) |
923 | | /** SHA2-256 */ |
924 | 0 | #define PSA_ALG_SHA_256 ((psa_algorithm_t) 0x02000009) |
925 | | /** SHA2-384 */ |
926 | 0 | #define PSA_ALG_SHA_384 ((psa_algorithm_t) 0x0200000a) |
927 | | /** SHA2-512 */ |
928 | 0 | #define PSA_ALG_SHA_512 ((psa_algorithm_t) 0x0200000b) |
929 | | /** SHA2-512/224 */ |
930 | 0 | #define PSA_ALG_SHA_512_224 ((psa_algorithm_t) 0x0200000c) |
931 | | /** SHA2-512/256 */ |
932 | 0 | #define PSA_ALG_SHA_512_256 ((psa_algorithm_t) 0x0200000d) |
933 | | /** SHA3-224 */ |
934 | 0 | #define PSA_ALG_SHA3_224 ((psa_algorithm_t) 0x02000010) |
935 | | /** SHA3-256 */ |
936 | 0 | #define PSA_ALG_SHA3_256 ((psa_algorithm_t) 0x02000011) |
937 | | /** SHA3-384 */ |
938 | 0 | #define PSA_ALG_SHA3_384 ((psa_algorithm_t) 0x02000012) |
939 | | /** SHA3-512 */ |
940 | 0 | #define PSA_ALG_SHA3_512 ((psa_algorithm_t) 0x02000013) |
941 | | /** The first 512 bits (64 bytes) of the SHAKE256 output. |
942 | | * |
943 | | * This is the prehashing for Ed448ph (see #PSA_ALG_ED448PH). For other |
944 | | * scenarios where a hash function based on SHA3/SHAKE is desired, SHA3-512 |
945 | | * has the same output size and a (theoretically) higher security strength. |
946 | | */ |
947 | | #define PSA_ALG_SHAKE256_512 ((psa_algorithm_t) 0x02000015) |
948 | | |
949 | | /** In a hash-and-sign algorithm policy, allow any hash algorithm. |
950 | | * |
951 | | * This value may be used to form the algorithm usage field of a policy |
952 | | * for a signature algorithm that is parametrized by a hash. The key |
953 | | * may then be used to perform operations using the same signature |
954 | | * algorithm parametrized with any supported hash. |
955 | | * |
956 | | * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros: |
957 | | * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, #PSA_ALG_RSA_PSS_ANY_SALT, |
958 | | * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA. |
959 | | * Then you may create and use a key as follows: |
960 | | * - Set the key usage field using #PSA_ALG_ANY_HASH, for example: |
961 | | * ``` |
962 | | * psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH); // or VERIFY |
963 | | * psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH)); |
964 | | * ``` |
965 | | * - Import or generate key material. |
966 | | * - Call psa_sign_hash() or psa_verify_hash(), passing |
967 | | * an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each |
968 | | * call to sign or verify a message may use a different hash. |
969 | | * ``` |
970 | | * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...); |
971 | | * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...); |
972 | | * psa_sign_hash(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...); |
973 | | * ``` |
974 | | * |
975 | | * This value may not be used to build other algorithms that are |
976 | | * parametrized over a hash. For any valid use of this macro to build |
977 | | * an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true. |
978 | | * |
979 | | * This value may not be used to build an algorithm specification to |
980 | | * perform an operation. It is only valid to build policies. |
981 | | */ |
982 | 0 | #define PSA_ALG_ANY_HASH ((psa_algorithm_t) 0x020000ff) |
983 | | |
984 | 0 | #define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t) 0x00c00000) |
985 | 0 | #define PSA_ALG_HMAC_BASE ((psa_algorithm_t) 0x03800000) |
986 | | /** Macro to build an HMAC algorithm. |
987 | | * |
988 | | * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256. |
989 | | * |
990 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
991 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
992 | | * |
993 | | * \return The corresponding HMAC algorithm. |
994 | | * \return Unspecified if \p hash_alg is not a supported |
995 | | * hash algorithm. |
996 | | */ |
997 | | #define PSA_ALG_HMAC(hash_alg) \ |
998 | 0 | (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
999 | | |
1000 | | #define PSA_ALG_HMAC_GET_HASH(hmac_alg) \ |
1001 | 0 | (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK)) |
1002 | | |
1003 | | /** Whether the specified algorithm is an HMAC algorithm. |
1004 | | * |
1005 | | * HMAC is a family of MAC algorithms that are based on a hash function. |
1006 | | * |
1007 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1008 | | * |
1009 | | * \return 1 if \p alg is an HMAC algorithm, 0 otherwise. |
1010 | | * This macro may return either 0 or 1 if \p alg is not a supported |
1011 | | * algorithm identifier. |
1012 | | */ |
1013 | | #define PSA_ALG_IS_HMAC(alg) \ |
1014 | 0 | (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ |
1015 | 0 | PSA_ALG_HMAC_BASE) |
1016 | | |
1017 | | /* In the encoding of a MAC algorithm, the bits corresponding to |
1018 | | * PSA_ALG_MAC_TRUNCATION_MASK encode the length to which the MAC is |
1019 | | * truncated. As an exception, the value 0 means the untruncated algorithm, |
1020 | | * whatever its length is. The length is encoded in 6 bits, so it can |
1021 | | * reach up to 63; the largest MAC is 64 bytes so its trivial truncation |
1022 | | * to full length is correctly encoded as 0 and any non-trivial truncation |
1023 | | * is correctly encoded as a value between 1 and 63. */ |
1024 | 0 | #define PSA_ALG_MAC_TRUNCATION_MASK ((psa_algorithm_t) 0x003f0000) |
1025 | 0 | #define PSA_MAC_TRUNCATION_OFFSET 16 |
1026 | | |
1027 | | /* In the encoding of a MAC algorithm, the bit corresponding to |
1028 | | * #PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm |
1029 | | * is a wildcard algorithm. A key with such wildcard algorithm as permitted |
1030 | | * algorithm policy can be used with any algorithm corresponding to the |
1031 | | * same base class and having a (potentially truncated) MAC length greater or |
1032 | | * equal than the one encoded in #PSA_ALG_MAC_TRUNCATION_MASK. */ |
1033 | 0 | #define PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG ((psa_algorithm_t) 0x00008000) |
1034 | | |
1035 | | /** Macro to build a truncated MAC algorithm. |
1036 | | * |
1037 | | * A truncated MAC algorithm is identical to the corresponding MAC |
1038 | | * algorithm except that the MAC value for the truncated algorithm |
1039 | | * consists of only the first \p mac_length bytes of the MAC value |
1040 | | * for the untruncated algorithm. |
1041 | | * |
1042 | | * \note This macro may allow constructing algorithm identifiers that |
1043 | | * are not valid, either because the specified length is larger |
1044 | | * than the untruncated MAC or because the specified length is |
1045 | | * smaller than permitted by the implementation. |
1046 | | * |
1047 | | * \note It is implementation-defined whether a truncated MAC that |
1048 | | * is truncated to the same length as the MAC of the untruncated |
1049 | | * algorithm is considered identical to the untruncated algorithm |
1050 | | * for policy comparison purposes. |
1051 | | * |
1052 | | * \param mac_alg A MAC algorithm identifier (value of type |
1053 | | * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) |
1054 | | * is true). This may be a truncated or untruncated |
1055 | | * MAC algorithm. |
1056 | | * \param mac_length Desired length of the truncated MAC in bytes. |
1057 | | * This must be at most the full length of the MAC |
1058 | | * and must be at least an implementation-specified |
1059 | | * minimum. The implementation-specified minimum |
1060 | | * shall not be zero. |
1061 | | * |
1062 | | * \return The corresponding MAC algorithm with the specified |
1063 | | * length. |
1064 | | * \return Unspecified if \p mac_alg is not a supported |
1065 | | * MAC algorithm or if \p mac_length is too small or |
1066 | | * too large for the specified MAC algorithm. |
1067 | | */ |
1068 | | #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \ |
1069 | 0 | (((mac_alg) & ~(PSA_ALG_MAC_TRUNCATION_MASK | \ |
1070 | 0 | PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG)) | \ |
1071 | 0 | ((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK)) |
1072 | | |
1073 | | /** Macro to build the base MAC algorithm corresponding to a truncated |
1074 | | * MAC algorithm. |
1075 | | * |
1076 | | * \param mac_alg A MAC algorithm identifier (value of type |
1077 | | * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) |
1078 | | * is true). This may be a truncated or untruncated |
1079 | | * MAC algorithm. |
1080 | | * |
1081 | | * \return The corresponding base MAC algorithm. |
1082 | | * \return Unspecified if \p mac_alg is not a supported |
1083 | | * MAC algorithm. |
1084 | | */ |
1085 | | #define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \ |
1086 | 0 | ((mac_alg) & ~(PSA_ALG_MAC_TRUNCATION_MASK | \ |
1087 | 0 | PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG)) |
1088 | | |
1089 | | /** Length to which a MAC algorithm is truncated. |
1090 | | * |
1091 | | * \param mac_alg A MAC algorithm identifier (value of type |
1092 | | * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) |
1093 | | * is true). |
1094 | | * |
1095 | | * \return Length of the truncated MAC in bytes. |
1096 | | * \return 0 if \p mac_alg is a non-truncated MAC algorithm. |
1097 | | * \return Unspecified if \p mac_alg is not a supported |
1098 | | * MAC algorithm. |
1099 | | */ |
1100 | | #define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \ |
1101 | 0 | (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET) |
1102 | | |
1103 | | /** Macro to build a MAC minimum-MAC-length wildcard algorithm. |
1104 | | * |
1105 | | * A minimum-MAC-length MAC wildcard algorithm permits all MAC algorithms |
1106 | | * sharing the same base algorithm, and where the (potentially truncated) MAC |
1107 | | * length of the specific algorithm is equal to or larger then the wildcard |
1108 | | * algorithm's minimum MAC length. |
1109 | | * |
1110 | | * \note When setting the minimum required MAC length to less than the |
1111 | | * smallest MAC length allowed by the base algorithm, this effectively |
1112 | | * becomes an 'any-MAC-length-allowed' policy for that base algorithm. |
1113 | | * |
1114 | | * \param mac_alg A MAC algorithm identifier (value of type |
1115 | | * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg) |
1116 | | * is true). |
1117 | | * \param min_mac_length Desired minimum length of the message authentication |
1118 | | * code in bytes. This must be at most the untruncated |
1119 | | * length of the MAC and must be at least 1. |
1120 | | * |
1121 | | * \return The corresponding MAC wildcard algorithm with the |
1122 | | * specified minimum length. |
1123 | | * \return Unspecified if \p mac_alg is not a supported MAC |
1124 | | * algorithm or if \p min_mac_length is less than 1 or |
1125 | | * too large for the specified MAC algorithm. |
1126 | | */ |
1127 | | #define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \ |
1128 | 0 | (PSA_ALG_TRUNCATED_MAC(mac_alg, min_mac_length) | \ |
1129 | 0 | PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG) |
1130 | | |
1131 | 0 | #define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t) 0x03c00000) |
1132 | | /** The CBC-MAC construction over a block cipher |
1133 | | * |
1134 | | * \warning CBC-MAC is insecure in many cases. |
1135 | | * A more secure mode, such as #PSA_ALG_CMAC, is recommended. |
1136 | | */ |
1137 | | #define PSA_ALG_CBC_MAC ((psa_algorithm_t) 0x03c00100) |
1138 | | /** The CMAC construction over a block cipher */ |
1139 | 0 | #define PSA_ALG_CMAC ((psa_algorithm_t) 0x03c00200) |
1140 | | |
1141 | | /** Whether the specified algorithm is a MAC algorithm based on a block cipher. |
1142 | | * |
1143 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1144 | | * |
1145 | | * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise. |
1146 | | * This macro may return either 0 or 1 if \p alg is not a supported |
1147 | | * algorithm identifier. |
1148 | | */ |
1149 | | #define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) \ |
1150 | 0 | (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ |
1151 | 0 | PSA_ALG_CIPHER_MAC_BASE) |
1152 | | |
1153 | 0 | #define PSA_ALG_CIPHER_STREAM_FLAG ((psa_algorithm_t) 0x00800000) |
1154 | | #define PSA_ALG_CIPHER_FROM_BLOCK_FLAG ((psa_algorithm_t) 0x00400000) |
1155 | | |
1156 | | /** Whether the specified algorithm is a stream cipher. |
1157 | | * |
1158 | | * A stream cipher is a symmetric cipher that encrypts or decrypts messages |
1159 | | * by applying a bitwise-xor with a stream of bytes that is generated |
1160 | | * from a key. |
1161 | | * |
1162 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1163 | | * |
1164 | | * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise. |
1165 | | * This macro may return either 0 or 1 if \p alg is not a supported |
1166 | | * algorithm identifier or if it is not a symmetric cipher algorithm. |
1167 | | */ |
1168 | | #define PSA_ALG_IS_STREAM_CIPHER(alg) \ |
1169 | 0 | (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_STREAM_FLAG)) == \ |
1170 | 0 | (PSA_ALG_CATEGORY_CIPHER | PSA_ALG_CIPHER_STREAM_FLAG)) |
1171 | | |
1172 | | /** The stream cipher mode of a stream cipher algorithm. |
1173 | | * |
1174 | | * The underlying stream cipher is determined by the key type. |
1175 | | * - To use ChaCha20, use a key type of #PSA_KEY_TYPE_CHACHA20. |
1176 | | */ |
1177 | 0 | #define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t) 0x04800100) |
1178 | | |
1179 | | /** The CTR stream cipher mode. |
1180 | | * |
1181 | | * CTR is a stream cipher which is built from a block cipher. |
1182 | | * The underlying block cipher is determined by the key type. |
1183 | | * For example, to use AES-128-CTR, use this algorithm with |
1184 | | * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). |
1185 | | */ |
1186 | 0 | #define PSA_ALG_CTR ((psa_algorithm_t) 0x04c01000) |
1187 | | |
1188 | | /** The CFB stream cipher mode. |
1189 | | * |
1190 | | * The underlying block cipher is determined by the key type. |
1191 | | */ |
1192 | 0 | #define PSA_ALG_CFB ((psa_algorithm_t) 0x04c01100) |
1193 | | |
1194 | | /** The OFB stream cipher mode. |
1195 | | * |
1196 | | * The underlying block cipher is determined by the key type. |
1197 | | */ |
1198 | 0 | #define PSA_ALG_OFB ((psa_algorithm_t) 0x04c01200) |
1199 | | |
1200 | | /** The XTS cipher mode. |
1201 | | * |
1202 | | * XTS is a cipher mode which is built from a block cipher. It requires at |
1203 | | * least one full block of input, but beyond this minimum the input |
1204 | | * does not need to be a whole number of blocks. |
1205 | | */ |
1206 | 0 | #define PSA_ALG_XTS ((psa_algorithm_t) 0x0440ff00) |
1207 | | |
1208 | | /** The Electronic Code Book (ECB) mode of a block cipher, with no padding. |
1209 | | * |
1210 | | * \warning ECB mode does not protect the confidentiality of the encrypted data |
1211 | | * except in extremely narrow circumstances. It is recommended that applications |
1212 | | * only use ECB if they need to construct an operating mode that the |
1213 | | * implementation does not provide. Implementations are encouraged to provide |
1214 | | * the modes that applications need in preference to supporting direct access |
1215 | | * to ECB. |
1216 | | * |
1217 | | * The underlying block cipher is determined by the key type. |
1218 | | * |
1219 | | * This symmetric cipher mode can only be used with messages whose lengths are a |
1220 | | * multiple of the block size of the chosen block cipher. |
1221 | | * |
1222 | | * ECB mode does not accept an initialization vector (IV). When using a |
1223 | | * multi-part cipher operation with this algorithm, psa_cipher_generate_iv() |
1224 | | * and psa_cipher_set_iv() must not be called. |
1225 | | */ |
1226 | 0 | #define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t) 0x04404400) |
1227 | | |
1228 | | /** The CBC block cipher chaining mode, with no padding. |
1229 | | * |
1230 | | * The underlying block cipher is determined by the key type. |
1231 | | * |
1232 | | * This symmetric cipher mode can only be used with messages whose lengths |
1233 | | * are whole number of blocks for the chosen block cipher. |
1234 | | */ |
1235 | 0 | #define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t) 0x04404000) |
1236 | | |
1237 | | /** The CBC block cipher chaining mode with PKCS#7 padding. |
1238 | | * |
1239 | | * The underlying block cipher is determined by the key type. |
1240 | | * |
1241 | | * This is the padding method defined by PKCS#7 (RFC 2315) §10.3. |
1242 | | */ |
1243 | 0 | #define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t) 0x04404100) |
1244 | | |
1245 | | #define PSA_ALG_AEAD_FROM_BLOCK_FLAG ((psa_algorithm_t) 0x00400000) |
1246 | | |
1247 | | /** Whether the specified algorithm is an AEAD mode on a block cipher. |
1248 | | * |
1249 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1250 | | * |
1251 | | * \return 1 if \p alg is an AEAD algorithm which is an AEAD mode based on |
1252 | | * a block cipher, 0 otherwise. |
1253 | | * This macro may return either 0 or 1 if \p alg is not a supported |
1254 | | * algorithm identifier. |
1255 | | */ |
1256 | | #define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) \ |
1257 | | (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) == \ |
1258 | | (PSA_ALG_CATEGORY_AEAD | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) |
1259 | | |
1260 | | /** The CCM authenticated encryption algorithm. |
1261 | | * |
1262 | | * The underlying block cipher is determined by the key type. |
1263 | | */ |
1264 | 0 | #define PSA_ALG_CCM ((psa_algorithm_t) 0x05500100) |
1265 | | |
1266 | | /** The CCM* cipher mode without authentication. |
1267 | | * |
1268 | | * This is CCM* as specified in IEEE 802.15.4 §7, with a tag length of 0. |
1269 | | * For CCM* with a nonzero tag length, use the AEAD algorithm #PSA_ALG_CCM. |
1270 | | * |
1271 | | * The underlying block cipher is determined by the key type. |
1272 | | * |
1273 | | * Currently only 13-byte long IV's are supported. |
1274 | | */ |
1275 | 0 | #define PSA_ALG_CCM_STAR_NO_TAG ((psa_algorithm_t) 0x04c01300) |
1276 | | |
1277 | | /** The GCM authenticated encryption algorithm. |
1278 | | * |
1279 | | * The underlying block cipher is determined by the key type. |
1280 | | */ |
1281 | 0 | #define PSA_ALG_GCM ((psa_algorithm_t) 0x05500200) |
1282 | | |
1283 | | /** The Chacha20-Poly1305 AEAD algorithm. |
1284 | | * |
1285 | | * The ChaCha20_Poly1305 construction is defined in RFC 7539. |
1286 | | * |
1287 | | * Implementations must support 12-byte nonces, may support 8-byte nonces, |
1288 | | * and should reject other sizes. |
1289 | | * |
1290 | | * Implementations must support 16-byte tags and should reject other sizes. |
1291 | | */ |
1292 | 0 | #define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t) 0x05100500) |
1293 | | |
1294 | | /* In the encoding of an AEAD algorithm, the bits corresponding to |
1295 | | * PSA_ALG_AEAD_TAG_LENGTH_MASK encode the length of the AEAD tag. |
1296 | | * The constants for default lengths follow this encoding. |
1297 | | */ |
1298 | 0 | #define PSA_ALG_AEAD_TAG_LENGTH_MASK ((psa_algorithm_t) 0x003f0000) |
1299 | 0 | #define PSA_AEAD_TAG_LENGTH_OFFSET 16 |
1300 | | |
1301 | | /* In the encoding of an AEAD algorithm, the bit corresponding to |
1302 | | * #PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG encodes the fact that the algorithm |
1303 | | * is a wildcard algorithm. A key with such wildcard algorithm as permitted |
1304 | | * algorithm policy can be used with any algorithm corresponding to the |
1305 | | * same base class and having a tag length greater than or equal to the one |
1306 | | * encoded in #PSA_ALG_AEAD_TAG_LENGTH_MASK. */ |
1307 | 0 | #define PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG ((psa_algorithm_t) 0x00008000) |
1308 | | |
1309 | | /** Macro to build a shortened AEAD algorithm. |
1310 | | * |
1311 | | * A shortened AEAD algorithm is similar to the corresponding AEAD |
1312 | | * algorithm, but has an authentication tag that consists of fewer bytes. |
1313 | | * Depending on the algorithm, the tag length may affect the calculation |
1314 | | * of the ciphertext. |
1315 | | * |
1316 | | * \param aead_alg An AEAD algorithm identifier (value of type |
1317 | | * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg) |
1318 | | * is true). |
1319 | | * \param tag_length Desired length of the authentication tag in bytes. |
1320 | | * |
1321 | | * \return The corresponding AEAD algorithm with the specified |
1322 | | * length. |
1323 | | * \return Unspecified if \p aead_alg is not a supported |
1324 | | * AEAD algorithm or if \p tag_length is not valid |
1325 | | * for the specified AEAD algorithm. |
1326 | | */ |
1327 | | #define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \ |
1328 | 0 | (((aead_alg) & ~(PSA_ALG_AEAD_TAG_LENGTH_MASK | \ |
1329 | 0 | PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG)) | \ |
1330 | 0 | ((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET & \ |
1331 | 0 | PSA_ALG_AEAD_TAG_LENGTH_MASK)) |
1332 | | |
1333 | | /** Retrieve the tag length of a specified AEAD algorithm |
1334 | | * |
1335 | | * \param aead_alg An AEAD algorithm identifier (value of type |
1336 | | * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg) |
1337 | | * is true). |
1338 | | * |
1339 | | * \return The tag length specified by the input algorithm. |
1340 | | * \return Unspecified if \p aead_alg is not a supported |
1341 | | * AEAD algorithm. |
1342 | | */ |
1343 | | #define PSA_ALG_AEAD_GET_TAG_LENGTH(aead_alg) \ |
1344 | 0 | (((aead_alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> \ |
1345 | 0 | PSA_AEAD_TAG_LENGTH_OFFSET) |
1346 | | |
1347 | | /** Calculate the corresponding AEAD algorithm with the default tag length. |
1348 | | * |
1349 | | * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that |
1350 | | * #PSA_ALG_IS_AEAD(\p aead_alg) is true). |
1351 | | * |
1352 | | * \return The corresponding AEAD algorithm with the default |
1353 | | * tag length for that algorithm. |
1354 | | */ |
1355 | | #define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg) \ |
1356 | 0 | ( \ |
1357 | 0 | PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_CCM) \ |
1358 | 0 | PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_GCM) \ |
1359 | 0 | PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, PSA_ALG_CHACHA20_POLY1305) \ |
1360 | 0 | 0) |
1361 | | #define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG_CASE(aead_alg, ref) \ |
1362 | 0 | PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, 0) == \ |
1363 | 0 | PSA_ALG_AEAD_WITH_SHORTENED_TAG(ref, 0) ? \ |
1364 | 0 | ref : |
1365 | | |
1366 | | /** Macro to build an AEAD minimum-tag-length wildcard algorithm. |
1367 | | * |
1368 | | * A minimum-tag-length AEAD wildcard algorithm permits all AEAD algorithms |
1369 | | * sharing the same base algorithm, and where the tag length of the specific |
1370 | | * algorithm is equal to or larger then the minimum tag length specified by the |
1371 | | * wildcard algorithm. |
1372 | | * |
1373 | | * \note When setting the minimum required tag length to less than the |
1374 | | * smallest tag length allowed by the base algorithm, this effectively |
1375 | | * becomes an 'any-tag-length-allowed' policy for that base algorithm. |
1376 | | * |
1377 | | * \param aead_alg An AEAD algorithm identifier (value of type |
1378 | | * #psa_algorithm_t such that |
1379 | | * #PSA_ALG_IS_AEAD(\p aead_alg) is true). |
1380 | | * \param min_tag_length Desired minimum length of the authentication tag in |
1381 | | * bytes. This must be at least 1 and at most the largest |
1382 | | * allowed tag length of the algorithm. |
1383 | | * |
1384 | | * \return The corresponding AEAD wildcard algorithm with the |
1385 | | * specified minimum length. |
1386 | | * \return Unspecified if \p aead_alg is not a supported |
1387 | | * AEAD algorithm or if \p min_tag_length is less than 1 |
1388 | | * or too large for the specified AEAD algorithm. |
1389 | | */ |
1390 | | #define PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG(aead_alg, min_tag_length) \ |
1391 | 0 | (PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, min_tag_length) | \ |
1392 | 0 | PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG) |
1393 | | |
1394 | 0 | #define PSA_ALG_RSA_PKCS1V15_SIGN_BASE ((psa_algorithm_t) 0x06000200) |
1395 | | /** RSA PKCS#1 v1.5 signature with hashing. |
1396 | | * |
1397 | | * This is the signature scheme defined by RFC 8017 |
1398 | | * (PKCS#1: RSA Cryptography Specifications) under the name |
1399 | | * RSASSA-PKCS1-v1_5. |
1400 | | * |
1401 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1402 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1403 | | * This includes #PSA_ALG_ANY_HASH |
1404 | | * when specifying the algorithm in a usage policy. |
1405 | | * |
1406 | | * \return The corresponding RSA PKCS#1 v1.5 signature algorithm. |
1407 | | * \return Unspecified if \p hash_alg is not a supported |
1408 | | * hash algorithm. |
1409 | | */ |
1410 | | #define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \ |
1411 | 0 | (PSA_ALG_RSA_PKCS1V15_SIGN_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1412 | | /** Raw PKCS#1 v1.5 signature. |
1413 | | * |
1414 | | * The input to this algorithm is the DigestInfo structure used by |
1415 | | * RFC 8017 (PKCS#1: RSA Cryptography Specifications), §9.2 |
1416 | | * steps 3–6. |
1417 | | */ |
1418 | 0 | #define PSA_ALG_RSA_PKCS1V15_SIGN_RAW PSA_ALG_RSA_PKCS1V15_SIGN_BASE |
1419 | | #define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \ |
1420 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_BASE) |
1421 | | |
1422 | 0 | #define PSA_ALG_RSA_PSS_BASE ((psa_algorithm_t) 0x06000300) |
1423 | 0 | #define PSA_ALG_RSA_PSS_ANY_SALT_BASE ((psa_algorithm_t) 0x06001300) |
1424 | | /** RSA PSS signature with hashing. |
1425 | | * |
1426 | | * This is the signature scheme defined by RFC 8017 |
1427 | | * (PKCS#1: RSA Cryptography Specifications) under the name |
1428 | | * RSASSA-PSS, with the message generation function MGF1, and with |
1429 | | * a salt length equal to the length of the hash, or the largest |
1430 | | * possible salt length for the algorithm and key size if that is |
1431 | | * smaller than the hash length. The specified hash algorithm is |
1432 | | * used to hash the input message, to create the salted hash, and |
1433 | | * for the mask generation. |
1434 | | * |
1435 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1436 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1437 | | * This includes #PSA_ALG_ANY_HASH |
1438 | | * when specifying the algorithm in a usage policy. |
1439 | | * |
1440 | | * \return The corresponding RSA PSS signature algorithm. |
1441 | | * \return Unspecified if \p hash_alg is not a supported |
1442 | | * hash algorithm. |
1443 | | */ |
1444 | | #define PSA_ALG_RSA_PSS(hash_alg) \ |
1445 | 0 | (PSA_ALG_RSA_PSS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1446 | | |
1447 | | /** RSA PSS signature with hashing with relaxed verification. |
1448 | | * |
1449 | | * This algorithm has the same behavior as #PSA_ALG_RSA_PSS when signing, |
1450 | | * but allows an arbitrary salt length (including \c 0) when verifying a |
1451 | | * signature. |
1452 | | * |
1453 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1454 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1455 | | * This includes #PSA_ALG_ANY_HASH |
1456 | | * when specifying the algorithm in a usage policy. |
1457 | | * |
1458 | | * \return The corresponding RSA PSS signature algorithm. |
1459 | | * \return Unspecified if \p hash_alg is not a supported |
1460 | | * hash algorithm. |
1461 | | */ |
1462 | | #define PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) \ |
1463 | 0 | (PSA_ALG_RSA_PSS_ANY_SALT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1464 | | |
1465 | | /** Whether the specified algorithm is RSA PSS with standard salt. |
1466 | | * |
1467 | | * \param alg An algorithm value or an algorithm policy wildcard. |
1468 | | * |
1469 | | * \return 1 if \p alg is of the form |
1470 | | * #PSA_ALG_RSA_PSS(\c hash_alg), |
1471 | | * where \c hash_alg is a hash algorithm or |
1472 | | * #PSA_ALG_ANY_HASH. 0 otherwise. |
1473 | | * This macro may return either 0 or 1 if \p alg is not |
1474 | | * a supported algorithm identifier or policy. |
1475 | | */ |
1476 | | #define PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) \ |
1477 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_BASE) |
1478 | | |
1479 | | /** Whether the specified algorithm is RSA PSS with any salt. |
1480 | | * |
1481 | | * \param alg An algorithm value or an algorithm policy wildcard. |
1482 | | * |
1483 | | * \return 1 if \p alg is of the form |
1484 | | * #PSA_ALG_RSA_PSS_ANY_SALT_BASE(\c hash_alg), |
1485 | | * where \c hash_alg is a hash algorithm or |
1486 | | * #PSA_ALG_ANY_HASH. 0 otherwise. |
1487 | | * This macro may return either 0 or 1 if \p alg is not |
1488 | | * a supported algorithm identifier or policy. |
1489 | | */ |
1490 | | #define PSA_ALG_IS_RSA_PSS_ANY_SALT(alg) \ |
1491 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_ANY_SALT_BASE) |
1492 | | |
1493 | | /** Whether the specified algorithm is RSA PSS. |
1494 | | * |
1495 | | * This includes any of the RSA PSS algorithm variants, regardless of the |
1496 | | * constraints on salt length. |
1497 | | * |
1498 | | * \param alg An algorithm value or an algorithm policy wildcard. |
1499 | | * |
1500 | | * \return 1 if \p alg is of the form |
1501 | | * #PSA_ALG_RSA_PSS(\c hash_alg) or |
1502 | | * #PSA_ALG_RSA_PSS_ANY_SALT_BASE(\c hash_alg), |
1503 | | * where \c hash_alg is a hash algorithm or |
1504 | | * #PSA_ALG_ANY_HASH. 0 otherwise. |
1505 | | * This macro may return either 0 or 1 if \p alg is not |
1506 | | * a supported algorithm identifier or policy. |
1507 | | */ |
1508 | | #define PSA_ALG_IS_RSA_PSS(alg) \ |
1509 | 0 | (PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) || \ |
1510 | 0 | PSA_ALG_IS_RSA_PSS_ANY_SALT(alg)) |
1511 | | |
1512 | 0 | #define PSA_ALG_ECDSA_BASE ((psa_algorithm_t) 0x06000600) |
1513 | | /** ECDSA signature with hashing. |
1514 | | * |
1515 | | * This is the ECDSA signature scheme defined by ANSI X9.62, |
1516 | | * with a random per-message secret number (*k*). |
1517 | | * |
1518 | | * The representation of the signature as a byte string consists of |
1519 | | * the concatenation of the signature values *r* and *s*. Each of |
1520 | | * *r* and *s* is encoded as an *N*-octet string, where *N* is the length |
1521 | | * of the base point of the curve in octets. Each value is represented |
1522 | | * in big-endian order (most significant octet first). |
1523 | | * |
1524 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1525 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1526 | | * This includes #PSA_ALG_ANY_HASH |
1527 | | * when specifying the algorithm in a usage policy. |
1528 | | * |
1529 | | * \return The corresponding ECDSA signature algorithm. |
1530 | | * \return Unspecified if \p hash_alg is not a supported |
1531 | | * hash algorithm. |
1532 | | */ |
1533 | | #define PSA_ALG_ECDSA(hash_alg) \ |
1534 | 0 | (PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1535 | | /** ECDSA signature without hashing. |
1536 | | * |
1537 | | * This is the same signature scheme as #PSA_ALG_ECDSA(), but |
1538 | | * without specifying a hash algorithm. This algorithm may only be |
1539 | | * used to sign or verify a sequence of bytes that should be an |
1540 | | * already-calculated hash. Note that the input is padded with |
1541 | | * zeros on the left or truncated on the left as required to fit |
1542 | | * the curve size. |
1543 | | */ |
1544 | 0 | #define PSA_ALG_ECDSA_ANY PSA_ALG_ECDSA_BASE |
1545 | 0 | #define PSA_ALG_DETERMINISTIC_ECDSA_BASE ((psa_algorithm_t) 0x06000700) |
1546 | | /** Deterministic ECDSA signature with hashing. |
1547 | | * |
1548 | | * This is the deterministic ECDSA signature scheme defined by RFC 6979. |
1549 | | * |
1550 | | * The representation of a signature is the same as with #PSA_ALG_ECDSA(). |
1551 | | * |
1552 | | * Note that when this algorithm is used for verification, signatures |
1553 | | * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the |
1554 | | * same private key are accepted. In other words, |
1555 | | * #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from |
1556 | | * #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification. |
1557 | | * |
1558 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1559 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1560 | | * This includes #PSA_ALG_ANY_HASH |
1561 | | * when specifying the algorithm in a usage policy. |
1562 | | * |
1563 | | * \return The corresponding deterministic ECDSA signature |
1564 | | * algorithm. |
1565 | | * \return Unspecified if \p hash_alg is not a supported |
1566 | | * hash algorithm. |
1567 | | */ |
1568 | | #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \ |
1569 | 0 | (PSA_ALG_DETERMINISTIC_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1570 | 0 | #define PSA_ALG_ECDSA_DETERMINISTIC_FLAG ((psa_algorithm_t) 0x00000100) |
1571 | | #define PSA_ALG_IS_ECDSA(alg) \ |
1572 | 0 | (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_ECDSA_DETERMINISTIC_FLAG) == \ |
1573 | 0 | PSA_ALG_ECDSA_BASE) |
1574 | | #define PSA_ALG_ECDSA_IS_DETERMINISTIC(alg) \ |
1575 | 0 | (((alg) & PSA_ALG_ECDSA_DETERMINISTIC_FLAG) != 0) |
1576 | | #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ |
1577 | 0 | (PSA_ALG_IS_ECDSA(alg) && PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) |
1578 | | #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \ |
1579 | 0 | (PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) |
1580 | | |
1581 | | /** Edwards-curve digital signature algorithm without prehashing (PureEdDSA), |
1582 | | * using standard parameters. |
1583 | | * |
1584 | | * Contexts are not supported in the current version of this specification |
1585 | | * because there is no suitable signature interface that can take the |
1586 | | * context as a parameter. A future version of this specification may add |
1587 | | * suitable functions and extend this algorithm to support contexts. |
1588 | | * |
1589 | | * PureEdDSA requires an elliptic curve key on a twisted Edwards curve. |
1590 | | * In this specification, the following curves are supported: |
1591 | | * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified |
1592 | | * in RFC 8032. |
1593 | | * The curve is Edwards25519. |
1594 | | * The hash function used internally is SHA-512. |
1595 | | * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 448-bit: Ed448 as specified |
1596 | | * in RFC 8032. |
1597 | | * The curve is Edwards448. |
1598 | | * The hash function used internally is the first 114 bytes of the |
1599 | | * SHAKE256 output. |
1600 | | * |
1601 | | * This algorithm can be used with psa_sign_message() and |
1602 | | * psa_verify_message(). Since there is no prehashing, it cannot be used |
1603 | | * with psa_sign_hash() or psa_verify_hash(). |
1604 | | * |
1605 | | * The signature format is the concatenation of R and S as defined by |
1606 | | * RFC 8032 §5.1.6 and §5.2.6 (a 64-byte string for Ed25519, a 114-byte |
1607 | | * string for Ed448). |
1608 | | */ |
1609 | 0 | #define PSA_ALG_PURE_EDDSA ((psa_algorithm_t) 0x06000800) |
1610 | | |
1611 | 0 | #define PSA_ALG_HASH_EDDSA_BASE ((psa_algorithm_t) 0x06000900) |
1612 | | #define PSA_ALG_IS_HASH_EDDSA(alg) \ |
1613 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HASH_EDDSA_BASE) |
1614 | | |
1615 | | /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA), |
1616 | | * using SHA-512 and the Edwards25519 curve. |
1617 | | * |
1618 | | * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. |
1619 | | * |
1620 | | * This algorithm is Ed25519 as specified in RFC 8032. |
1621 | | * The curve is Edwards25519. |
1622 | | * The prehash is SHA-512. |
1623 | | * The hash function used internally is SHA-512. |
1624 | | * |
1625 | | * This is a hash-and-sign algorithm: to calculate a signature, |
1626 | | * you can either: |
1627 | | * - call psa_sign_message() on the message; |
1628 | | * - or calculate the SHA-512 hash of the message |
1629 | | * with psa_hash_compute() |
1630 | | * or with a multi-part hash operation started with psa_hash_setup(), |
1631 | | * using the hash algorithm #PSA_ALG_SHA_512, |
1632 | | * then sign the calculated hash with psa_sign_hash(). |
1633 | | * Verifying a signature is similar, using psa_verify_message() or |
1634 | | * psa_verify_hash() instead of the signature function. |
1635 | | */ |
1636 | | #define PSA_ALG_ED25519PH \ |
1637 | | (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHA_512 & PSA_ALG_HASH_MASK)) |
1638 | | |
1639 | | /** Edwards-curve digital signature algorithm with prehashing (HashEdDSA), |
1640 | | * using SHAKE256 and the Edwards448 curve. |
1641 | | * |
1642 | | * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format. |
1643 | | * |
1644 | | * This algorithm is Ed448 as specified in RFC 8032. |
1645 | | * The curve is Edwards448. |
1646 | | * The prehash is the first 64 bytes of the SHAKE256 output. |
1647 | | * The hash function used internally is the first 114 bytes of the |
1648 | | * SHAKE256 output. |
1649 | | * |
1650 | | * This is a hash-and-sign algorithm: to calculate a signature, |
1651 | | * you can either: |
1652 | | * - call psa_sign_message() on the message; |
1653 | | * - or calculate the first 64 bytes of the SHAKE256 output of the message |
1654 | | * with psa_hash_compute() |
1655 | | * or with a multi-part hash operation started with psa_hash_setup(), |
1656 | | * using the hash algorithm #PSA_ALG_SHAKE256_512, |
1657 | | * then sign the calculated hash with psa_sign_hash(). |
1658 | | * Verifying a signature is similar, using psa_verify_message() or |
1659 | | * psa_verify_hash() instead of the signature function. |
1660 | | */ |
1661 | | #define PSA_ALG_ED448PH \ |
1662 | | (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHAKE256_512 & PSA_ALG_HASH_MASK)) |
1663 | | |
1664 | | /* Default definition, to be overridden if the library is extended with |
1665 | | * more hash-and-sign algorithms that we want to keep out of this header |
1666 | | * file. */ |
1667 | | #define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) 0 |
1668 | | |
1669 | | /** Whether the specified algorithm is a signature algorithm that can be used |
1670 | | * with psa_sign_hash() and psa_verify_hash(). |
1671 | | * |
1672 | | * This encompasses all strict hash-and-sign algorithms categorized by |
1673 | | * PSA_ALG_IS_HASH_AND_SIGN(), as well as algorithms that follow the |
1674 | | * paradigm more loosely: |
1675 | | * - #PSA_ALG_RSA_PKCS1V15_SIGN_RAW (expects its input to be an encoded hash) |
1676 | | * - #PSA_ALG_ECDSA_ANY (doesn't specify what kind of hash the input is) |
1677 | | * |
1678 | | * \param alg An algorithm identifier (value of type psa_algorithm_t). |
1679 | | * |
1680 | | * \return 1 if alg is a signature algorithm that can be used to sign a |
1681 | | * hash. 0 if alg is a signature algorithm that can only be used |
1682 | | * to sign a message. 0 if alg is not a signature algorithm. |
1683 | | * This macro can return either 0 or 1 if alg is not a |
1684 | | * supported algorithm identifier. |
1685 | | */ |
1686 | | #define PSA_ALG_IS_SIGN_HASH(alg) \ |
1687 | 0 | (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \ |
1688 | 0 | PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg) || \ |
1689 | 0 | PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg)) |
1690 | | |
1691 | | /** Whether the specified algorithm is a signature algorithm that can be used |
1692 | | * with psa_sign_message() and psa_verify_message(). |
1693 | | * |
1694 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1695 | | * |
1696 | | * \return 1 if alg is a signature algorithm that can be used to sign a |
1697 | | * message. 0 if \p alg is a signature algorithm that can only be used |
1698 | | * to sign an already-calculated hash. 0 if \p alg is not a signature |
1699 | | * algorithm. This macro can return either 0 or 1 if \p alg is not a |
1700 | | * supported algorithm identifier. |
1701 | | */ |
1702 | | #define PSA_ALG_IS_SIGN_MESSAGE(alg) \ |
1703 | 0 | (PSA_ALG_IS_SIGN_HASH(alg) || (alg) == PSA_ALG_PURE_EDDSA) |
1704 | | |
1705 | | /** Whether the specified algorithm is a hash-and-sign algorithm. |
1706 | | * |
1707 | | * Hash-and-sign algorithms are asymmetric (public-key) signature algorithms |
1708 | | * structured in two parts: first the calculation of a hash in a way that |
1709 | | * does not depend on the key, then the calculation of a signature from the |
1710 | | * hash value and the key. Hash-and-sign algorithms encode the hash |
1711 | | * used for the hashing step, and you can call #PSA_ALG_SIGN_GET_HASH |
1712 | | * to extract this algorithm. |
1713 | | * |
1714 | | * Thus, for a hash-and-sign algorithm, |
1715 | | * `psa_sign_message(key, alg, input, ...)` is equivalent to |
1716 | | * ``` |
1717 | | * psa_hash_compute(PSA_ALG_SIGN_GET_HASH(alg), input, ..., hash, ...); |
1718 | | * psa_sign_hash(key, alg, hash, ..., signature, ...); |
1719 | | * ``` |
1720 | | * Most usefully, separating the hash from the signature allows the hash |
1721 | | * to be calculated in multiple steps with psa_hash_setup(), psa_hash_update() |
1722 | | * and psa_hash_finish(). Likewise psa_verify_message() is equivalent to |
1723 | | * calculating the hash and then calling psa_verify_hash(). |
1724 | | * |
1725 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1726 | | * |
1727 | | * \return 1 if \p alg is a hash-and-sign algorithm, 0 otherwise. |
1728 | | * This macro may return either 0 or 1 if \p alg is not a supported |
1729 | | * algorithm identifier. |
1730 | | */ |
1731 | | #define PSA_ALG_IS_HASH_AND_SIGN(alg) \ |
1732 | 0 | (PSA_ALG_IS_SIGN_HASH(alg) && \ |
1733 | 0 | ((alg) & PSA_ALG_HASH_MASK) != 0) |
1734 | | |
1735 | | /** Get the hash used by a hash-and-sign signature algorithm. |
1736 | | * |
1737 | | * A hash-and-sign algorithm is a signature algorithm which is |
1738 | | * composed of two phases: first a hashing phase which does not use |
1739 | | * the key and produces a hash of the input message, then a signing |
1740 | | * phase which only uses the hash and the key and not the message |
1741 | | * itself. |
1742 | | * |
1743 | | * \param alg A signature algorithm (\c PSA_ALG_XXX value such that |
1744 | | * #PSA_ALG_IS_SIGN(\p alg) is true). |
1745 | | * |
1746 | | * \return The underlying hash algorithm if \p alg is a hash-and-sign |
1747 | | * algorithm. |
1748 | | * \return 0 if \p alg is a signature algorithm that does not |
1749 | | * follow the hash-and-sign structure. |
1750 | | * \return Unspecified if \p alg is not a signature algorithm or |
1751 | | * if it is not supported by the implementation. |
1752 | | */ |
1753 | | #define PSA_ALG_SIGN_GET_HASH(alg) \ |
1754 | 0 | (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ |
1755 | 0 | ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ |
1756 | 0 | 0) |
1757 | | |
1758 | | /** RSA PKCS#1 v1.5 encryption. |
1759 | | * |
1760 | | * \warning Calling psa_asymmetric_decrypt() with this algorithm as a |
1761 | | * parameter is considered an inherently dangerous function |
1762 | | * (CWE-242). Unless it is used in a side channel free and safe |
1763 | | * way (eg. implementing the TLS protocol as per 7.4.7.1 of |
1764 | | * RFC 5246), the calling code is vulnerable. |
1765 | | * |
1766 | | */ |
1767 | 0 | #define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t) 0x07000200) |
1768 | | |
1769 | 0 | #define PSA_ALG_RSA_OAEP_BASE ((psa_algorithm_t) 0x07000300) |
1770 | | /** RSA OAEP encryption. |
1771 | | * |
1772 | | * This is the encryption scheme defined by RFC 8017 |
1773 | | * (PKCS#1: RSA Cryptography Specifications) under the name |
1774 | | * RSAES-OAEP, with the message generation function MGF1. |
1775 | | * |
1776 | | * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that |
1777 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true) to use |
1778 | | * for MGF1. |
1779 | | * |
1780 | | * \return The corresponding RSA OAEP encryption algorithm. |
1781 | | * \return Unspecified if \p hash_alg is not a supported |
1782 | | * hash algorithm. |
1783 | | */ |
1784 | | #define PSA_ALG_RSA_OAEP(hash_alg) \ |
1785 | 0 | (PSA_ALG_RSA_OAEP_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1786 | | #define PSA_ALG_IS_RSA_OAEP(alg) \ |
1787 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_BASE) |
1788 | | #define PSA_ALG_RSA_OAEP_GET_HASH(alg) \ |
1789 | 0 | (PSA_ALG_IS_RSA_OAEP(alg) ? \ |
1790 | 0 | ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ |
1791 | 0 | 0) |
1792 | | |
1793 | 0 | #define PSA_ALG_HKDF_BASE ((psa_algorithm_t) 0x08000100) |
1794 | | /** Macro to build an HKDF algorithm. |
1795 | | * |
1796 | | * For example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)` is HKDF using HMAC-SHA-256. |
1797 | | * |
1798 | | * This key derivation algorithm uses the following inputs: |
1799 | | * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step. |
1800 | | * It is optional; if omitted, the derivation uses an empty salt. |
1801 | | * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step. |
1802 | | * - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step. |
1803 | | * You must pass #PSA_KEY_DERIVATION_INPUT_SALT before #PSA_KEY_DERIVATION_INPUT_SECRET. |
1804 | | * You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before |
1805 | | * starting to generate output. |
1806 | | * |
1807 | | * \warning HKDF processes the salt as follows: first hash it with hash_alg |
1808 | | * if the salt is longer than the block size of the hash algorithm; then |
1809 | | * pad with null bytes up to the block size. As a result, it is possible |
1810 | | * for distinct salt inputs to result in the same outputs. To ensure |
1811 | | * unique outputs, it is recommended to use a fixed length for salt values. |
1812 | | * |
1813 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1814 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1815 | | * |
1816 | | * \return The corresponding HKDF algorithm. |
1817 | | * \return Unspecified if \p hash_alg is not a supported |
1818 | | * hash algorithm. |
1819 | | */ |
1820 | | #define PSA_ALG_HKDF(hash_alg) \ |
1821 | | (PSA_ALG_HKDF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1822 | | /** Whether the specified algorithm is an HKDF algorithm. |
1823 | | * |
1824 | | * HKDF is a family of key derivation algorithms that are based on a hash |
1825 | | * function and the HMAC construction. |
1826 | | * |
1827 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1828 | | * |
1829 | | * \return 1 if \c alg is an HKDF algorithm, 0 otherwise. |
1830 | | * This macro may return either 0 or 1 if \c alg is not a supported |
1831 | | * key derivation algorithm identifier. |
1832 | | */ |
1833 | | #define PSA_ALG_IS_HKDF(alg) \ |
1834 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE) |
1835 | | #define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \ |
1836 | 0 | (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) |
1837 | | |
1838 | 0 | #define PSA_ALG_HKDF_EXTRACT_BASE ((psa_algorithm_t) 0x08000400) |
1839 | | /** Macro to build an HKDF-Extract algorithm. |
1840 | | * |
1841 | | * For example, `PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA_256)` is |
1842 | | * HKDF-Extract using HMAC-SHA-256. |
1843 | | * |
1844 | | * This key derivation algorithm uses the following inputs: |
1845 | | * - PSA_KEY_DERIVATION_INPUT_SALT is the salt. |
1846 | | * - PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the |
1847 | | * "extract" step. |
1848 | | * The inputs are mandatory and must be passed in the order above. |
1849 | | * Each input may only be passed once. |
1850 | | * |
1851 | | * \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF |
1852 | | * should be used instead if possible. PSA_ALG_HKDF_EXTRACT is provided |
1853 | | * as a separate algorithm for the sake of protocols that use it as a |
1854 | | * building block. It may also be a slight performance optimization |
1855 | | * in applications that use HKDF with the same salt and key but many |
1856 | | * different info strings. |
1857 | | * |
1858 | | * \warning HKDF processes the salt as follows: first hash it with hash_alg |
1859 | | * if the salt is longer than the block size of the hash algorithm; then |
1860 | | * pad with null bytes up to the block size. As a result, it is possible |
1861 | | * for distinct salt inputs to result in the same outputs. To ensure |
1862 | | * unique outputs, it is recommended to use a fixed length for salt values. |
1863 | | * |
1864 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1865 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1866 | | * |
1867 | | * \return The corresponding HKDF-Extract algorithm. |
1868 | | * \return Unspecified if \p hash_alg is not a supported |
1869 | | * hash algorithm. |
1870 | | */ |
1871 | | #define PSA_ALG_HKDF_EXTRACT(hash_alg) \ |
1872 | | (PSA_ALG_HKDF_EXTRACT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1873 | | /** Whether the specified algorithm is an HKDF-Extract algorithm. |
1874 | | * |
1875 | | * HKDF-Extract is a family of key derivation algorithms that are based |
1876 | | * on a hash function and the HMAC construction. |
1877 | | * |
1878 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1879 | | * |
1880 | | * \return 1 if \c alg is an HKDF-Extract algorithm, 0 otherwise. |
1881 | | * This macro may return either 0 or 1 if \c alg is not a supported |
1882 | | * key derivation algorithm identifier. |
1883 | | */ |
1884 | | #define PSA_ALG_IS_HKDF_EXTRACT(alg) \ |
1885 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE) |
1886 | | |
1887 | 0 | #define PSA_ALG_HKDF_EXPAND_BASE ((psa_algorithm_t) 0x08000500) |
1888 | | /** Macro to build an HKDF-Expand algorithm. |
1889 | | * |
1890 | | * For example, `PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA_256)` is |
1891 | | * HKDF-Expand using HMAC-SHA-256. |
1892 | | * |
1893 | | * This key derivation algorithm uses the following inputs: |
1894 | | * - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK). |
1895 | | * - PSA_KEY_DERIVATION_INPUT_INFO is the info string. |
1896 | | * |
1897 | | * The inputs are mandatory and must be passed in the order above. |
1898 | | * Each input may only be passed once. |
1899 | | * |
1900 | | * \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF` |
1901 | | * should be used instead if possible. `PSA_ALG_HKDF_EXPAND` is provided as |
1902 | | * a separate algorithm for the sake of protocols that use it as a building |
1903 | | * block. It may also be a slight performance optimization in applications |
1904 | | * that use HKDF with the same salt and key but many different info strings. |
1905 | | * |
1906 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1907 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1908 | | * |
1909 | | * \return The corresponding HKDF-Expand algorithm. |
1910 | | * \return Unspecified if \p hash_alg is not a supported |
1911 | | * hash algorithm. |
1912 | | */ |
1913 | | #define PSA_ALG_HKDF_EXPAND(hash_alg) \ |
1914 | | (PSA_ALG_HKDF_EXPAND_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1915 | | /** Whether the specified algorithm is an HKDF-Expand algorithm. |
1916 | | * |
1917 | | * HKDF-Expand is a family of key derivation algorithms that are based |
1918 | | * on a hash function and the HMAC construction. |
1919 | | * |
1920 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1921 | | * |
1922 | | * \return 1 if \c alg is an HKDF-Expand algorithm, 0 otherwise. |
1923 | | * This macro may return either 0 or 1 if \c alg is not a supported |
1924 | | * key derivation algorithm identifier. |
1925 | | */ |
1926 | | #define PSA_ALG_IS_HKDF_EXPAND(alg) \ |
1927 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE) |
1928 | | |
1929 | | /** Whether the specified algorithm is an HKDF or HKDF-Extract or |
1930 | | * HKDF-Expand algorithm. |
1931 | | * |
1932 | | * |
1933 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1934 | | * |
1935 | | * \return 1 if \c alg is any HKDF type algorithm, 0 otherwise. |
1936 | | * This macro may return either 0 or 1 if \c alg is not a supported |
1937 | | * key derivation algorithm identifier. |
1938 | | */ |
1939 | | #define PSA_ALG_IS_ANY_HKDF(alg) \ |
1940 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE || \ |
1941 | 0 | ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE || \ |
1942 | 0 | ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE) |
1943 | | |
1944 | 0 | #define PSA_ALG_TLS12_PRF_BASE ((psa_algorithm_t) 0x08000200) |
1945 | | /** Macro to build a TLS-1.2 PRF algorithm. |
1946 | | * |
1947 | | * TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, |
1948 | | * specified in Section 5 of RFC 5246. It is based on HMAC and can be |
1949 | | * used with either SHA-256 or SHA-384. |
1950 | | * |
1951 | | * This key derivation algorithm uses the following inputs, which must be |
1952 | | * passed in the order given here: |
1953 | | * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. |
1954 | | * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. |
1955 | | * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. |
1956 | | * |
1957 | | * For the application to TLS-1.2 key expansion, the seed is the |
1958 | | * concatenation of ServerHello.Random + ClientHello.Random, |
1959 | | * and the label is "key expansion". |
1960 | | * |
1961 | | * For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA_256)` represents the |
1962 | | * TLS 1.2 PRF using HMAC-SHA-256. |
1963 | | * |
1964 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
1965 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
1966 | | * |
1967 | | * \return The corresponding TLS-1.2 PRF algorithm. |
1968 | | * \return Unspecified if \p hash_alg is not a supported |
1969 | | * hash algorithm. |
1970 | | */ |
1971 | | #define PSA_ALG_TLS12_PRF(hash_alg) \ |
1972 | | (PSA_ALG_TLS12_PRF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
1973 | | |
1974 | | /** Whether the specified algorithm is a TLS-1.2 PRF algorithm. |
1975 | | * |
1976 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
1977 | | * |
1978 | | * \return 1 if \c alg is a TLS-1.2 PRF algorithm, 0 otherwise. |
1979 | | * This macro may return either 0 or 1 if \c alg is not a supported |
1980 | | * key derivation algorithm identifier. |
1981 | | */ |
1982 | | #define PSA_ALG_IS_TLS12_PRF(alg) \ |
1983 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PRF_BASE) |
1984 | | #define PSA_ALG_TLS12_PRF_GET_HASH(hkdf_alg) \ |
1985 | 0 | (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) |
1986 | | |
1987 | 0 | #define PSA_ALG_TLS12_PSK_TO_MS_BASE ((psa_algorithm_t) 0x08000300) |
1988 | | /** Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm. |
1989 | | * |
1990 | | * In a pure-PSK handshake in TLS 1.2, the master secret is derived |
1991 | | * from the PreSharedKey (PSK) through the application of padding |
1992 | | * (RFC 4279, Section 2) and the TLS-1.2 PRF (RFC 5246, Section 5). |
1993 | | * The latter is based on HMAC and can be used with either SHA-256 |
1994 | | * or SHA-384. |
1995 | | * |
1996 | | * This key derivation algorithm uses the following inputs, which must be |
1997 | | * passed in the order given here: |
1998 | | * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. |
1999 | | * - #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the |
2000 | | * computation of the premaster secret. This input is optional; |
2001 | | * if omitted, it defaults to a string of null bytes with the same length |
2002 | | * as the secret (PSK) input. |
2003 | | * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. |
2004 | | * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. |
2005 | | * |
2006 | | * For the application to TLS-1.2, the seed (which is |
2007 | | * forwarded to the TLS-1.2 PRF) is the concatenation of the |
2008 | | * ClientHello.Random + ServerHello.Random, |
2009 | | * the label is "master secret" or "extended master secret" and |
2010 | | * the other secret depends on the key exchange specified in the cipher suite: |
2011 | | * - for a plain PSK cipher suite (RFC 4279, Section 2), omit |
2012 | | * PSA_KEY_DERIVATION_INPUT_OTHER_SECRET |
2013 | | * - for a DHE-PSK (RFC 4279, Section 3) or ECDHE-PSK cipher suite |
2014 | | * (RFC 5489, Section 2), the other secret should be the output of the |
2015 | | * PSA_ALG_FFDH or PSA_ALG_ECDH key agreement performed with the peer. |
2016 | | * The recommended way to pass this input is to use a key derivation |
2017 | | * algorithm constructed as |
2018 | | * PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg)) |
2019 | | * and to call psa_key_derivation_key_agreement(). Alternatively, |
2020 | | * this input may be an output of `psa_raw_key_agreement()` passed with |
2021 | | * psa_key_derivation_input_bytes(), or an equivalent input passed with |
2022 | | * psa_key_derivation_input_bytes() or psa_key_derivation_input_key(). |
2023 | | * - for a RSA-PSK cipher suite (RFC 4279, Section 4), the other secret |
2024 | | * should be the 48-byte client challenge (the PreMasterSecret of |
2025 | | * (RFC 5246, Section 7.4.7.1)) concatenation of the TLS version and |
2026 | | * a 46-byte random string chosen by the client. On the server, this is |
2027 | | * typically an output of psa_asymmetric_decrypt() using |
2028 | | * PSA_ALG_RSA_PKCS1V15_CRYPT, passed to the key derivation operation |
2029 | | * with `psa_key_derivation_input_bytes()`. |
2030 | | * |
2031 | | * For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA_256)` represents the |
2032 | | * TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256. |
2033 | | * |
2034 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
2035 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
2036 | | * |
2037 | | * \return The corresponding TLS-1.2 PSK to MS algorithm. |
2038 | | * \return Unspecified if \p hash_alg is not a supported |
2039 | | * hash algorithm. |
2040 | | */ |
2041 | | #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) \ |
2042 | | (PSA_ALG_TLS12_PSK_TO_MS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
2043 | | |
2044 | | /** Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm. |
2045 | | * |
2046 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2047 | | * |
2048 | | * \return 1 if \c alg is a TLS-1.2 PSK to MS algorithm, 0 otherwise. |
2049 | | * This macro may return either 0 or 1 if \c alg is not a supported |
2050 | | * key derivation algorithm identifier. |
2051 | | */ |
2052 | | #define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) \ |
2053 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PSK_TO_MS_BASE) |
2054 | | #define PSA_ALG_TLS12_PSK_TO_MS_GET_HASH(hkdf_alg) \ |
2055 | | (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) |
2056 | | |
2057 | | /* The TLS 1.2 ECJPAKE-to-PMS KDF. It takes the shared secret K (an EC point |
2058 | | * in case of EC J-PAKE) and calculates SHA256(K.X) that the rest of TLS 1.2 |
2059 | | * will use to derive the session secret, as defined by step 2 of |
2060 | | * https://datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01#section-8.7. |
2061 | | * Uses PSA_ALG_SHA_256. |
2062 | | * This function takes a single input: |
2063 | | * #PSA_KEY_DERIVATION_INPUT_SECRET is the shared secret K from EC J-PAKE. |
2064 | | * The only supported curve is secp256r1 (the 256-bit curve in |
2065 | | * #PSA_ECC_FAMILY_SECP_R1), so the input must be exactly 65 bytes. |
2066 | | * The output has to be read as a single chunk of 32 bytes, defined as |
2067 | | * PSA_TLS12_ECJPAKE_TO_PMS_DATA_SIZE. |
2068 | | */ |
2069 | 0 | #define PSA_ALG_TLS12_ECJPAKE_TO_PMS ((psa_algorithm_t) 0x08000609) |
2070 | | |
2071 | | /* This flag indicates whether the key derivation algorithm is suitable for |
2072 | | * use on low-entropy secrets such as password - these algorithms are also |
2073 | | * known as key stretching or password hashing schemes. These are also the |
2074 | | * algorithms that accepts inputs of type #PSA_KEY_DERIVATION_INPUT_PASSWORD. |
2075 | | * |
2076 | | * Those algorithms cannot be combined with a key agreement algorithm. |
2077 | | */ |
2078 | | #define PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG ((psa_algorithm_t) 0x00800000) |
2079 | | |
2080 | 0 | #define PSA_ALG_PBKDF2_HMAC_BASE ((psa_algorithm_t) 0x08800100) |
2081 | | /** Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm. |
2082 | | * |
2083 | | * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). |
2084 | | * This macro specifies the PBKDF2 algorithm constructed using a PRF based on |
2085 | | * HMAC with the specified hash. |
2086 | | * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256)` specifies PBKDF2 |
2087 | | * using the PRF HMAC-SHA-256. |
2088 | | * |
2089 | | * This key derivation algorithm uses the following inputs, which must be |
2090 | | * provided in the following order: |
2091 | | * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count. |
2092 | | * This input step must be used exactly once. |
2093 | | * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt. |
2094 | | * This input step must be used one or more times; if used several times, the |
2095 | | * inputs will be concatenated. This can be used to build the final salt |
2096 | | * from multiple sources, both public and secret (also known as pepper). |
2097 | | * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed. |
2098 | | * This input step must be used exactly once. |
2099 | | * |
2100 | | * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that |
2101 | | * #PSA_ALG_IS_HASH(\p hash_alg) is true). |
2102 | | * |
2103 | | * \return The corresponding PBKDF2-HMAC-XXX algorithm. |
2104 | | * \return Unspecified if \p hash_alg is not a supported |
2105 | | * hash algorithm. |
2106 | | */ |
2107 | | #define PSA_ALG_PBKDF2_HMAC(hash_alg) \ |
2108 | | (PSA_ALG_PBKDF2_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) |
2109 | | |
2110 | | /** Whether the specified algorithm is a PBKDF2-HMAC algorithm. |
2111 | | * |
2112 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2113 | | * |
2114 | | * \return 1 if \c alg is a PBKDF2-HMAC algorithm, 0 otherwise. |
2115 | | * This macro may return either 0 or 1 if \c alg is not a supported |
2116 | | * key derivation algorithm identifier. |
2117 | | */ |
2118 | | #define PSA_ALG_IS_PBKDF2_HMAC(alg) \ |
2119 | 0 | (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_PBKDF2_HMAC_BASE) |
2120 | | #define PSA_ALG_PBKDF2_HMAC_GET_HASH(pbkdf2_alg) \ |
2121 | 0 | (PSA_ALG_CATEGORY_HASH | ((pbkdf2_alg) & PSA_ALG_HASH_MASK)) |
2122 | | /** The PBKDF2-AES-CMAC-PRF-128 password hashing / key stretching algorithm. |
2123 | | * |
2124 | | * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2). |
2125 | | * This macro specifies the PBKDF2 algorithm constructed using the |
2126 | | * AES-CMAC-PRF-128 PRF specified by RFC 4615. |
2127 | | * |
2128 | | * This key derivation algorithm uses the same inputs as |
2129 | | * #PSA_ALG_PBKDF2_HMAC() with the same constraints. |
2130 | | */ |
2131 | 0 | #define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t) 0x08800200) |
2132 | | |
2133 | | #define PSA_ALG_IS_PBKDF2(kdf_alg) \ |
2134 | 0 | (PSA_ALG_IS_PBKDF2_HMAC(kdf_alg) || \ |
2135 | 0 | ((kdf_alg) == PSA_ALG_PBKDF2_AES_CMAC_PRF_128)) |
2136 | | |
2137 | 0 | #define PSA_ALG_KEY_DERIVATION_MASK ((psa_algorithm_t) 0xfe00ffff) |
2138 | 0 | #define PSA_ALG_KEY_AGREEMENT_MASK ((psa_algorithm_t) 0xffff0000) |
2139 | | |
2140 | | /** Macro to build a combined algorithm that chains a key agreement with |
2141 | | * a key derivation. |
2142 | | * |
2143 | | * \param ka_alg A key agreement algorithm (\c PSA_ALG_XXX value such |
2144 | | * that #PSA_ALG_IS_KEY_AGREEMENT(\p ka_alg) is true). |
2145 | | * \param kdf_alg A key derivation algorithm (\c PSA_ALG_XXX value such |
2146 | | * that #PSA_ALG_IS_KEY_DERIVATION(\p kdf_alg) is true). |
2147 | | * |
2148 | | * \return The corresponding key agreement and derivation |
2149 | | * algorithm. |
2150 | | * \return Unspecified if \p ka_alg is not a supported |
2151 | | * key agreement algorithm or \p kdf_alg is not a |
2152 | | * supported key derivation algorithm. |
2153 | | */ |
2154 | | #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ |
2155 | | ((ka_alg) | (kdf_alg)) |
2156 | | |
2157 | | #define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) \ |
2158 | 0 | (((alg) & PSA_ALG_KEY_DERIVATION_MASK) | PSA_ALG_CATEGORY_KEY_DERIVATION) |
2159 | | |
2160 | | #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \ |
2161 | 0 | (((alg) & PSA_ALG_KEY_AGREEMENT_MASK) | PSA_ALG_CATEGORY_KEY_AGREEMENT) |
2162 | | |
2163 | | /** Whether the specified algorithm is a raw key agreement algorithm. |
2164 | | * |
2165 | | * A raw key agreement algorithm is one that does not specify |
2166 | | * a key derivation function. |
2167 | | * Usually, raw key agreement algorithms are constructed directly with |
2168 | | * a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are |
2169 | | * constructed with #PSA_ALG_KEY_AGREEMENT(). |
2170 | | * |
2171 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2172 | | * |
2173 | | * \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise. |
2174 | | * This macro may return either 0 or 1 if \p alg is not a supported |
2175 | | * algorithm identifier. |
2176 | | */ |
2177 | | #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ |
2178 | 0 | (PSA_ALG_IS_KEY_AGREEMENT(alg) && \ |
2179 | 0 | PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION) |
2180 | | |
2181 | | #define PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT(alg) \ |
2182 | | ((PSA_ALG_IS_KEY_DERIVATION(alg) || PSA_ALG_IS_KEY_AGREEMENT(alg))) |
2183 | | |
2184 | | /** The finite-field Diffie-Hellman (DH) key agreement algorithm. |
2185 | | * |
2186 | | * The shared secret produced by key agreement is |
2187 | | * `g^{ab}` in big-endian format. |
2188 | | * It is `ceiling(m / 8)` bytes long where `m` is the size of the prime `p` |
2189 | | * in bits. |
2190 | | */ |
2191 | 0 | #define PSA_ALG_FFDH ((psa_algorithm_t) 0x09010000) |
2192 | | |
2193 | | /** Whether the specified algorithm is a finite field Diffie-Hellman algorithm. |
2194 | | * |
2195 | | * This includes the raw finite field Diffie-Hellman algorithm as well as |
2196 | | * finite-field Diffie-Hellman followed by any supporter key derivation |
2197 | | * algorithm. |
2198 | | * |
2199 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2200 | | * |
2201 | | * \return 1 if \c alg is a finite field Diffie-Hellman algorithm, 0 otherwise. |
2202 | | * This macro may return either 0 or 1 if \c alg is not a supported |
2203 | | * key agreement algorithm identifier. |
2204 | | */ |
2205 | | #define PSA_ALG_IS_FFDH(alg) \ |
2206 | | (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_FFDH) |
2207 | | |
2208 | | /** The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm. |
2209 | | * |
2210 | | * The shared secret produced by key agreement is the x-coordinate of |
2211 | | * the shared secret point. It is always `ceiling(m / 8)` bytes long where |
2212 | | * `m` is the bit size associated with the curve, i.e. the bit size of the |
2213 | | * order of the curve's coordinate field. When `m` is not a multiple of 8, |
2214 | | * the byte containing the most significant bit of the shared secret |
2215 | | * is padded with zero bits. The byte order is either little-endian |
2216 | | * or big-endian depending on the curve type. |
2217 | | * |
2218 | | * - For Montgomery curves (curve types `PSA_ECC_FAMILY_CURVEXXX`), |
2219 | | * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` |
2220 | | * in little-endian byte order. |
2221 | | * The bit size is 448 for Curve448 and 255 for Curve25519. |
2222 | | * - For Weierstrass curves over prime fields (curve types |
2223 | | * `PSA_ECC_FAMILY_SECPXXX` and `PSA_ECC_FAMILY_BRAINPOOL_PXXX`), |
2224 | | * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` |
2225 | | * in big-endian byte order. |
2226 | | * The bit size is `m = ceiling(log_2(p))` for the field `F_p`. |
2227 | | * - For Weierstrass curves over binary fields (curve types |
2228 | | * `PSA_ECC_FAMILY_SECTXXX`), |
2229 | | * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` |
2230 | | * in big-endian byte order. |
2231 | | * The bit size is `m` for the field `F_{2^m}`. |
2232 | | */ |
2233 | 0 | #define PSA_ALG_ECDH ((psa_algorithm_t) 0x09020000) |
2234 | | |
2235 | | /** Whether the specified algorithm is an elliptic curve Diffie-Hellman |
2236 | | * algorithm. |
2237 | | * |
2238 | | * This includes the raw elliptic curve Diffie-Hellman algorithm as well as |
2239 | | * elliptic curve Diffie-Hellman followed by any supporter key derivation |
2240 | | * algorithm. |
2241 | | * |
2242 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2243 | | * |
2244 | | * \return 1 if \c alg is an elliptic curve Diffie-Hellman algorithm, |
2245 | | * 0 otherwise. |
2246 | | * This macro may return either 0 or 1 if \c alg is not a supported |
2247 | | * key agreement algorithm identifier. |
2248 | | */ |
2249 | | #define PSA_ALG_IS_ECDH(alg) \ |
2250 | 0 | (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_ECDH) |
2251 | | |
2252 | | /** Whether the specified algorithm encoding is a wildcard. |
2253 | | * |
2254 | | * Wildcard values may only be used to set the usage algorithm field in |
2255 | | * a policy, not to perform an operation. |
2256 | | * |
2257 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2258 | | * |
2259 | | * \return 1 if \c alg is a wildcard algorithm encoding. |
2260 | | * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for |
2261 | | * an operation). |
2262 | | * \return This macro may return either 0 or 1 if \c alg is not a supported |
2263 | | * algorithm identifier. |
2264 | | */ |
2265 | | #define PSA_ALG_IS_WILDCARD(alg) \ |
2266 | 0 | (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ |
2267 | 0 | PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \ |
2268 | 0 | PSA_ALG_IS_MAC(alg) ? \ |
2269 | 0 | (alg & PSA_ALG_MAC_AT_LEAST_THIS_LENGTH_FLAG) != 0 : \ |
2270 | 0 | PSA_ALG_IS_AEAD(alg) ? \ |
2271 | 0 | (alg & PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG) != 0 : \ |
2272 | 0 | (alg) == PSA_ALG_ANY_HASH) |
2273 | | |
2274 | | /** Get the hash used by a composite algorithm. |
2275 | | * |
2276 | | * \param alg An algorithm identifier (value of type #psa_algorithm_t). |
2277 | | * |
2278 | | * \return The underlying hash algorithm if alg is a composite algorithm that |
2279 | | * uses a hash algorithm. |
2280 | | * |
2281 | | * \return \c 0 if alg is not a composite algorithm that uses a hash. |
2282 | | */ |
2283 | | #define PSA_ALG_GET_HASH(alg) \ |
2284 | 0 | (((alg) & 0x000000ff) == 0 ? ((psa_algorithm_t) 0) : 0x02000000 | ((alg) & 0x000000ff)) |
2285 | | |
2286 | | /**@}*/ |
2287 | | |
2288 | | /** \defgroup key_lifetimes Key lifetimes |
2289 | | * @{ |
2290 | | */ |
2291 | | |
2292 | | /* Note that location and persistence level values are embedded in the |
2293 | | * persistent key store, as part of key metadata. As a consequence, they |
2294 | | * must not be changed (unless the storage format version changes). |
2295 | | */ |
2296 | | |
2297 | | /** The default lifetime for volatile keys. |
2298 | | * |
2299 | | * A volatile key only exists as long as the identifier to it is not destroyed. |
2300 | | * The key material is guaranteed to be erased on a power reset. |
2301 | | * |
2302 | | * A key with this lifetime is typically stored in the RAM area of the |
2303 | | * PSA Crypto subsystem. However this is an implementation choice. |
2304 | | * If an implementation stores data about the key in a non-volatile memory, |
2305 | | * it must release all the resources associated with the key and erase the |
2306 | | * key material if the calling application terminates. |
2307 | | */ |
2308 | 0 | #define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t) 0x00000000) |
2309 | | |
2310 | | /** The default lifetime for persistent keys. |
2311 | | * |
2312 | | * A persistent key remains in storage until it is explicitly destroyed or |
2313 | | * until the corresponding storage area is wiped. This specification does |
2314 | | * not define any mechanism to wipe a storage area, but integrations may |
2315 | | * provide their own mechanism (for example to perform a factory reset, |
2316 | | * to prepare for device refurbishment, or to uninstall an application). |
2317 | | * |
2318 | | * This lifetime value is the default storage area for the calling |
2319 | | * application. Integrations of Mbed TLS may support other persistent lifetimes. |
2320 | | * See ::psa_key_lifetime_t for more information. |
2321 | | */ |
2322 | 0 | #define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t) 0x00000001) |
2323 | | |
2324 | | /** The persistence level of volatile keys. |
2325 | | * |
2326 | | * See ::psa_key_persistence_t for more information. |
2327 | | */ |
2328 | 0 | #define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t) 0x00) |
2329 | | |
2330 | | /** The default persistence level for persistent keys. |
2331 | | * |
2332 | | * See ::psa_key_persistence_t for more information. |
2333 | | */ |
2334 | | #define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t) 0x01) |
2335 | | |
2336 | | /** A persistence level indicating that a key is never destroyed. |
2337 | | * |
2338 | | * See ::psa_key_persistence_t for more information. |
2339 | | */ |
2340 | 0 | #define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t) 0xff) |
2341 | | |
2342 | | #define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \ |
2343 | 0 | ((psa_key_persistence_t) ((lifetime) & 0x000000ff)) |
2344 | | |
2345 | | #define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \ |
2346 | 0 | ((psa_key_location_t) ((lifetime) >> 8)) |
2347 | | |
2348 | | /** Whether a key lifetime indicates that the key is volatile. |
2349 | | * |
2350 | | * A volatile key is automatically destroyed by the implementation when |
2351 | | * the application instance terminates. In particular, a volatile key |
2352 | | * is automatically destroyed on a power reset of the device. |
2353 | | * |
2354 | | * A key that is not volatile is persistent. Persistent keys are |
2355 | | * preserved until the application explicitly destroys them or until an |
2356 | | * implementation-specific device management event occurs (for example, |
2357 | | * a factory reset). |
2358 | | * |
2359 | | * \param lifetime The lifetime value to query (value of type |
2360 | | * ::psa_key_lifetime_t). |
2361 | | * |
2362 | | * \return \c 1 if the key is volatile, otherwise \c 0. |
2363 | | */ |
2364 | | #define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \ |
2365 | 0 | (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \ |
2366 | 0 | PSA_KEY_PERSISTENCE_VOLATILE) |
2367 | | |
2368 | | /** Whether a key lifetime indicates that the key is read-only. |
2369 | | * |
2370 | | * Read-only keys cannot be created or destroyed through the PSA Crypto API. |
2371 | | * They must be created through platform-specific means that bypass the API. |
2372 | | * |
2373 | | * Some platforms may offer ways to destroy read-only keys. For example, |
2374 | | * consider a platform with multiple levels of privilege, where a |
2375 | | * low-privilege application can use a key but is not allowed to destroy |
2376 | | * it, and the platform exposes the key to the application with a read-only |
2377 | | * lifetime. High-privilege code can destroy the key even though the |
2378 | | * application sees the key as read-only. |
2379 | | * |
2380 | | * \param lifetime The lifetime value to query (value of type |
2381 | | * ::psa_key_lifetime_t). |
2382 | | * |
2383 | | * \return \c 1 if the key is read-only, otherwise \c 0. |
2384 | | */ |
2385 | | #define PSA_KEY_LIFETIME_IS_READ_ONLY(lifetime) \ |
2386 | 0 | (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \ |
2387 | 0 | PSA_KEY_PERSISTENCE_READ_ONLY) |
2388 | | |
2389 | | /** Construct a lifetime from a persistence level and a location. |
2390 | | * |
2391 | | * \param persistence The persistence level |
2392 | | * (value of type ::psa_key_persistence_t). |
2393 | | * \param location The location indicator |
2394 | | * (value of type ::psa_key_location_t). |
2395 | | * |
2396 | | * \return The constructed lifetime value. |
2397 | | */ |
2398 | | #define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \ |
2399 | 0 | ((location) << 8 | (persistence)) |
2400 | | |
2401 | | /** The local storage area for persistent keys. |
2402 | | * |
2403 | | * This storage area is available on all systems that can store persistent |
2404 | | * keys without delegating the storage to a third-party cryptoprocessor. |
2405 | | * |
2406 | | * See ::psa_key_location_t for more information. |
2407 | | */ |
2408 | 0 | #define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t) 0x000000) |
2409 | | |
2410 | | #define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t) 0x800000) |
2411 | | |
2412 | | /* Note that key identifier values are embedded in the |
2413 | | * persistent key store, as part of key metadata. As a consequence, they |
2414 | | * must not be changed (unless the storage format version changes). |
2415 | | */ |
2416 | | |
2417 | | /** The null key identifier. |
2418 | | */ |
2419 | | /* *INDENT-OFF* (https://github.com/ARM-software/psa-arch-tests/issues/337) */ |
2420 | | #define PSA_KEY_ID_NULL ((psa_key_id_t)0) |
2421 | | /* *INDENT-ON* */ |
2422 | | /** The minimum value for a key identifier chosen by the application. |
2423 | | */ |
2424 | 0 | #define PSA_KEY_ID_USER_MIN ((psa_key_id_t) 0x00000001) |
2425 | | /** The maximum value for a key identifier chosen by the application. |
2426 | | */ |
2427 | 0 | #define PSA_KEY_ID_USER_MAX ((psa_key_id_t) 0x3fffffff) |
2428 | | /** The minimum value for a key identifier chosen by the implementation. |
2429 | | */ |
2430 | 0 | #define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t) 0x40000000) |
2431 | | /** The maximum value for a key identifier chosen by the implementation. |
2432 | | */ |
2433 | 0 | #define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t) 0x7fffffff) |
2434 | | |
2435 | | |
2436 | | #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) |
2437 | | |
2438 | 0 | #define MBEDTLS_SVC_KEY_ID_INIT ((psa_key_id_t) 0) |
2439 | 0 | #define MBEDTLS_SVC_KEY_ID_GET_KEY_ID(id) (id) |
2440 | | #define MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(id) (0) |
2441 | | |
2442 | | /** Utility to initialize a key identifier at runtime. |
2443 | | * |
2444 | | * \param unused Unused parameter. |
2445 | | * \param key_id Identifier of the key. |
2446 | | */ |
2447 | | static inline mbedtls_svc_key_id_t mbedtls_svc_key_id_make( |
2448 | | unsigned int unused, psa_key_id_t key_id) |
2449 | 0 | { |
2450 | 0 | (void) unused; |
2451 | 0 |
|
2452 | 0 | return key_id; |
2453 | 0 | } Unexecuted instantiation: fuzz_pkcs7.c:mbedtls_svc_key_id_make Unexecuted instantiation: platform_builtin_keys.c:mbedtls_svc_key_id_make Unexecuted instantiation: helpers.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_helpers.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_stubs.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_exercise_key.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_memory_poisoning_wrappers.c:mbedtls_svc_key_id_make Unexecuted instantiation: certs.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_test_wrappers.c:mbedtls_svc_key_id_make Unexecuted instantiation: pkcs7.c:mbedtls_svc_key_id_make Unexecuted instantiation: x509.c:mbedtls_svc_key_id_make Unexecuted instantiation: x509_crl.c:mbedtls_svc_key_id_make Unexecuted instantiation: x509_crt.c:mbedtls_svc_key_id_make Unexecuted instantiation: md.c:mbedtls_svc_key_id_make Unexecuted instantiation: oid.c:mbedtls_svc_key_id_make Unexecuted instantiation: pem.c:mbedtls_svc_key_id_make Unexecuted instantiation: pk.c:mbedtls_svc_key_id_make Unexecuted instantiation: pk_ecc.c:mbedtls_svc_key_id_make Unexecuted instantiation: pk_wrap.c:mbedtls_svc_key_id_make Unexecuted instantiation: pkparse.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_aead.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_client.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_hash.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_mac.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_pake.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_se.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_slot_management.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_crypto_storage.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_its_file.c:mbedtls_svc_key_id_make Unexecuted instantiation: psa_util.c:mbedtls_svc_key_id_make Unexecuted instantiation: rsa.c:mbedtls_svc_key_id_make Unexecuted instantiation: cipher.c:mbedtls_svc_key_id_make Unexecuted instantiation: cipher_wrap.c:mbedtls_svc_key_id_make Unexecuted instantiation: pkcs12.c:mbedtls_svc_key_id_make Unexecuted instantiation: pkcs5.c:mbedtls_svc_key_id_make |
2454 | | |
2455 | | /** Compare two key identifiers. |
2456 | | * |
2457 | | * \param id1 First key identifier. |
2458 | | * \param id2 Second key identifier. |
2459 | | * |
2460 | | * \return Non-zero if the two key identifier are equal, zero otherwise. |
2461 | | */ |
2462 | | static inline int mbedtls_svc_key_id_equal(mbedtls_svc_key_id_t id1, |
2463 | | mbedtls_svc_key_id_t id2) |
2464 | 0 | { |
2465 | 0 | return id1 == id2; |
2466 | 0 | } Unexecuted instantiation: fuzz_pkcs7.c:mbedtls_svc_key_id_equal Unexecuted instantiation: platform_builtin_keys.c:mbedtls_svc_key_id_equal Unexecuted instantiation: helpers.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_helpers.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_stubs.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_exercise_key.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_memory_poisoning_wrappers.c:mbedtls_svc_key_id_equal Unexecuted instantiation: certs.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_test_wrappers.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pkcs7.c:mbedtls_svc_key_id_equal Unexecuted instantiation: x509.c:mbedtls_svc_key_id_equal Unexecuted instantiation: x509_crl.c:mbedtls_svc_key_id_equal Unexecuted instantiation: x509_crt.c:mbedtls_svc_key_id_equal Unexecuted instantiation: md.c:mbedtls_svc_key_id_equal Unexecuted instantiation: oid.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pem.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pk.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pk_ecc.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pk_wrap.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pkparse.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_aead.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_client.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_hash.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_mac.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_pake.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_se.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_slot_management.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_crypto_storage.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_its_file.c:mbedtls_svc_key_id_equal Unexecuted instantiation: psa_util.c:mbedtls_svc_key_id_equal Unexecuted instantiation: rsa.c:mbedtls_svc_key_id_equal Unexecuted instantiation: cipher.c:mbedtls_svc_key_id_equal Unexecuted instantiation: cipher_wrap.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pkcs12.c:mbedtls_svc_key_id_equal Unexecuted instantiation: pkcs5.c:mbedtls_svc_key_id_equal |
2467 | | |
2468 | | /** Check whether a key identifier is null. |
2469 | | * |
2470 | | * \param key Key identifier. |
2471 | | * |
2472 | | * \return Non-zero if the key identifier is null, zero otherwise. |
2473 | | */ |
2474 | | static inline int mbedtls_svc_key_id_is_null(mbedtls_svc_key_id_t key) |
2475 | 0 | { |
2476 | 0 | return key == 0; |
2477 | 0 | } Unexecuted instantiation: fuzz_pkcs7.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: platform_builtin_keys.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: helpers.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_helpers.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_stubs.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_exercise_key.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_memory_poisoning_wrappers.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: certs.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_test_wrappers.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pkcs7.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: x509.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: x509_crl.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: x509_crt.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: md.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: oid.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pem.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pk.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pk_ecc.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pk_wrap.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pkparse.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_aead.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_cipher.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_client.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_driver_wrappers_no_static.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_ecp.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_ffdh.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_hash.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_mac.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_pake.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_rsa.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_se.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_slot_management.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_crypto_storage.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_its_file.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: psa_util.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: rsa.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: cipher.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: cipher_wrap.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pkcs12.c:mbedtls_svc_key_id_is_null Unexecuted instantiation: pkcs5.c:mbedtls_svc_key_id_is_null |
2478 | | |
2479 | | #else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ |
2480 | | |
2481 | | #define MBEDTLS_SVC_KEY_ID_INIT ((mbedtls_svc_key_id_t){ 0, 0 }) |
2482 | | #define MBEDTLS_SVC_KEY_ID_GET_KEY_ID(id) ((id).MBEDTLS_PRIVATE(key_id)) |
2483 | | #define MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(id) ((id).MBEDTLS_PRIVATE(owner)) |
2484 | | |
2485 | | /** Utility to initialize a key identifier at runtime. |
2486 | | * |
2487 | | * \param owner_id Identifier of the key owner. |
2488 | | * \param key_id Identifier of the key. |
2489 | | */ |
2490 | | static inline mbedtls_svc_key_id_t mbedtls_svc_key_id_make( |
2491 | | mbedtls_key_owner_id_t owner_id, psa_key_id_t key_id) |
2492 | | { |
2493 | | return (mbedtls_svc_key_id_t){ .MBEDTLS_PRIVATE(key_id) = key_id, |
2494 | | .MBEDTLS_PRIVATE(owner) = owner_id }; |
2495 | | } |
2496 | | |
2497 | | /** Compare two key identifiers. |
2498 | | * |
2499 | | * \param id1 First key identifier. |
2500 | | * \param id2 Second key identifier. |
2501 | | * |
2502 | | * \return Non-zero if the two key identifier are equal, zero otherwise. |
2503 | | */ |
2504 | | static inline int mbedtls_svc_key_id_equal(mbedtls_svc_key_id_t id1, |
2505 | | mbedtls_svc_key_id_t id2) |
2506 | | { |
2507 | | return (id1.MBEDTLS_PRIVATE(key_id) == id2.MBEDTLS_PRIVATE(key_id)) && |
2508 | | mbedtls_key_owner_id_equal(id1.MBEDTLS_PRIVATE(owner), id2.MBEDTLS_PRIVATE(owner)); |
2509 | | } |
2510 | | |
2511 | | /** Check whether a key identifier is null. |
2512 | | * |
2513 | | * \param key Key identifier. |
2514 | | * |
2515 | | * \return Non-zero if the key identifier is null, zero otherwise. |
2516 | | */ |
2517 | | static inline int mbedtls_svc_key_id_is_null(mbedtls_svc_key_id_t key) |
2518 | | { |
2519 | | return key.MBEDTLS_PRIVATE(key_id) == 0; |
2520 | | } |
2521 | | |
2522 | | #endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ |
2523 | | |
2524 | | /**@}*/ |
2525 | | |
2526 | | /** \defgroup policy Key policies |
2527 | | * @{ |
2528 | | */ |
2529 | | |
2530 | | /* Note that key usage flags are embedded in the |
2531 | | * persistent key store, as part of key metadata. As a consequence, they |
2532 | | * must not be changed (unless the storage format version changes). |
2533 | | */ |
2534 | | |
2535 | | /** Whether the key may be exported. |
2536 | | * |
2537 | | * A public key or the public part of a key pair may always be exported |
2538 | | * regardless of the value of this permission flag. |
2539 | | * |
2540 | | * If a key does not have export permission, implementations shall not |
2541 | | * allow the key to be exported in plain form from the cryptoprocessor, |
2542 | | * whether through psa_export_key() or through a proprietary interface. |
2543 | | * The key may however be exportable in a wrapped form, i.e. in a form |
2544 | | * where it is encrypted by another key. |
2545 | | */ |
2546 | 0 | #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t) 0x00000001) |
2547 | | |
2548 | | /** Whether the key may be copied. |
2549 | | * |
2550 | | * This flag allows the use of psa_copy_key() to make a copy of the key |
2551 | | * with the same policy or a more restrictive policy. |
2552 | | * |
2553 | | * For lifetimes for which the key is located in a secure element which |
2554 | | * enforce the non-exportability of keys, copying a key outside the secure |
2555 | | * element also requires the usage flag #PSA_KEY_USAGE_EXPORT. |
2556 | | * Copying the key inside the secure element is permitted with just |
2557 | | * #PSA_KEY_USAGE_COPY if the secure element supports it. |
2558 | | * For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or |
2559 | | * #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY |
2560 | | * is sufficient to permit the copy. |
2561 | | */ |
2562 | 0 | #define PSA_KEY_USAGE_COPY ((psa_key_usage_t) 0x00000002) |
2563 | | |
2564 | | /** Whether the key may be used to encrypt a message. |
2565 | | * |
2566 | | * This flag allows the key to be used for a symmetric encryption operation, |
2567 | | * for an AEAD encryption-and-authentication operation, |
2568 | | * or for an asymmetric encryption operation, |
2569 | | * if otherwise permitted by the key's type and policy. |
2570 | | * |
2571 | | * For a key pair, this concerns the public key. |
2572 | | */ |
2573 | 0 | #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t) 0x00000100) |
2574 | | |
2575 | | /** Whether the key may be used to decrypt a message. |
2576 | | * |
2577 | | * This flag allows the key to be used for a symmetric decryption operation, |
2578 | | * for an AEAD decryption-and-verification operation, |
2579 | | * or for an asymmetric decryption operation, |
2580 | | * if otherwise permitted by the key's type and policy. |
2581 | | * |
2582 | | * For a key pair, this concerns the private key. |
2583 | | */ |
2584 | 0 | #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t) 0x00000200) |
2585 | | |
2586 | | /** Whether the key may be used to sign a message. |
2587 | | * |
2588 | | * This flag allows the key to be used for a MAC calculation operation or for |
2589 | | * an asymmetric message signature operation, if otherwise permitted by the |
2590 | | * key’s type and policy. |
2591 | | * |
2592 | | * For a key pair, this concerns the private key. |
2593 | | */ |
2594 | 0 | #define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t) 0x00000400) |
2595 | | |
2596 | | /** Whether the key may be used to verify a message. |
2597 | | * |
2598 | | * This flag allows the key to be used for a MAC verification operation or for |
2599 | | * an asymmetric message signature verification operation, if otherwise |
2600 | | * permitted by the key’s type and policy. |
2601 | | * |
2602 | | * For a key pair, this concerns the public key. |
2603 | | */ |
2604 | 0 | #define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t) 0x00000800) |
2605 | | |
2606 | | /** Whether the key may be used to sign a message. |
2607 | | * |
2608 | | * This flag allows the key to be used for a MAC calculation operation |
2609 | | * or for an asymmetric signature operation, |
2610 | | * if otherwise permitted by the key's type and policy. |
2611 | | * |
2612 | | * For a key pair, this concerns the private key. |
2613 | | */ |
2614 | 0 | #define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t) 0x00001000) |
2615 | | |
2616 | | /** Whether the key may be used to verify a message signature. |
2617 | | * |
2618 | | * This flag allows the key to be used for a MAC verification operation |
2619 | | * or for an asymmetric signature verification operation, |
2620 | | * if otherwise permitted by the key's type and policy. |
2621 | | * |
2622 | | * For a key pair, this concerns the public key. |
2623 | | */ |
2624 | 0 | #define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t) 0x00002000) |
2625 | | |
2626 | | /** Whether the key may be used to derive other keys or produce a password |
2627 | | * hash. |
2628 | | * |
2629 | | * This flag allows the key to be used for a key derivation operation or for |
2630 | | * a key agreement operation, if otherwise permitted by the key's type and |
2631 | | * policy. |
2632 | | * |
2633 | | * If this flag is present on all keys used in calls to |
2634 | | * psa_key_derivation_input_key() for a key derivation operation, then it |
2635 | | * permits calling psa_key_derivation_output_bytes() or |
2636 | | * psa_key_derivation_output_key() at the end of the operation. |
2637 | | */ |
2638 | 0 | #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t) 0x00004000) |
2639 | | |
2640 | | /** Whether the key may be used to verify the result of a key derivation, |
2641 | | * including password hashing. |
2642 | | * |
2643 | | * This flag allows the key to be used: |
2644 | | * |
2645 | | * This flag allows the key to be used in a key derivation operation, if |
2646 | | * otherwise permitted by the key's type and policy. |
2647 | | * |
2648 | | * If this flag is present on all keys used in calls to |
2649 | | * psa_key_derivation_input_key() for a key derivation operation, then it |
2650 | | * permits calling psa_key_derivation_verify_bytes() or |
2651 | | * psa_key_derivation_verify_key() at the end of the operation. |
2652 | | */ |
2653 | 0 | #define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t) 0x00008000) |
2654 | | |
2655 | | /**@}*/ |
2656 | | |
2657 | | /** \defgroup derivation Key derivation |
2658 | | * @{ |
2659 | | */ |
2660 | | |
2661 | | /* Key input steps are not embedded in the persistent storage, so you can |
2662 | | * change them if needed: it's only an ABI change. */ |
2663 | | |
2664 | | /** A secret input for key derivation. |
2665 | | * |
2666 | | * This should be a key of type #PSA_KEY_TYPE_DERIVE |
2667 | | * (passed to psa_key_derivation_input_key()) |
2668 | | * or the shared secret resulting from a key agreement |
2669 | | * (obtained via psa_key_derivation_key_agreement()). |
2670 | | * |
2671 | | * The secret can also be a direct input (passed to |
2672 | | * key_derivation_input_bytes()). In this case, the derivation operation |
2673 | | * may not be used to derive keys: the operation will only allow |
2674 | | * psa_key_derivation_output_bytes(), |
2675 | | * psa_key_derivation_verify_bytes(), or |
2676 | | * psa_key_derivation_verify_key(), but not |
2677 | | * psa_key_derivation_output_key(). |
2678 | | */ |
2679 | 0 | #define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t) 0x0101) |
2680 | | |
2681 | | /** A low-entropy secret input for password hashing / key stretching. |
2682 | | * |
2683 | | * This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to |
2684 | | * psa_key_derivation_input_key()) or a direct input (passed to |
2685 | | * psa_key_derivation_input_bytes()) that is a password or passphrase. It can |
2686 | | * also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or |
2687 | | * the shared secret resulting from a key agreement. |
2688 | | * |
2689 | | * The secret can also be a direct input (passed to |
2690 | | * key_derivation_input_bytes()). In this case, the derivation operation |
2691 | | * may not be used to derive keys: the operation will only allow |
2692 | | * psa_key_derivation_output_bytes(), |
2693 | | * psa_key_derivation_verify_bytes(), or |
2694 | | * psa_key_derivation_verify_key(), but not |
2695 | | * psa_key_derivation_output_key(). |
2696 | | */ |
2697 | 0 | #define PSA_KEY_DERIVATION_INPUT_PASSWORD ((psa_key_derivation_step_t) 0x0102) |
2698 | | |
2699 | | /** A high-entropy additional secret input for key derivation. |
2700 | | * |
2701 | | * This is typically the shared secret resulting from a key agreement obtained |
2702 | | * via `psa_key_derivation_key_agreement()`. It may alternatively be a key of |
2703 | | * type `PSA_KEY_TYPE_DERIVE` passed to `psa_key_derivation_input_key()`, or |
2704 | | * a direct input passed to `psa_key_derivation_input_bytes()`. |
2705 | | */ |
2706 | | #define PSA_KEY_DERIVATION_INPUT_OTHER_SECRET \ |
2707 | 0 | ((psa_key_derivation_step_t) 0x0103) |
2708 | | |
2709 | | /** A label for key derivation. |
2710 | | * |
2711 | | * This should be a direct input. |
2712 | | * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. |
2713 | | */ |
2714 | 0 | #define PSA_KEY_DERIVATION_INPUT_LABEL ((psa_key_derivation_step_t) 0x0201) |
2715 | | |
2716 | | /** A salt for key derivation. |
2717 | | * |
2718 | | * This should be a direct input. |
2719 | | * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA or |
2720 | | * #PSA_KEY_TYPE_PEPPER. |
2721 | | */ |
2722 | 0 | #define PSA_KEY_DERIVATION_INPUT_SALT ((psa_key_derivation_step_t) 0x0202) |
2723 | | |
2724 | | /** An information string for key derivation. |
2725 | | * |
2726 | | * This should be a direct input. |
2727 | | * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. |
2728 | | */ |
2729 | 0 | #define PSA_KEY_DERIVATION_INPUT_INFO ((psa_key_derivation_step_t) 0x0203) |
2730 | | |
2731 | | /** A seed for key derivation. |
2732 | | * |
2733 | | * This should be a direct input. |
2734 | | * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. |
2735 | | */ |
2736 | 0 | #define PSA_KEY_DERIVATION_INPUT_SEED ((psa_key_derivation_step_t) 0x0204) |
2737 | | |
2738 | | /** A cost parameter for password hashing / key stretching. |
2739 | | * |
2740 | | * This must be a direct input, passed to psa_key_derivation_input_integer(). |
2741 | | */ |
2742 | 0 | #define PSA_KEY_DERIVATION_INPUT_COST ((psa_key_derivation_step_t) 0x0205) |
2743 | | |
2744 | | /**@}*/ |
2745 | | |
2746 | | /** \defgroup helper_macros Helper macros |
2747 | | * @{ |
2748 | | */ |
2749 | | |
2750 | | /* Helper macros */ |
2751 | | |
2752 | | /** Check if two AEAD algorithm identifiers refer to the same AEAD algorithm |
2753 | | * regardless of the tag length they encode. |
2754 | | * |
2755 | | * \param aead_alg_1 An AEAD algorithm identifier. |
2756 | | * \param aead_alg_2 An AEAD algorithm identifier. |
2757 | | * |
2758 | | * \return 1 if both identifiers refer to the same AEAD algorithm, |
2759 | | * 0 otherwise. |
2760 | | * Unspecified if neither \p aead_alg_1 nor \p aead_alg_2 are |
2761 | | * a supported AEAD algorithm. |
2762 | | */ |
2763 | | #define MBEDTLS_PSA_ALG_AEAD_EQUAL(aead_alg_1, aead_alg_2) \ |
2764 | 0 | (!(((aead_alg_1) ^ (aead_alg_2)) & \ |
2765 | 0 | ~(PSA_ALG_AEAD_TAG_LENGTH_MASK | PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG))) |
2766 | | |
2767 | | /**@}*/ |
2768 | | |
2769 | | /**@}*/ |
2770 | | |
2771 | | /** \defgroup interruptible Interruptible operations |
2772 | | * @{ |
2773 | | */ |
2774 | | |
2775 | | /** Maximum value for use with \c psa_interruptible_set_max_ops() to determine |
2776 | | * the maximum number of ops allowed to be executed by an interruptible |
2777 | | * function in a single call. |
2778 | | */ |
2779 | | #define PSA_INTERRUPTIBLE_MAX_OPS_UNLIMITED UINT32_MAX |
2780 | | |
2781 | | /**@}*/ |
2782 | | |
2783 | | #endif /* PSA_CRYPTO_VALUES_H */ |