Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_MBED_PSA_SRV/inc/psa/crypto_sizes.h
1 /**
2  * \file psa/crypto_sizes.h
3  *
4  * \brief PSA cryptography module: Mbed TLS buffer size macros
5  *
6  * \note This file may not be included directly. Applications must
7  * include psa/crypto.h.
8  *
9  * This file contains the definitions of macros that are useful to
10  * compute buffer sizes. The signatures and semantics of these macros
11  * are standardized, but the definitions are not, because they depend on
12  * the available algorithms and, in some cases, on permitted tolerances
13  * on buffer sizes.
14  *
15  * In implementations with isolation between the application and the
16  * cryptography module, implementers should take care to ensure that
17  * the definitions that are exposed to applications match what the
18  * module implements.
19  *
20  * Macros that compute sizes whose values do not depend on the
21  * implementation are in crypto.h.
22  */
23 /*
24  * Copyright The Mbed TLS Contributors
25  * SPDX-License-Identifier: Apache-2.0
26  *
27  * Licensed under the Apache License, Version 2.0 (the "License"); you may
28  * not use this file except in compliance with the License.
29  * You may obtain a copy of the License at
30  *
31  * http://www.apache.org/licenses/LICENSE-2.0
32  *
33  * Unless required by applicable law or agreed to in writing, software
34  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
35  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
36  * See the License for the specific language governing permissions and
37  * limitations under the License.
38  */
39 
40 #ifndef PSA_CRYPTO_SIZES_H
41 #define PSA_CRYPTO_SIZES_H
42 
43 /* Include the Mbed TLS configuration file, the way Mbed TLS does it
44  * in each of its header files. */
45 #if !defined(MBEDTLS_CONFIG_FILE)
46 #include "mbedtls/config.h"
47 #else
48 #include MBEDTLS_CONFIG_FILE
49 #endif
50 
51 #define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
52 #define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
53 
54 #define PSA_ROUND_UP_TO_MULTIPLE(block_size, length) \
55  (((length) + (block_size) - 1) / (block_size) * (block_size))
56 
57 /** The size of the output of psa_hash_finish(), in bytes.
58  *
59  * This is also the hash size that psa_hash_verify() expects.
60  *
61  * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
62  * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm
63  * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a
64  * hash algorithm).
65  *
66  * \return The hash size for the specified hash algorithm.
67  * If the hash algorithm is not recognized, return 0.
68  * An implementation may return either 0 or the correct size
69  * for a hash algorithm that it recognizes, but does not support.
70  */
71 #define PSA_HASH_SIZE(alg) \
72  ( \
73  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
74  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
75  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
76  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
77  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
78  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
79  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
80  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
81  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
82  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
83  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
84  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
85  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
86  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
87  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
88  0)
89 
90 /** \def PSA_HASH_MAX_SIZE
91  *
92  * Maximum size of a hash.
93  *
94  * This macro must expand to a compile-time constant integer. This value
95  * should be the maximum size of a hash supported by the implementation,
96  * in bytes, and must be no smaller than this maximum.
97  */
98 /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
99  * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
100  * HMAC-SHA3-512. */
101 #if defined(MBEDTLS_SHA512_C)
102 #define PSA_HASH_MAX_SIZE 64
103 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
104 #else
105 #define PSA_HASH_MAX_SIZE 32
106 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 64
107 #endif
108 
109 /** \def PSA_MAC_MAX_SIZE
110  *
111  * Maximum size of a MAC.
112  *
113  * This macro must expand to a compile-time constant integer. This value
114  * should be the maximum size of a MAC supported by the implementation,
115  * in bytes, and must be no smaller than this maximum.
116  */
117 /* All non-HMAC MACs have a maximum size that's smaller than the
118  * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
119 /* Note that the encoding of truncated MAC algorithms limits this value
120  * to 64 bytes.
121  */
122 #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
123 
124 /** The tag size for an AEAD algorithm, in bytes.
125  *
126  * \param alg An AEAD algorithm
127  * (\c PSA_ALG_XXX value such that
128  * #PSA_ALG_IS_AEAD(\p alg) is true).
129  *
130  * \return The tag size for the specified algorithm.
131  * If the AEAD algorithm does not have an identified
132  * tag that can be distinguished from the rest of
133  * the ciphertext, return 0.
134  * If the AEAD algorithm is not recognized, return 0.
135  * An implementation may return either 0 or a
136  * correct size for an AEAD algorithm that it
137  * recognizes, but does not support.
138  */
139 #define PSA_AEAD_TAG_LENGTH(alg) \
140  (PSA_ALG_IS_AEAD(alg) ? \
141  (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
142  0)
143 
144 /* The maximum size of an RSA key on this implementation, in bits.
145  * This is a vendor-specific macro.
146  *
147  * Mbed TLS does not set a hard limit on the size of RSA keys: any key
148  * whose parameters fit in a bignum is accepted. However large keys can
149  * induce a large memory usage and long computation times. Unlike other
150  * auxiliary macros in this file and in crypto.h, which reflect how the
151  * library is configured, this macro defines how the library is
152  * configured. This implementation refuses to import or generate an
153  * RSA key whose size is larger than the value defined here.
154  *
155  * Note that an implementation may set different size limits for different
156  * operations, and does not need to accept all key sizes up to the limit. */
157 #define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
158 
159 /* The maximum size of an ECC key on this implementation, in bits.
160  * This is a vendor-specific macro. */
161 #if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
162 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
163 #elif defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
164 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 512
165 #elif defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
166 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 448
167 #elif defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
168 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
169 #elif defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
170 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
171 #elif defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
172 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
173 #elif defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
174 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
175 #elif defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
176 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
177 #elif defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED)
178 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 255
179 #elif defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
180 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
181 #elif defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
182 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
183 #elif defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
184 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
185 #elif defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
186 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
187 #else
188 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 0
189 #endif
190 
191 /** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
192  *
193  * This macro returns the maximum length of the PSK supported
194  * by the TLS-1.2 PSK-to-MS key derivation.
195  *
196  * Quoting RFC 4279, Sect 5.3:
197  * TLS implementations supporting these ciphersuites MUST support
198  * arbitrary PSK identities up to 128 octets in length, and arbitrary
199  * PSKs up to 64 octets in length. Supporting longer identities and
200  * keys is RECOMMENDED.
201  *
202  * Therefore, no implementation should define a value smaller than 64
203  * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.
204  */
205 #define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
206 
207 /** The maximum size of a block cipher supported by the implementation. */
208 #define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
209 
210 /** The size of the output of psa_mac_sign_finish(), in bytes.
211  *
212  * This is also the MAC size that psa_mac_verify_finish() expects.
213  *
214  * \param key_type The type of the MAC key.
215  * \param key_bits The size of the MAC key in bits.
216  * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
217  * #PSA_ALG_IS_MAC(\p alg) is true).
218  *
219  * \return The MAC size for the specified algorithm with
220  * the specified key parameters.
221  * \return 0 if the MAC algorithm is not recognized.
222  * \return Either 0 or the correct size for a MAC algorithm that
223  * the implementation recognizes, but does not support.
224  * \return Unspecified if the key parameters are not consistent
225  * with the algorithm.
226  */
227 #define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
228  ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
229  PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
230  PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
231  ((void)(key_type), (void)(key_bits), 0))
232 
233 /** The maximum size of the output of psa_aead_encrypt(), in bytes.
234  *
235  * If the size of the ciphertext buffer is at least this large, it is
236  * guaranteed that psa_aead_encrypt() will not fail due to an
237  * insufficient buffer size. Depending on the algorithm, the actual size of
238  * the ciphertext may be smaller.
239  *
240  * \param alg An AEAD algorithm
241  * (\c PSA_ALG_XXX value such that
242  * #PSA_ALG_IS_AEAD(\p alg) is true).
243  * \param plaintext_length Size of the plaintext in bytes.
244  *
245  * \return The AEAD ciphertext size for the specified
246  * algorithm.
247  * If the AEAD algorithm is not recognized, return 0.
248  * An implementation may return either 0 or a
249  * correct size for an AEAD algorithm that it
250  * recognizes, but does not support.
251  */
252 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
253  (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
254  (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
255  0)
256 
257 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
258  *
259  * If the size of the plaintext buffer is at least this large, it is
260  * guaranteed that psa_aead_decrypt() will not fail due to an
261  * insufficient buffer size. Depending on the algorithm, the actual size of
262  * the plaintext may be smaller.
263  *
264  * \param alg An AEAD algorithm
265  * (\c PSA_ALG_XXX value such that
266  * #PSA_ALG_IS_AEAD(\p alg) is true).
267  * \param ciphertext_length Size of the plaintext in bytes.
268  *
269  * \return The AEAD ciphertext size for the specified
270  * algorithm.
271  * If the AEAD algorithm is not recognized, return 0.
272  * An implementation may return either 0 or a
273  * correct size for an AEAD algorithm that it
274  * recognizes, but does not support.
275  */
276 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
277  (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
278  (ciphertext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
279  0)
280 
281 /** A sufficient output buffer size for psa_aead_update().
282  *
283  * If the size of the output buffer is at least this large, it is
284  * guaranteed that psa_aead_update() will not fail due to an
285  * insufficient buffer size. The actual size of the output may be smaller
286  * in any given call.
287  *
288  * \param alg An AEAD algorithm
289  * (\c PSA_ALG_XXX value such that
290  * #PSA_ALG_IS_AEAD(\p alg) is true).
291  * \param input_length Size of the input in bytes.
292  *
293  * \return A sufficient output buffer size for the specified
294  * algorithm.
295  * If the AEAD algorithm is not recognized, return 0.
296  * An implementation may return either 0 or a
297  * correct size for an AEAD algorithm that it
298  * recognizes, but does not support.
299  */
300 /* For all the AEAD modes defined in this specification, it is possible
301  * to emit output without delay. However, hardware may not always be
302  * capable of this. So for modes based on a block cipher, allow the
303  * implementation to delay the output until it has a full block. */
304 #define PSA_AEAD_UPDATE_OUTPUT_SIZE(alg, input_length) \
305  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
306  PSA_ROUND_UP_TO_MULTIPLE(PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE, (input_length)) : \
307  (input_length))
308 
309 /** A sufficient ciphertext buffer size for psa_aead_finish().
310  *
311  * If the size of the ciphertext buffer is at least this large, it is
312  * guaranteed that psa_aead_finish() will not fail due to an
313  * insufficient ciphertext buffer size. The actual size of the output may
314  * be smaller in any given call.
315  *
316  * \param alg An AEAD algorithm
317  * (\c PSA_ALG_XXX value such that
318  * #PSA_ALG_IS_AEAD(\p alg) is true).
319  *
320  * \return A sufficient ciphertext buffer size for the
321  * specified algorithm.
322  * If the AEAD algorithm is not recognized, return 0.
323  * An implementation may return either 0 or a
324  * correct size for an AEAD algorithm that it
325  * recognizes, but does not support.
326  */
327 #define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \
328  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
329  PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
330  0)
331 
332 /** A sufficient plaintext buffer size for psa_aead_verify().
333  *
334  * If the size of the plaintext buffer is at least this large, it is
335  * guaranteed that psa_aead_verify() will not fail due to an
336  * insufficient plaintext buffer size. The actual size of the output may
337  * be smaller in any given call.
338  *
339  * \param alg An AEAD algorithm
340  * (\c PSA_ALG_XXX value such that
341  * #PSA_ALG_IS_AEAD(\p alg) is true).
342  *
343  * \return A sufficient plaintext buffer size for the
344  * specified algorithm.
345  * If the AEAD algorithm is not recognized, return 0.
346  * An implementation may return either 0 or a
347  * correct size for an AEAD algorithm that it
348  * recognizes, but does not support.
349  */
350 #define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg) \
351  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
352  PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
353  0)
354 
355 #define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
356  (PSA_ALG_IS_RSA_OAEP(alg) ? \
357  2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
358  11 /*PKCS#1v1.5*/)
359 
360 /**
361  * \brief ECDSA signature size for a given curve bit size
362  *
363  * \param curve_bits Curve size in bits.
364  * \return Signature size in bytes.
365  *
366  * \note This macro returns a compile-time constant if its argument is one.
367  */
368 #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
369  (PSA_BITS_TO_BYTES(curve_bits) * 2)
370 
371 /** Sufficient signature buffer size for psa_sign_hash().
372  *
373  * This macro returns a sufficient buffer size for a signature using a key
374  * of the specified type and size, with the specified algorithm.
375  * Note that the actual size of the signature may be smaller
376  * (some algorithms produce a variable-size signature).
377  *
378  * \warning This function may call its arguments multiple times or
379  * zero times, so you should not pass arguments that contain
380  * side effects.
381  *
382  * \param key_type An asymmetric key type (this may indifferently be a
383  * key pair type or a public key type).
384  * \param key_bits The size of the key in bits.
385  * \param alg The signature algorithm.
386  *
387  * \return If the parameters are valid and supported, return
388  * a buffer size in bytes that guarantees that
389  * psa_sign_hash() will not fail with
390  * #PSA_ERROR_BUFFER_TOO_SMALL.
391  * If the parameters are a valid combination that is not supported
392  * by the implementation, this macro shall return either a
393  * sensible size or 0.
394  * If the parameters are not valid, the
395  * return value is unspecified.
396  */
397 #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
398  (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
399  PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
400  ((void)alg, 0))
401 
402 #define PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE \
403  PSA_ECDSA_SIGNATURE_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
404 
405 /** \def PSA_SIGNATURE_MAX_SIZE
406  *
407  * Maximum size of an asymmetric signature.
408  *
409  * This macro must expand to a compile-time constant integer. This value
410  * should be the maximum size of a signature supported by the implementation,
411  * in bytes, and must be no smaller than this maximum.
412  */
413 #define PSA_SIGNATURE_MAX_SIZE \
414  (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \
415  PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) : \
416  PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE)
417 
418 /** Sufficient output buffer size for psa_asymmetric_encrypt().
419  *
420  * This macro returns a sufficient buffer size for a ciphertext produced using
421  * a key of the specified type and size, with the specified algorithm.
422  * Note that the actual size of the ciphertext may be smaller, depending
423  * on the algorithm.
424  *
425  * \warning This function may call its arguments multiple times or
426  * zero times, so you should not pass arguments that contain
427  * side effects.
428  *
429  * \param key_type An asymmetric key type (this may indifferently be a
430  * key pair type or a public key type).
431  * \param key_bits The size of the key in bits.
432  * \param alg The asymmetric encryption algorithm.
433  *
434  * \return If the parameters are valid and supported, return
435  * a buffer size in bytes that guarantees that
436  * psa_asymmetric_encrypt() will not fail with
437  * #PSA_ERROR_BUFFER_TOO_SMALL.
438  * If the parameters are a valid combination that is not supported
439  * by the implementation, this macro shall return either a
440  * sensible size or 0.
441  * If the parameters are not valid, the
442  * return value is unspecified.
443  */
444 #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
445  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
446  ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
447  0)
448 
449 /** Sufficient output buffer size for psa_asymmetric_decrypt().
450  *
451  * This macro returns a sufficient buffer size for a plaintext produced using
452  * a key of the specified type and size, with the specified algorithm.
453  * Note that the actual size of the plaintext may be smaller, depending
454  * on the algorithm.
455  *
456  * \warning This function may call its arguments multiple times or
457  * zero times, so you should not pass arguments that contain
458  * side effects.
459  *
460  * \param key_type An asymmetric key type (this may indifferently be a
461  * key pair type or a public key type).
462  * \param key_bits The size of the key in bits.
463  * \param alg The asymmetric encryption algorithm.
464  *
465  * \return If the parameters are valid and supported, return
466  * a buffer size in bytes that guarantees that
467  * psa_asymmetric_decrypt() will not fail with
468  * #PSA_ERROR_BUFFER_TOO_SMALL.
469  * If the parameters are a valid combination that is not supported
470  * by the implementation, this macro shall return either a
471  * sensible size or 0.
472  * If the parameters are not valid, the
473  * return value is unspecified.
474  */
475 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
476  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
477  PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
478  0)
479 
480 /* Maximum size of the ASN.1 encoding of an INTEGER with the specified
481  * number of bits.
482  *
483  * This definition assumes that bits <= 2^19 - 9 so that the length field
484  * is at most 3 bytes. The length of the encoding is the length of the
485  * bit string padded to a whole number of bytes plus:
486  * - 1 type byte;
487  * - 1 to 3 length bytes;
488  * - 0 to 1 bytes of leading 0 due to the sign bit.
489  */
490 #define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
491  ((bits) / 8 + 5)
492 
493 /* Maximum size of the export encoding of an RSA public key.
494  * Assumes that the public exponent is less than 2^32.
495  *
496  * RSAPublicKey ::= SEQUENCE {
497  * modulus INTEGER, -- n
498  * publicExponent INTEGER } -- e
499  *
500  * - 4 bytes of SEQUENCE overhead;
501  * - n : INTEGER;
502  * - 7 bytes for the public exponent.
503  */
504 #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
505  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
506 
507 /* Maximum size of the export encoding of an RSA key pair.
508  * Assumes thatthe public exponent is less than 2^32 and that the size
509  * difference between the two primes is at most 1 bit.
510  *
511  * RSAPrivateKey ::= SEQUENCE {
512  * version Version, -- 0
513  * modulus INTEGER, -- N-bit
514  * publicExponent INTEGER, -- 32-bit
515  * privateExponent INTEGER, -- N-bit
516  * prime1 INTEGER, -- N/2-bit
517  * prime2 INTEGER, -- N/2-bit
518  * exponent1 INTEGER, -- N/2-bit
519  * exponent2 INTEGER, -- N/2-bit
520  * coefficient INTEGER, -- N/2-bit
521  * }
522  *
523  * - 4 bytes of SEQUENCE overhead;
524  * - 3 bytes of version;
525  * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
526  * overapproximated as 9 half-size INTEGERS;
527  * - 7 bytes for the public exponent.
528  */
529 #define PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) \
530  (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
531 
532 /* Maximum size of the export encoding of a DSA public key.
533  *
534  * SubjectPublicKeyInfo ::= SEQUENCE {
535  * algorithm AlgorithmIdentifier,
536  * subjectPublicKey BIT STRING } -- contains DSAPublicKey
537  * AlgorithmIdentifier ::= SEQUENCE {
538  * algorithm OBJECT IDENTIFIER,
539  * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
540  * DSAPublicKey ::= INTEGER -- public key, Y
541  *
542  * - 3 * 4 bytes of SEQUENCE overhead;
543  * - 1 + 1 + 7 bytes of algorithm (DSA OID);
544  * - 4 bytes of BIT STRING overhead;
545  * - 3 full-size INTEGERs (p, g, y);
546  * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
547  */
548 #define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
549  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
550 
551 /* Maximum size of the export encoding of a DSA key pair.
552  *
553  * DSAPrivateKey ::= SEQUENCE {
554  * version Version, -- 0
555  * prime INTEGER, -- p
556  * subprime INTEGER, -- q
557  * generator INTEGER, -- g
558  * public INTEGER, -- y
559  * private INTEGER, -- x
560  * }
561  *
562  * - 4 bytes of SEQUENCE overhead;
563  * - 3 bytes of version;
564  * - 3 full-size INTEGERs (p, g, y);
565  * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
566  */
567 #define PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) \
568  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
569 
570 /* Maximum size of the export encoding of an ECC public key.
571  *
572  * The representation of an ECC public key is:
573  * - The byte 0x04;
574  * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
575  * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
576  * - where m is the bit size associated with the curve.
577  *
578  * - 1 byte + 2 * point size.
579  */
580 #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
581  (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
582 
583 /* Maximum size of the export encoding of an ECC key pair.
584  *
585  * An ECC key pair is represented by the secret value.
586  */
587 #define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \
588  (PSA_BITS_TO_BYTES(key_bits))
589 
590 /** Sufficient output buffer size for psa_export_key() or psa_export_public_key().
591  *
592  * This macro returns a compile-time constant if its arguments are
593  * compile-time constants.
594  *
595  * \warning This function may call its arguments multiple times or
596  * zero times, so you should not pass arguments that contain
597  * side effects.
598  *
599  * The following code illustrates how to allocate enough memory to export
600  * a key by querying the key type and size at runtime.
601  * \code{c}
602  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
603  * psa_status_t status;
604  * status = psa_get_key_attributes(key, &attributes);
605  * if (status != PSA_SUCCESS) handle_error(...);
606  * psa_key_type_t key_type = psa_get_key_type(&attributes);
607  * size_t key_bits = psa_get_key_bits(&attributes);
608  * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
609  * psa_reset_key_attributes(&attributes);
610  * uint8_t *buffer = malloc(buffer_size);
611  * if (buffer == NULL) handle_error(...);
612  * size_t buffer_length;
613  * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
614  * if (status != PSA_SUCCESS) handle_error(...);
615  * \endcode
616  *
617  * For psa_export_public_key(), calculate the buffer size from the
618  * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
619  * to convert a key pair type to the corresponding public key type.
620  * \code{c}
621  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
622  * psa_status_t status;
623  * status = psa_get_key_attributes(key, &attributes);
624  * if (status != PSA_SUCCESS) handle_error(...);
625  * psa_key_type_t key_type = psa_get_key_type(&attributes);
626  * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type);
627  * size_t key_bits = psa_get_key_bits(&attributes);
628  * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
629  * psa_reset_key_attributes(&attributes);
630  * uint8_t *buffer = malloc(buffer_size);
631  * if (buffer == NULL) handle_error(...);
632  * size_t buffer_length;
633  * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
634  * if (status != PSA_SUCCESS) handle_error(...);
635  * \endcode
636  *
637  * \param key_type A supported key type.
638  * \param key_bits The size of the key in bits.
639  *
640  * \return If the parameters are valid and supported, return
641  * a buffer size in bytes that guarantees that
642  * psa_sign_hash() will not fail with
643  * #PSA_ERROR_BUFFER_TOO_SMALL.
644  * If the parameters are a valid combination that is not supported
645  * by the implementation, this macro shall return either a
646  * sensible size or 0.
647  * If the parameters are not valid, the
648  * return value is unspecified.
649  */
650 #define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
651  (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
652  (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) : \
653  (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
654  (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
655  (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
656  PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
657  PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
658  0)
659 
660 /** The default nonce size for an AEAD algorithm, in bytes.
661  *
662  * This macro can be used to allocate a buffer of sufficient size to
663  * store the nonce output from #psa_aead_generate_nonce().
664  *
665  * See also #PSA_AEAD_NONCE_MAX_SIZE.
666  *
667  * \note This is not the maximum size of nonce supported as input to #psa_aead_set_nonce(),
668  * #psa_aead_encrypt() or #psa_aead_decrypt(), just the default size that is generated by
669  * #psa_aead_generate_nonce().
670  *
671  * \warning This macro may evaluate its arguments multiple times or
672  * zero times, so you should not pass arguments that contain
673  * side effects.
674  *
675  * \param key_type A symmetric key type that is compatible with algorithm \p alg.
676  *
677  * \param alg An AEAD algorithm (\c PSA_ALG_XXX value such that #PSA_ALG_IS_AEAD(\p alg) is true).
678  *
679  * \return The default nonce size for the specified key type and algorithm.
680  * If the key type or AEAD algorithm is not recognized,
681  * or the parameters are incompatible, return 0.
682  * An implementation can return either 0 or a correct size for a key type
683  * and AEAD algorithm that it recognizes, but does not support.
684  */
685 #define PSA_AEAD_NONCE_LENGTH(key_type, alg) \
686  (PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) == 16 && \
687  (PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg) == PSA_ALG_CCM || \
688  PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg) == PSA_ALG_GCM) ? 12 : \
689  (key_type) == PSA_KEY_TYPE_CHACHA20 && \
690  PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg) == PSA_ALG_CHACHA20_POLY1305 ? 12 : \
691  0)
692 
693 /** The maximum default nonce size among all supported pairs of key types and AEAD algorithms, in bytes.
694  *
695  * This is equal to or greater than any value that #PSA_AEAD_NONCE_LENGTH() may return.
696  *
697  * \note This is not the maximum size of nonce supported as input to #psa_aead_set_nonce(),
698  * #psa_aead_encrypt() or #psa_aead_decrypt(), just the largest size that may be generated by
699  * #psa_aead_generate_nonce().
700  */
701 #define PSA_AEAD_NONCE_MAX_SIZE 12
702 
703 /** The default IV size for a cipher algorithm, in bytes.
704  *
705  * The IV that is generated as part of a call to #psa_cipher_encrypt() is always
706  * the default IV length for the algorithm.
707  *
708  * This macro can be used to allocate a buffer of sufficient size to
709  * store the IV output from #psa_cipher_generate_iv() when using
710  * a multi-part cipher operation.
711  *
712  * See also #PSA_CIPHER_IV_MAX_SIZE.
713  *
714  * \warning This macro may evaluate its arguments multiple times or
715  * zero times, so you should not pass arguments that contain
716  * side effects.
717  *
718  * \param key_type A symmetric key type that is compatible with algorithm \p alg.
719  *
720  * \param alg A cipher algorithm (\c PSA_ALG_XXX value such that #PSA_ALG_IS_CIPHER(\p alg) is true).
721  *
722  * \return The default IV size for the specified key type and algorithm.
723  * If the algorithm does not use an IV, return 0.
724  * If the key type or cipher algorithm is not recognized,
725  * or the parameters are incompatible, return 0.
726  * An implementation can return either 0 or a correct size for a key type
727  * and cipher algorithm that it recognizes, but does not support.
728  */
729 #define PSA_CIPHER_IV_LENGTH(key_type, alg) \
730  (PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) > 1 && \
731  ((alg) == PSA_ALG_CTR || \
732  (alg) == PSA_ALG_CFB || \
733  (alg) == PSA_ALG_OFB || \
734  (alg) == PSA_ALG_XTS || \
735  (alg) == PSA_ALG_CBC_NO_PADDING || \
736  (alg) == PSA_ALG_CBC_PKCS7) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
737  (key_type) == PSA_KEY_TYPE_CHACHA20 && \
738  (alg) == PSA_ALG_STREAM_CIPHER ? 12 : \
739  0)
740 
741 /** The maximum IV size for all supported cipher algorithms, in bytes.
742  *
743  * See also #PSA_CIPHER_IV_LENGTH().
744  */
745 #define PSA_CIPHER_IV_MAX_SIZE 16
746 
747 #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.