Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM/TARGET_TFM_LATEST/include/psa/crypto_sizes.h
1 /*
2  * Copyright (c) 2018-2021, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 /**
8  * \file psa/crypto_sizes.h
9  *
10  * \brief PSA cryptography module: Mbed TLS buffer size macros
11  *
12  * \note This file may not be included directly. Applications must
13  * include psa/crypto.h.
14  *
15  * This file contains the definitions of macros that are useful to
16  * compute buffer sizes. The signatures and semantics of these macros
17  * are standardized, but the definitions are not, because they depend on
18  * the available algorithms and, in some cases, on permitted tolerances
19  * on buffer sizes.
20  *
21  * In implementations with isolation between the application and the
22  * cryptography module, implementers should take care to ensure that
23  * the definitions that are exposed to applications match what the
24  * module implements.
25  *
26  * Macros that compute sizes whose values do not depend on the
27  * implementation are in crypto.h.
28  */
29 
30 #ifndef PSA_CRYPTO_SIZES_H
31 #define PSA_CRYPTO_SIZES_H
32 
33 #define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
34 #define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
35 
36 #define PSA_ROUND_UP_TO_MULTIPLE(block_size, length) \
37  (((length) + (block_size) - 1) / (block_size) * (block_size))
38 
39 /** The size of the output of psa_hash_finish(), in bytes.
40  *
41  * This is also the hash size that psa_hash_verify() expects.
42  *
43  * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
44  * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm
45  * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a
46  * hash algorithm).
47  *
48  * \return The hash size for the specified hash algorithm.
49  * If the hash algorithm is not recognized, return 0.
50  */
51 #define PSA_HASH_LENGTH(alg) \
52  ( \
53  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
54  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
55  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
56  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
57  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
58  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
59  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
60  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
61  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
62  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
63  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
64  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
65  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
66  0)
67 
68 /** \def PSA_HASH_MAX_SIZE
69  *
70  * Maximum size of a hash.
71  *
72  * This macro expands to a compile-time constant integer. This value
73  * is the maximum size of a hash in bytes.
74  */
75 /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
76  * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
77  * HMAC-SHA3-512. */
78 #if defined(MBEDTLS_SHA512_C)
79 #define PSA_HASH_MAX_SIZE 64
80 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
81 #else
82 #define PSA_HASH_MAX_SIZE 32
83 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 64
84 #endif
85 
86 /** \def PSA_MAC_MAX_SIZE
87  *
88  * Maximum size of a MAC.
89  *
90  * This macro expands to a compile-time constant integer. This value
91  * is the maximum size of a MAC in bytes.
92  */
93 /* All non-HMAC MACs have a maximum size that's smaller than the
94  * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
95 /* Note that the encoding of truncated MAC algorithms limits this value
96  * to 64 bytes.
97  */
98 #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
99 
100 /** The length of a tag for an AEAD algorithm, in bytes.
101  *
102  * This macro can be used to allocate a buffer of sufficient size to store the
103  * tag output from psa_aead_finish().
104  *
105  * See also #PSA_AEAD_TAG_MAX_SIZE.
106  *
107  * \param key_type The type of the AEAD key.
108  * \param key_bits The size of the AEAD key in bits.
109  * \param alg An AEAD algorithm
110  * (\c PSA_ALG_XXX value such that
111  * #PSA_ALG_IS_AEAD(\p alg) is true).
112  *
113  * \return The tag length for the specified algorithm and key.
114  * If the AEAD algorithm does not have an identified
115  * tag that can be distinguished from the rest of
116  * the ciphertext, return 0.
117  * If the key type or AEAD algorithm is not
118  * recognized, or the parameters are incompatible,
119  * return 0.
120  */
121 #define PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) \
122  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
123  PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
124  ((void) (key_bits), 0))
125 
126 /** The maximum tag size for all supported AEAD algorithms, in bytes.
127  *
128  * See also #PSA_AEAD_TAG_LENGTH(\p key_type, \p key_bits, \p alg).
129  */
130 #define PSA_AEAD_TAG_MAX_SIZE 16
131 
132 /* The maximum size of an RSA key on this implementation, in bits.
133  * This is a vendor-specific macro.
134  *
135  * Mbed TLS does not set a hard limit on the size of RSA keys: any key
136  * whose parameters fit in a bignum is accepted. However large keys can
137  * induce a large memory usage and long computation times. Unlike other
138  * auxiliary macros in this file and in crypto.h, which reflect how the
139  * library is configured, this macro defines how the library is
140  * configured. This implementation refuses to import or generate an
141  * RSA key whose size is larger than the value defined here.
142  *
143  * Note that an implementation may set different size limits for different
144  * operations, and does not need to accept all key sizes up to the limit. */
145 #define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
146 
147 /* The maximum size of an ECC key on this implementation, in bits */
148 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
149 
150 /** This macro returns the maximum supported length of the PSK for the
151  * TLS-1.2 PSK-to-MS key derivation
152  * (#PSA_ALG_TLS12_PSK_TO_MS(\c hash_alg)).
153  *
154  * The maximum supported length does not depend on the chosen hash algorithm.
155  *
156  * Quoting RFC 4279, Sect 5.3:
157  * TLS implementations supporting these ciphersuites MUST support
158  * arbitrary PSK identities up to 128 octets in length, and arbitrary
159  * PSKs up to 64 octets in length. Supporting longer identities and
160  * keys is RECOMMENDED.
161  *
162  * Therefore, no implementation should define a value smaller than 64
163  * for #PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.
164  */
165 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE 128
166 
167 /** The maximum size of a block cipher. */
168 #define PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE 16
169 
170 /** The size of the output of psa_mac_sign_finish(), in bytes.
171  *
172  * This is also the MAC size that psa_mac_verify_finish() expects.
173  *
174  * \warning This macro may evaluate its arguments multiple times or
175  * zero times, so you should not pass arguments that contain
176  * side effects.
177  *
178  * \param key_type The type of the MAC key.
179  * \param key_bits The size of the MAC key in bits.
180  * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
181  * #PSA_ALG_IS_MAC(\p alg) is true).
182  *
183  * \return The MAC size for the specified algorithm with
184  * the specified key parameters.
185  * \return 0 if the MAC algorithm is not recognized.
186  * \return Either 0 or the correct size for a MAC algorithm that
187  * the implementation recognizes, but does not support.
188  * \return Unspecified if the key parameters are not consistent
189  * with the algorithm.
190  */
191 #define PSA_MAC_LENGTH(key_type, key_bits, alg) \
192  ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
193  PSA_ALG_IS_HMAC(alg) ? PSA_HASH_LENGTH(PSA_ALG_HMAC_GET_HASH(alg)) : \
194  PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
195  ((void)(key_type), (void)(key_bits), 0))
196 
197 /** The maximum size of the output of psa_aead_encrypt(), in bytes.
198  *
199  * If the size of the ciphertext buffer is at least this large, it is
200  * guaranteed that psa_aead_encrypt() will not fail due to an
201  * insufficient buffer size. Depending on the algorithm, the actual size of
202  * the ciphertext may be smaller.
203  *
204  * See also #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length).
205  *
206  * \warning This macro may evaluate its arguments multiple times or
207  * zero times, so you should not pass arguments that contain
208  * side effects.
209  *
210  * \param key_type A symmetric key type that is
211  * compatible with algorithm \p alg.
212  * \param alg An AEAD algorithm
213  * (\c PSA_ALG_XXX value such that
214  * #PSA_ALG_IS_AEAD(\p alg) is true).
215  * \param plaintext_length Size of the plaintext in bytes.
216  *
217  * \return The AEAD ciphertext size for the specified
218  * algorithm.
219  * If the key type or AEAD algorithm is not
220  * recognized, or the parameters are incompatible,
221  * return 0.
222  */
223 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \
224  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
225  (plaintext_length) + PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
226  0)
227 
228 /** A sufficient output buffer size for psa_aead_encrypt(), for any of the
229  * supported key types and AEAD algorithms.
230  *
231  * If the size of the ciphertext buffer is at least this large, it is guaranteed
232  * that psa_aead_encrypt() will not fail due to an insufficient buffer size.
233  *
234  * \note This macro returns a compile-time constant if its arguments are
235  * compile-time constants.
236  *
237  * See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg,
238  * \p plaintext_length).
239  *
240  * \param plaintext_length Size of the plaintext in bytes.
241  *
242  * \return A sufficient output buffer size for any of the
243  * supported key types and AEAD algorithms.
244  *
245  */
246 #define PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) \
247  ((plaintext_length) + PSA_AEAD_TAG_MAX_SIZE)
248 
249 
250 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
251  *
252  * If the size of the plaintext buffer is at least this large, it is
253  * guaranteed that psa_aead_decrypt() will not fail due to an
254  * insufficient buffer size. Depending on the algorithm, the actual size of
255  * the plaintext may be smaller.
256  *
257  * See also #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length).
258  *
259  * \warning This macro may evaluate its arguments multiple times or
260  * zero times, so you should not pass arguments that contain
261  * side effects.
262  *
263  * \param key_type A symmetric key type that is
264  * compatible with algorithm \p alg.
265  * \param alg An AEAD algorithm
266  * (\c PSA_ALG_XXX value such that
267  * #PSA_ALG_IS_AEAD(\p alg) is true).
268  * \param ciphertext_length Size of the plaintext in bytes.
269  *
270  * \return The AEAD ciphertext size for the specified
271  * algorithm.
272  * If the key type or AEAD algorithm is not
273  * recognized, or the parameters are incompatible,
274  * return 0.
275  */
276 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \
277  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
278  (ciphertext_length) > PSA_ALG_AEAD_GET_TAG_LENGTH(alg) ? \
279  (ciphertext_length) - PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
280  0)
281 
282 /** A sufficient output buffer size for psa_aead_decrypt(), for any of the
283  * supported key types and AEAD algorithms.
284  *
285  * If the size of the plaintext buffer is at least this large, it is guaranteed
286  * that psa_aead_decrypt() will not fail due to an insufficient buffer size.
287  *
288  * \note This macro returns a compile-time constant if its arguments are
289  * compile-time constants.
290  *
291  * See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg,
292  * \p ciphertext_length).
293  *
294  * \param ciphertext_length Size of the ciphertext in bytes.
295  *
296  * \return A sufficient output buffer size for any of the
297  * supported key types and AEAD algorithms.
298  *
299  */
300 #define PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) \
301  (ciphertext_length)
302 
303 /** The default nonce size for an AEAD algorithm, in bytes.
304  *
305  * This macro can be used to allocate a buffer of sufficient size to
306  * store the nonce output from #psa_aead_generate_nonce().
307  *
308  * See also #PSA_AEAD_NONCE_MAX_SIZE.
309  *
310  * \note This is not the maximum size of nonce supported as input to
311  * #psa_aead_set_nonce(), #psa_aead_encrypt() or #psa_aead_decrypt(),
312  * just the default size that is generated by #psa_aead_generate_nonce().
313  *
314  * \warning This macro may evaluate its arguments multiple times or
315  * zero times, so you should not pass arguments that contain
316  * side effects.
317  *
318  * \param key_type A symmetric key type that is compatible with
319  * algorithm \p alg.
320  *
321  * \param alg An AEAD algorithm (\c PSA_ALG_XXX value such that
322  * #PSA_ALG_IS_AEAD(\p alg) is true).
323  *
324  * \return The default nonce size for the specified key type and algorithm.
325  * If the key type or AEAD algorithm is not recognized,
326  * or the parameters are incompatible, return 0.
327  */
328 #define PSA_AEAD_NONCE_LENGTH(key_type, alg) \
329  (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 ? \
330  MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_CCM) ? 13 : \
331  MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_GCM) ? 12 : \
332  0 : \
333  (key_type) == PSA_KEY_TYPE_CHACHA20 && \
334  MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_CHACHA20_POLY1305) ? 12 : \
335  0)
336 
337 /** The maximum default nonce size among all supported pairs of key types and
338  * AEAD algorithms, in bytes.
339  *
340  * This is equal to or greater than any value that #PSA_AEAD_NONCE_LENGTH()
341  * may return.
342  *
343  * \note This is not the maximum size of nonce supported as input to
344  * #psa_aead_set_nonce(), #psa_aead_encrypt() or #psa_aead_decrypt(),
345  * just the largest size that may be generated by
346  * #psa_aead_generate_nonce().
347  */
348 #define PSA_AEAD_NONCE_MAX_SIZE 13
349 
350 /** A sufficient output buffer size for psa_aead_update().
351  *
352  * If the size of the output buffer is at least this large, it is
353  * guaranteed that psa_aead_update() will not fail due to an
354  * insufficient buffer size. The actual size of the output may be smaller
355  * in any given call.
356  *
357  * See also #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length).
358  *
359  * \warning This macro may evaluate its arguments multiple times or
360  * zero times, so you should not pass arguments that contain
361  * side effects.
362  *
363  * \param key_type A symmetric key type that is
364  * compatible with algorithm \p alg.
365  * \param alg An AEAD algorithm
366  * (\c PSA_ALG_XXX value such that
367  * #PSA_ALG_IS_AEAD(\p alg) is true).
368  * \param input_length Size of the input in bytes.
369  *
370  * \return A sufficient output buffer size for the specified
371  * algorithm.
372  * If the key type or AEAD algorithm is not
373  * recognized, or the parameters are incompatible,
374  * return 0.
375  */
376 /* For all the AEAD modes defined in this specification, it is possible
377  * to emit output without delay. However, hardware may not always be
378  * capable of this. So for modes based on a block cipher, allow the
379  * implementation to delay the output until it has a full block. */
380 #define PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
381  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
382  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
383  PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type), (input_length)) : \
384  (input_length) : \
385  0)
386 
387 /** A sufficient output buffer size for psa_aead_update(), for any of the
388  * supported key types and AEAD algorithms.
389  *
390  * If the size of the output buffer is at least this large, it is guaranteed
391  * that psa_aead_update() will not fail due to an insufficient buffer size.
392  *
393  * See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
394  *
395  * \param input_length Size of the input in bytes.
396  */
397 #define PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) \
398  (PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, (input_length)))
399 
400 /** A sufficient ciphertext buffer size for psa_aead_finish().
401  *
402  * If the size of the ciphertext buffer is at least this large, it is
403  * guaranteed that psa_aead_finish() will not fail due to an
404  * insufficient ciphertext buffer size. The actual size of the output may
405  * be smaller in any given call.
406  *
407  * See also #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE.
408  *
409  * \param key_type A symmetric key type that is
410  compatible with algorithm \p alg.
411  * \param alg An AEAD algorithm
412  * (\c PSA_ALG_XXX value such that
413  * #PSA_ALG_IS_AEAD(\p alg) is true).
414  *
415  * \return A sufficient ciphertext buffer size for the
416  * specified algorithm.
417  * If the key type or AEAD algorithm is not
418  * recognized, or the parameters are incompatible,
419  * return 0.
420  */
421 #define PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) \
422  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
423  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
424  PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
425  0)
426 
427 /** A sufficient ciphertext buffer size for psa_aead_finish(), for any of the
428  * supported key types and AEAD algorithms.
429  *
430  * See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p key_type, \p alg).
431  */
432 #define PSA_AEAD_FINISH_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
433 
434 /** A sufficient plaintext buffer size for psa_aead_verify().
435  *
436  * If the size of the plaintext buffer is at least this large, it is
437  * guaranteed that psa_aead_verify() will not fail due to an
438  * insufficient plaintext buffer size. The actual size of the output may
439  * be smaller in any given call.
440  *
441  * See also #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE.
442  *
443  * \param key_type A symmetric key type that is
444  * compatible with algorithm \p alg.
445  * \param alg An AEAD algorithm
446  * (\c PSA_ALG_XXX value such that
447  * #PSA_ALG_IS_AEAD(\p alg) is true).
448  *
449  * \return A sufficient plaintext buffer size for the
450  * specified algorithm.
451  * If the key type or AEAD algorithm is not
452  * recognized, or the parameters are incompatible,
453  * return 0.
454  */
455 #define PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) \
456  (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
457  PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
458  PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
459  0)
460 
461 /** A sufficient plaintext buffer size for psa_aead_verify(), for any of the
462  * supported key types and AEAD algorithms.
463  *
464  * See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p key_type, \p alg).
465  */
466 #define PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
467 
468 #define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
469  (PSA_ALG_IS_RSA_OAEP(alg) ? \
470  2 * PSA_HASH_LENGTH(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
471  11 /*PKCS#1v1.5*/)
472 
473 /**
474  * \brief ECDSA signature size for a given curve bit size
475  *
476  * \param curve_bits Curve size in bits.
477  * \return Signature size in bytes.
478  *
479  * \note This macro returns a compile-time constant if its argument is one.
480  */
481 #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
482  (PSA_BITS_TO_BYTES(curve_bits) * 2)
483 
484 /** Sufficient signature buffer size for psa_sign_hash().
485  *
486  * This macro returns a sufficient buffer size for a signature using a key
487  * of the specified type and size, with the specified algorithm.
488  * Note that the actual size of the signature may be smaller
489  * (some algorithms produce a variable-size signature).
490  *
491  * \warning This function may call its arguments multiple times or
492  * zero times, so you should not pass arguments that contain
493  * side effects.
494  *
495  * \param key_type An asymmetric key type (this may indifferently be a
496  * key pair type or a public key type).
497  * \param key_bits The size of the key in bits.
498  * \param alg The signature algorithm.
499  *
500  * \return If the parameters are valid and supported, return
501  * a buffer size in bytes that guarantees that
502  * psa_sign_hash() will not fail with
503  * #PSA_ERROR_BUFFER_TOO_SMALL.
504  * If the parameters are a valid combination that is not supported,
505  * return either a sensible size or 0.
506  * If the parameters are not valid, the
507  * return value is unspecified.
508  */
509 #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
510  (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
511  PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
512  ((void)alg, 0))
513 
514 #define PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE \
515  PSA_ECDSA_SIGNATURE_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
516 
517 /** \def PSA_SIGNATURE_MAX_SIZE
518  *
519  * Maximum size of an asymmetric signature.
520  *
521  * This macro expands to a compile-time constant integer. This value
522  * is the maximum size of a signature in bytes.
523  */
524 #define PSA_SIGNATURE_MAX_SIZE \
525  (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \
526  PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) : \
527  PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE)
528 
529 /** Sufficient output buffer size for psa_asymmetric_encrypt().
530  *
531  * This macro returns a sufficient buffer size for a ciphertext produced using
532  * a key of the specified type and size, with the specified algorithm.
533  * Note that the actual size of the ciphertext may be smaller, depending
534  * on the algorithm.
535  *
536  * \warning This function may call its arguments multiple times or
537  * zero times, so you should not pass arguments that contain
538  * side effects.
539  *
540  * \param key_type An asymmetric key type (this may indifferently be a
541  * key pair type or a public key type).
542  * \param key_bits The size of the key in bits.
543  * \param alg The asymmetric encryption algorithm.
544  *
545  * \return If the parameters are valid and supported, return
546  * a buffer size in bytes that guarantees that
547  * psa_asymmetric_encrypt() will not fail with
548  * #PSA_ERROR_BUFFER_TOO_SMALL.
549  * If the parameters are a valid combination that is not supported,
550  * return either a sensible size or 0.
551  * If the parameters are not valid, the
552  * return value is unspecified.
553  */
554 #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
555  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
556  ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
557  0)
558 
559 /** A sufficient output buffer size for psa_asymmetric_encrypt(), for any
560  * supported asymmetric encryption.
561  *
562  * See also #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg).
563  */
564 /* This macro assumes that RSA is the only supported asymmetric encryption. */
565 #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \
566  (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS))
567 
568 /** Sufficient output buffer size for psa_asymmetric_decrypt().
569  *
570  * This macro returns a sufficient buffer size for a plaintext produced using
571  * a key of the specified type and size, with the specified algorithm.
572  * Note that the actual size of the plaintext may be smaller, depending
573  * on the algorithm.
574  *
575  * \warning This function may call its arguments multiple times or
576  * zero times, so you should not pass arguments that contain
577  * side effects.
578  *
579  * \param key_type An asymmetric key type (this may indifferently be a
580  * key pair type or a public key type).
581  * \param key_bits The size of the key in bits.
582  * \param alg The asymmetric encryption algorithm.
583  *
584  * \return If the parameters are valid and supported, return
585  * a buffer size in bytes that guarantees that
586  * psa_asymmetric_decrypt() will not fail with
587  * #PSA_ERROR_BUFFER_TOO_SMALL.
588  * If the parameters are a valid combination that is not supported,
589  * return either a sensible size or 0.
590  * If the parameters are not valid, the
591  * return value is unspecified.
592  */
593 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
594  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
595  PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
596  0)
597 
598 /** A sufficient output buffer size for psa_asymmetric_decrypt(), for any
599  * supported asymmetric decryption.
600  *
601  * This macro assumes that RSA is the only supported asymmetric encryption.
602  *
603  * See also #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg).
604  */
605 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \
606  (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS))
607 
608 /* Maximum size of the ASN.1 encoding of an INTEGER with the specified
609  * number of bits.
610  *
611  * This definition assumes that bits <= 2^19 - 9 so that the length field
612  * is at most 3 bytes. The length of the encoding is the length of the
613  * bit string padded to a whole number of bytes plus:
614  * - 1 type byte;
615  * - 1 to 3 length bytes;
616  * - 0 to 1 bytes of leading 0 due to the sign bit.
617  */
618 #define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
619  ((bits) / 8 + 5)
620 
621 /* Maximum size of the export encoding of an RSA public key.
622  * Assumes that the public exponent is less than 2^32.
623  *
624  * RSAPublicKey ::= SEQUENCE {
625  * modulus INTEGER, -- n
626  * publicExponent INTEGER } -- e
627  *
628  * - 4 bytes of SEQUENCE overhead;
629  * - n : INTEGER;
630  * - 7 bytes for the public exponent.
631  */
632 #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
633  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
634 
635 /* Maximum size of the export encoding of an RSA key pair.
636  * Assumes thatthe public exponent is less than 2^32 and that the size
637  * difference between the two primes is at most 1 bit.
638  *
639  * RSAPrivateKey ::= SEQUENCE {
640  * version Version, -- 0
641  * modulus INTEGER, -- N-bit
642  * publicExponent INTEGER, -- 32-bit
643  * privateExponent INTEGER, -- N-bit
644  * prime1 INTEGER, -- N/2-bit
645  * prime2 INTEGER, -- N/2-bit
646  * exponent1 INTEGER, -- N/2-bit
647  * exponent2 INTEGER, -- N/2-bit
648  * coefficient INTEGER, -- N/2-bit
649  * }
650  *
651  * - 4 bytes of SEQUENCE overhead;
652  * - 3 bytes of version;
653  * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
654  * overapproximated as 9 half-size INTEGERS;
655  * - 7 bytes for the public exponent.
656  */
657 #define PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) \
658  (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
659 
660 /* Maximum size of the export encoding of a DSA public key.
661  *
662  * SubjectPublicKeyInfo ::= SEQUENCE {
663  * algorithm AlgorithmIdentifier,
664  * subjectPublicKey BIT STRING } -- contains DSAPublicKey
665  * AlgorithmIdentifier ::= SEQUENCE {
666  * algorithm OBJECT IDENTIFIER,
667  * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
668  * DSAPublicKey ::= INTEGER -- public key, Y
669  *
670  * - 3 * 4 bytes of SEQUENCE overhead;
671  * - 1 + 1 + 7 bytes of algorithm (DSA OID);
672  * - 4 bytes of BIT STRING overhead;
673  * - 3 full-size INTEGERs (p, g, y);
674  * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
675  */
676 #define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
677  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
678 
679 /* Maximum size of the export encoding of a DSA key pair.
680  *
681  * DSAPrivateKey ::= SEQUENCE {
682  * version Version, -- 0
683  * prime INTEGER, -- p
684  * subprime INTEGER, -- q
685  * generator INTEGER, -- g
686  * public INTEGER, -- y
687  * private INTEGER, -- x
688  * }
689  *
690  * - 4 bytes of SEQUENCE overhead;
691  * - 3 bytes of version;
692  * - 3 full-size INTEGERs (p, g, y);
693  * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
694  */
695 #define PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) \
696  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
697 
698 /* Maximum size of the export encoding of an ECC public key.
699  *
700  * The representation of an ECC public key is:
701  * - The byte 0x04;
702  * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
703  * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
704  * - where m is the bit size associated with the curve.
705  *
706  * - 1 byte + 2 * point size.
707  */
708 #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
709  (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
710 
711 /* Maximum size of the export encoding of an ECC key pair.
712  *
713  * An ECC key pair is represented by the secret value.
714  */
715 #define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \
716  (PSA_BITS_TO_BYTES(key_bits))
717 
718 /** Sufficient output buffer size for psa_export_key() or
719  * psa_export_public_key().
720  *
721  * This macro returns a compile-time constant if its arguments are
722  * compile-time constants.
723  *
724  * \warning This macro may evaluate its arguments multiple times or
725  * zero times, so you should not pass arguments that contain
726  * side effects.
727  *
728  * The following code illustrates how to allocate enough memory to export
729  * a key by querying the key type and size at runtime.
730  * \code{c}
731  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
732  * psa_status_t status;
733  * status = psa_get_key_attributes(key, &attributes);
734  * if (status != PSA_SUCCESS) handle_error(...);
735  * psa_key_type_t key_type = psa_get_key_type(&attributes);
736  * size_t key_bits = psa_get_key_bits(&attributes);
737  * size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
738  * psa_reset_key_attributes(&attributes);
739  * uint8_t *buffer = malloc(buffer_size);
740  * if (buffer == NULL) handle_error(...);
741  * size_t buffer_length;
742  * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
743  * if (status != PSA_SUCCESS) handle_error(...);
744  * \endcode
745  *
746  * \param key_type A supported key type.
747  * \param key_bits The size of the key in bits.
748  *
749  * \return If the parameters are valid and supported, return
750  * a buffer size in bytes that guarantees that
751  * psa_export_key() or psa_export_public_key() will not fail with
752  * #PSA_ERROR_BUFFER_TOO_SMALL.
753  * If the parameters are a valid combination that is not supported,
754  * return either a sensible size or 0.
755  * If the parameters are not valid, the return value is unspecified.
756  */
757 #define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \
758  (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
759  (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) : \
760  (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
761  (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
762  (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
763  PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
764  PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
765  0)
766 
767 /** Sufficient output buffer size for psa_export_public_key().
768  *
769  * This macro returns a compile-time constant if its arguments are
770  * compile-time constants.
771  *
772  * \warning This macro may evaluate its arguments multiple times or
773  * zero times, so you should not pass arguments that contain
774  * side effects.
775  *
776  * The following code illustrates how to allocate enough memory to export
777  * a public key by querying the key type and size at runtime.
778  * \code{c}
779  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
780  * psa_status_t status;
781  * status = psa_get_key_attributes(key, &attributes);
782  * if (status != PSA_SUCCESS) handle_error(...);
783  * psa_key_type_t key_type = psa_get_key_type(&attributes);
784  * size_t key_bits = psa_get_key_bits(&attributes);
785  * size_t buffer_size = PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits);
786  * psa_reset_key_attributes(&attributes);
787  * uint8_t *buffer = malloc(buffer_size);
788  * if (buffer == NULL) handle_error(...);
789  * size_t buffer_length;
790  * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
791  * if (status != PSA_SUCCESS) handle_error(...);
792  * \endcode
793  *
794  * \param key_type A public key or key pair key type.
795  * \param key_bits The size of the key in bits.
796  *
797  * \return If the parameters are valid and supported, return
798  * a buffer size in bytes that guarantees that
799  * psa_export_public_key() will not fail with
800  * #PSA_ERROR_BUFFER_TOO_SMALL.
801  * If the parameters are a valid combination that is not
802  * supported, return either a sensible size or 0.
803  * If the parameters are not valid,
804  * the return value is unspecified.
805  *
806  * If the parameters are valid and supported,
807  * return the same result as
808  * #PSA_EXPORT_KEY_OUTPUT_SIZE(
809  * \p #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\p key_type),
810  * \p key_bits).
811  */
812 #define PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits) \
813  (PSA_KEY_TYPE_IS_RSA(key_type) ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
814  PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
815  0)
816 
817 /** Sufficient buffer size for exporting any asymmetric key pair.
818  *
819  * This macro expands to a compile-time constant integer. This value is
820  * a sufficient buffer size when calling psa_export_key() to export any
821  * asymmetric key pair, regardless of the exact key type and key size.
822  *
823  * See also #PSA_EXPORT_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
824  */
825 #define PSA_EXPORT_KEY_PAIR_MAX_SIZE \
826  (PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS) > \
827  PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS) ? \
828  PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS) : \
829  PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS))
830 
831 /** Sufficient buffer size for exporting any asymmetric public key.
832  *
833  * This macro expands to a compile-time constant integer. This value is
834  * a sufficient buffer size when calling psa_export_key() or
835  * psa_export_public_key() to export any asymmetric public key,
836  * regardless of the exact key type and key size.
837  *
838  * See also #PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
839  */
840 #define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE \
841  (PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS) > \
842  PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS) ? \
843  PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS) : \
844  PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS))
845 
846 /** Sufficient output buffer size for psa_raw_key_agreement().
847  *
848  * This macro returns a compile-time constant if its arguments are
849  * compile-time constants.
850  *
851  * \warning This macro may evaluate its arguments multiple times or
852  * zero times, so you should not pass arguments that contain
853  * side effects.
854  *
855  * See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE.
856  *
857  * \param key_type A supported key type.
858  * \param key_bits The size of the key in bits.
859  *
860  * \return If the parameters are valid and supported, return
861  * a buffer size in bytes that guarantees that
862  * psa_raw_key_agreement() will not fail with
863  * #PSA_ERROR_BUFFER_TOO_SMALL.
864  * If the parameters are a valid combination that
865  * is not supported, return either a sensible size or 0.
866  * If the parameters are not valid,
867  * the return value is unspecified.
868  */
869 /* FFDH is not yet supported in PSA. */
870 #define PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits) \
871  (PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? \
872  PSA_BITS_TO_BYTES(key_bits) : \
873  0)
874 
875 /** Maximum size of the output from psa_raw_key_agreement().
876  *
877  * This macro expands to a compile-time constant integer. This value is the
878  * maximum size of the output any raw key agreement algorithm, in bytes.
879  *
880  * See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(\p key_type, \p key_bits).
881  */
882 #define PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE \
883  (PSA_BITS_TO_BYTES(PSA_VENDOR_ECC_MAX_CURVE_BITS))
884 
885 /** The default IV size for a cipher algorithm, in bytes.
886  *
887  * The IV that is generated as part of a call to #psa_cipher_encrypt() is always
888  * the default IV length for the algorithm.
889  *
890  * This macro can be used to allocate a buffer of sufficient size to
891  * store the IV output from #psa_cipher_generate_iv() when using
892  * a multi-part cipher operation.
893  *
894  * See also #PSA_CIPHER_IV_MAX_SIZE.
895  *
896  * \warning This macro may evaluate its arguments multiple times or
897  * zero times, so you should not pass arguments that contain
898  * side effects.
899  *
900  * \param key_type A symmetric key type that is compatible with algorithm \p alg.
901  *
902  * \param alg A cipher algorithm (\c PSA_ALG_XXX value such that
903  * #PSA_ALG_IS_CIPHER(\p alg) is true).
904  *
905  * \return The default IV size for the specified key type and algorithm.
906  * If the algorithm does not use an IV, return 0.
907  * If the key type or cipher algorithm is not recognized,
908  * or the parameters are incompatible, return 0.
909  */
910 #define PSA_CIPHER_IV_LENGTH(key_type, alg) \
911  (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) > 1 && \
912  ((alg) == PSA_ALG_CTR || \
913  (alg) == PSA_ALG_CFB || \
914  (alg) == PSA_ALG_OFB || \
915  (alg) == PSA_ALG_XTS || \
916  (alg) == PSA_ALG_CBC_NO_PADDING || \
917  (alg) == PSA_ALG_CBC_PKCS7) ? PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
918  (key_type) == PSA_KEY_TYPE_CHACHA20 && \
919  (alg) == PSA_ALG_STREAM_CIPHER ? 12 : \
920  0)
921 
922 /** The maximum IV size for all supported cipher algorithms, in bytes.
923  *
924  * See also #PSA_CIPHER_IV_LENGTH().
925  */
926 #define PSA_CIPHER_IV_MAX_SIZE 16
927 
928 /** The maximum size of the output of psa_cipher_encrypt(), in bytes.
929  *
930  * If the size of the output buffer is at least this large, it is guaranteed
931  * that psa_cipher_encrypt() will not fail due to an insufficient buffer size.
932  * Depending on the algorithm, the actual size of the output might be smaller.
933  *
934  * See also #PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(\p input_length).
935  *
936  * \warning This macro may evaluate its arguments multiple times or
937  * zero times, so you should not pass arguments that contain
938  * side effects.
939  *
940  * \param key_type A symmetric key type that is compatible with algorithm
941  * alg.
942  * \param alg A cipher algorithm (\c PSA_ALG_XXX value such that
943  * #PSA_ALG_IS_CIPHER(\p alg) is true).
944  * \param input_length Size of the input in bytes.
945  *
946  * \return A sufficient output size for the specified key type and
947  * algorithm. If the key type or cipher algorithm is not
948  * recognized, or the parameters are incompatible,
949  * return 0.
950  */
951 #define PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(key_type, alg, input_length) \
952  (alg == PSA_ALG_CBC_PKCS7 ? \
953  PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type), \
954  (input_length) + 1) + \
955  PSA_CIPHER_IV_LENGTH((key_type), (alg)) : \
956  (PSA_ALG_IS_CIPHER(alg) ? \
957  (input_length) + PSA_CIPHER_IV_LENGTH((key_type), (alg)) : \
958  0))
959 
960 /** A sufficient output buffer size for psa_cipher_encrypt(), for any of the
961  * supported key types and cipher algorithms.
962  *
963  * If the size of the output buffer is at least this large, it is guaranteed
964  * that psa_cipher_encrypt() will not fail due to an insufficient buffer size.
965  *
966  * See also #PSA_CIPHER_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
967  *
968  * \param input_length Size of the input in bytes.
969  *
970  */
971 #define PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(input_length) \
972  (PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, \
973  (input_length) + 1) + \
974  PSA_CIPHER_IV_MAX_SIZE)
975 
976 /** The maximum size of the output of psa_cipher_decrypt(), in bytes.
977  *
978  * If the size of the output buffer is at least this large, it is guaranteed
979  * that psa_cipher_decrypt() will not fail due to an insufficient buffer size.
980  * Depending on the algorithm, the actual size of the output might be smaller.
981  *
982  * See also #PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(\p input_length).
983  *
984  * \param key_type A symmetric key type that is compatible with algorithm
985  * alg.
986  * \param alg A cipher algorithm (\c PSA_ALG_XXX value such that
987  * #PSA_ALG_IS_CIPHER(\p alg) is true).
988  * \param input_length Size of the input in bytes.
989  *
990  * \return A sufficient output size for the specified key type and
991  * algorithm. If the key type or cipher algorithm is not
992  * recognized, or the parameters are incompatible,
993  * return 0.
994  */
995 #define PSA_CIPHER_DECRYPT_OUTPUT_SIZE(key_type, alg, input_length) \
996  (PSA_ALG_IS_CIPHER(alg) && \
997  ((key_type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC ? \
998  (input_length) : \
999  0)
1000 
1001 /** A sufficient output buffer size for psa_cipher_decrypt(), for any of the
1002  * supported key types and cipher algorithms.
1003  *
1004  * If the size of the output buffer is at least this large, it is guaranteed
1005  * that psa_cipher_decrypt() will not fail due to an insufficient buffer size.
1006  *
1007  * See also #PSA_CIPHER_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
1008  *
1009  * \param input_length Size of the input in bytes.
1010  */
1011 #define PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(input_length) \
1012  (input_length)
1013 
1014 /** A sufficient output buffer size for psa_cipher_update().
1015  *
1016  * If the size of the output buffer is at least this large, it is guaranteed
1017  * that psa_cipher_update() will not fail due to an insufficient buffer size.
1018  * The actual size of the output might be smaller in any given call.
1019  *
1020  * See also #PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE(\p input_length).
1021  *
1022  * \param key_type A symmetric key type that is compatible with algorithm
1023  * alg.
1024  * \param alg A cipher algorithm (PSA_ALG_XXX value such that
1025  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1026  * \param input_length Size of the input in bytes.
1027  *
1028  * \return A sufficient output size for the specified key type and
1029  * algorithm. If the key type or cipher algorithm is not
1030  * recognized, or the parameters are incompatible, return 0.
1031  */
1032 #define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
1033  (PSA_ALG_IS_CIPHER(alg) ? \
1034  (((alg) == PSA_ALG_CBC_PKCS7 || \
1035  (alg) == PSA_ALG_CBC_NO_PADDING || \
1036  (alg) == PSA_ALG_ECB_NO_PADDING) ? \
1037  PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type), \
1038  input_length) : \
1039  (input_length)) : \
1040  0)
1041 
1042 /** A sufficient output buffer size for psa_cipher_update(), for any of the
1043  * supported key types and cipher algorithms.
1044  *
1045  * If the size of the output buffer is at least this large, it is guaranteed
1046  * that psa_cipher_update() will not fail due to an insufficient buffer size.
1047  *
1048  * See also #PSA_CIPHER_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length).
1049  *
1050  * \param input_length Size of the input in bytes.
1051  */
1052 #define PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE(input_length) \
1053  (PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, input_length))
1054 
1055 /** A sufficient ciphertext buffer size for psa_cipher_finish().
1056  *
1057  * If the size of the ciphertext buffer is at least this large, it is
1058  * guaranteed that psa_cipher_finish() will not fail due to an insufficient
1059  * ciphertext buffer size. The actual size of the output might be smaller in
1060  * any given call.
1061  *
1062  * See also #PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE().
1063  *
1064  * \param key_type A symmetric key type that is compatible with algorithm
1065  * alg.
1066  * \param alg A cipher algorithm (PSA_ALG_XXX value such that
1067  * #PSA_ALG_IS_CIPHER(\p alg) is true).
1068  * \return A sufficient output size for the specified key type and
1069  * algorithm. If the key type or cipher algorithm is not
1070  * recognized, or the parameters are incompatible, return 0.
1071  */
1072 #define PSA_CIPHER_FINISH_OUTPUT_SIZE(key_type, alg) \
1073  (PSA_ALG_IS_CIPHER(alg) ? \
1074  (alg == PSA_ALG_CBC_PKCS7 ? \
1075  PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
1076  0) : \
1077  0)
1078 
1079 /** A sufficient ciphertext buffer size for psa_cipher_finish(), for any of the
1080  * supported key types and cipher algorithms.
1081  *
1082  * See also #PSA_CIPHER_FINISH_OUTPUT_SIZE(\p key_type, \p alg).
1083  */
1084 #define PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE \
1085  (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)
1086 
1087 #endif /* PSA_CRYPTO_SIZES_H */
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.