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