TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
crypto_sizes.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
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 
53 #define PSA_HASH_SIZE(alg) \
54  ( \
55  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
56  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
57  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
58  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
59  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
60  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
61  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
62  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
63  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
64  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
65  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
66  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
67  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
68  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
69  PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
70  0)
71 
80 /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
81  * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
82  * HMAC-SHA3-512. */
83 #define PSA_HASH_MAX_SIZE 64
84 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
85 
94 /* All non-HMAC MACs have a maximum size that's smaller than the
95  * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
96 /* Note that the encoding of truncated MAC algorithms limits this value
97  * to 64 bytes.
98  */
99 #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
100 
116 #define PSA_AEAD_TAG_LENGTH(alg) \
117  (PSA_ALG_IS_AEAD(alg) ? \
118  (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
119  0)
120 
121 /* The maximum size of an RSA key on this implementation, in bits.
122  * This is a vendor-specific macro.
123  *
124  * Mbed TLS does not set a hard limit on the size of RSA keys: any key
125  * whose parameters fit in a bignum is accepted. However large keys can
126  * induce a large memory usage and long computation times. Unlike other
127  * auxiliary macros in this file and in crypto.h, which reflect how the
128  * library is configured, this macro defines how the library is
129  * configured. This implementation refuses to import or generate an
130  * RSA key whose size is larger than the value defined here.
131  *
132  * Note that an implementation may set different size limits for different
133  * operations, and does not need to accept all key sizes up to the limit. */
134 #define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
135 
136 /* The maximum size of an ECC key on this implementation, in bits */
137 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
138 
153 #define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
154 
156 #define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
157 
175 #define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
176  ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
177  PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
178  PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
179  ((void)(key_type), (void)(key_bits), 0))
180 
200 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
201  (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
202  (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
203  0)
204 
224 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
225  (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
226  (ciphertext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
227  0)
228 
248 /* For all the AEAD modes defined in this specification, it is possible
249  * to emit output without delay. However, hardware may not always be
250  * capable of this. So for modes based on a block cipher, allow the
251  * implementation to delay the output until it has a full block. */
252 #define PSA_AEAD_UPDATE_OUTPUT_SIZE(alg, input_length) \
253  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
254  PSA_ROUND_UP_TO_MULTIPLE(PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE, (input_length)) : \
255  (input_length))
256 
275 #define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \
276  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
277  PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
278  0)
279 
298 #define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg) \
299  (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
300  PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
301  0)
302 
303 #define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
304  (PSA_ALG_IS_RSA_OAEP(alg) ? \
305  2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
306  11 /*PKCS#1v1.5*/)
307 
316 #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
317  (PSA_BITS_TO_BYTES(curve_bits) * 2)
318 
345 #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
346  (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
347  PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
348  ((void)alg, 0))
349 
350 #define PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE \
351  PSA_ECDSA_SIGNATURE_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)
352 
361 #define PSA_SIGNATURE_MAX_SIZE \
362  (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \
363  PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) : \
364  PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE)
365 
392 #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
393  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
394  ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
395  0)
396 
423 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
424  (PSA_KEY_TYPE_IS_RSA(key_type) ? \
425  PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
426  0)
427 
428 /* Maximum size of the ASN.1 encoding of an INTEGER with the specified
429  * number of bits.
430  *
431  * This definition assumes that bits <= 2^19 - 9 so that the length field
432  * is at most 3 bytes. The length of the encoding is the length of the
433  * bit string padded to a whole number of bytes plus:
434  * - 1 type byte;
435  * - 1 to 3 length bytes;
436  * - 0 to 1 bytes of leading 0 due to the sign bit.
437  */
438 #define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
439  ((bits) / 8 + 5)
440 
441 /* Maximum size of the export encoding of an RSA public key.
442  * Assumes that the public exponent is less than 2^32.
443  *
444  * RSAPublicKey ::= SEQUENCE {
445  * modulus INTEGER, -- n
446  * publicExponent INTEGER } -- e
447  *
448  * - 4 bytes of SEQUENCE overhead;
449  * - n : INTEGER;
450  * - 7 bytes for the public exponent.
451  */
452 #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
453  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
454 
455 /* Maximum size of the export encoding of an RSA key pair.
456  * Assumes thatthe public exponent is less than 2^32 and that the size
457  * difference between the two primes is at most 1 bit.
458  *
459  * RSAPrivateKey ::= SEQUENCE {
460  * version Version, -- 0
461  * modulus INTEGER, -- N-bit
462  * publicExponent INTEGER, -- 32-bit
463  * privateExponent INTEGER, -- N-bit
464  * prime1 INTEGER, -- N/2-bit
465  * prime2 INTEGER, -- N/2-bit
466  * exponent1 INTEGER, -- N/2-bit
467  * exponent2 INTEGER, -- N/2-bit
468  * coefficient INTEGER, -- N/2-bit
469  * }
470  *
471  * - 4 bytes of SEQUENCE overhead;
472  * - 3 bytes of version;
473  * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
474  * overapproximated as 9 half-size INTEGERS;
475  * - 7 bytes for the public exponent.
476  */
477 #define PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) \
478  (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
479 
480 /* Maximum size of the export encoding of a DSA public key.
481  *
482  * SubjectPublicKeyInfo ::= SEQUENCE {
483  * algorithm AlgorithmIdentifier,
484  * subjectPublicKey BIT STRING } -- contains DSAPublicKey
485  * AlgorithmIdentifier ::= SEQUENCE {
486  * algorithm OBJECT IDENTIFIER,
487  * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
488  * DSAPublicKey ::= INTEGER -- public key, Y
489  *
490  * - 3 * 4 bytes of SEQUENCE overhead;
491  * - 1 + 1 + 7 bytes of algorithm (DSA OID);
492  * - 4 bytes of BIT STRING overhead;
493  * - 3 full-size INTEGERs (p, g, y);
494  * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
495  */
496 #define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
497  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
498 
499 /* Maximum size of the export encoding of a DSA key pair.
500  *
501  * DSAPrivateKey ::= SEQUENCE {
502  * version Version, -- 0
503  * prime INTEGER, -- p
504  * subprime INTEGER, -- q
505  * generator INTEGER, -- g
506  * public INTEGER, -- y
507  * private INTEGER, -- x
508  * }
509  *
510  * - 4 bytes of SEQUENCE overhead;
511  * - 3 bytes of version;
512  * - 3 full-size INTEGERs (p, g, y);
513  * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
514  */
515 #define PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) \
516  (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
517 
518 /* Maximum size of the export encoding of an ECC public key.
519  *
520  * The representation of an ECC public key is:
521  * - The byte 0x04;
522  * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
523  * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
524  * - where m is the bit size associated with the curve.
525  *
526  * - 1 byte + 2 * point size.
527  */
528 #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
529  (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
530 
531 /* Maximum size of the export encoding of an ECC key pair.
532  *
533  * An ECC key pair is represented by the secret value.
534  */
535 #define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \
536  (PSA_BITS_TO_BYTES(key_bits))
537 
598 #define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
599  (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
600  (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) : \
601  (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
602  (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
603  (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
604  PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
605  PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
606  0)
607 
608 #endif /* PSA_CRYPTO_SIZES_H */