Mbed OS Reference
Loading...
Searching...
No Matches
crypto_sizes.h
Go to the documentation of this file.
1/**
2 * \file
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 */
config.h
Configuration options (set of defines)