blob: 4c622394abacc5cc1448c99cb3f26ca3806b5936 [file] [log] [blame]
Antonio de Angelis377a1552018-11-22 17:02:40 +00001/*
Jamie Fox0e54ebc2019-04-09 14:21:04 +01002 * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
Antonio de Angelis377a1552018-11-22 17:02:40 +00003 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 *
6 */
7/**
Jamie Foxcc31d402019-01-28 17:13:52 +00008 * \file psa/crypto_sizes.h
Antonio de Angelis377a1552018-11-22 17:02:40 +00009 *
10 * \brief PSA cryptography module: buffer size macros
11 *
12 * \note This file may not be included directly. Applications must
Jamie Foxcc31d402019-01-28 17:13:52 +000013 * include psa/crypto.h.
Antonio de Angelis377a1552018-11-22 17:02:40 +000014 *
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
Jamie Fox0e54ebc2019-04-09 14:21:04 +010027 * implementation are in crypto.h.
Antonio de Angelis377a1552018-11-22 17:02:40 +000028 */
29
30#ifndef PSA_CRYPTO_SIZES_H
31#define PSA_CRYPTO_SIZES_H
32
Jamie Fox0e54ebc2019-04-09 14:21:04 +010033#define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
34#define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
35
36/** The size of the output of psa_hash_finish(), in bytes.
37 *
38 * This is also the hash size that psa_hash_verify() expects.
39 *
40 * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
41 * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm
42 * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a
43 * hash algorithm).
44 *
45 * \return The hash size for the specified hash algorithm.
46 * If the hash algorithm is not recognized, return 0.
47 * An implementation may return either 0 or the correct size
48 * for a hash algorithm that it recognizes, but does not support.
49 */
50#define PSA_HASH_SIZE(alg) \
51 ( \
52 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
53 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
54 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
55 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
56 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
57 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
58 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
59 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
60 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
61 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
62 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
63 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
64 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
65 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
66 PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
67 0)
68
Antonio de Angelis377a1552018-11-22 17:02:40 +000069/** \def PSA_HASH_MAX_SIZE
70 *
71 * Maximum size of a hash.
72 *
73 * This macro must expand to a compile-time constant integer. This value
74 * should be the maximum size of a hash supported by the implementation,
75 * in bytes, and must be no smaller than this maximum.
76 */
Jamie Fox0e54ebc2019-04-09 14:21:04 +010077/* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
78 * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
79 * HMAC-SHA3-512. */
Antonio de Angelis377a1552018-11-22 17:02:40 +000080#define PSA_HASH_MAX_SIZE 64
81#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
82
83/** \def PSA_MAC_MAX_SIZE
84 *
85 * Maximum size of a MAC.
86 *
87 * This macro must expand to a compile-time constant integer. This value
88 * should be the maximum size of a MAC supported by the implementation,
89 * in bytes, and must be no smaller than this maximum.
90 */
91/* All non-HMAC MACs have a maximum size that's smaller than the
92 * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
Jamie Fox0e54ebc2019-04-09 14:21:04 +010093/* Note that the encoding of truncated MAC algorithms limits this value
94 * to 64 bytes.
95 */
Antonio de Angelis377a1552018-11-22 17:02:40 +000096#define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
97
Jamie Fox0e54ebc2019-04-09 14:21:04 +010098/** The tag size for an AEAD algorithm, in bytes.
99 *
100 * \param alg An AEAD algorithm
101 * (\c PSA_ALG_XXX value such that
102 * #PSA_ALG_IS_AEAD(\p alg) is true).
103 *
104 * \return The tag size for the specified algorithm.
105 * If the AEAD algorithm does not have an identified
106 * tag that can be distinguished from the rest of
107 * the ciphertext, return 0.
108 * If the AEAD algorithm is not recognized, return 0.
109 * An implementation may return either 0 or a
110 * correct size for an AEAD algorithm that it
111 * recognizes, but does not support.
112 */
113#define PSA_AEAD_TAG_LENGTH(alg) \
114 (PSA_ALG_IS_AEAD(alg) ? \
115 (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
116 0)
117
Antonio de Angelis377a1552018-11-22 17:02:40 +0000118/* The maximum size of an RSA key on this implementation, in bits.
119 * This is a vendor-specific macro.
120 *
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100121 * Mbed TLS does not set a hard limit on the size of RSA keys: any key
Antonio de Angelis377a1552018-11-22 17:02:40 +0000122 * whose parameters fit in a bignum is accepted. However large keys can
123 * induce a large memory usage and long computation times. Unlike other
124 * auxiliary macros in this file and in crypto.h, which reflect how the
125 * library is configured, this macro defines how the library is
126 * configured. This implementation refuses to import or generate an
127 * RSA key whose size is larger than the value defined here.
128 *
129 * Note that an implementation may set different size limits for different
130 * operations, and does not need to accept all key sizes up to the limit. */
131#define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
132
133/* The maximum size of an ECC key on this implementation, in bits.
134 * This is a vendor-specific macro. */
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100135#define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
136
137/** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
138 *
139 * This macro returns the maximum length of the PSK supported
140 * by the TLS-1.2 PSK-to-MS key derivation.
141 *
142 * Quoting RFC 4279, Sect 5.3:
143 * TLS implementations supporting these ciphersuites MUST support
144 * arbitrary PSK identities up to 128 octets in length, and arbitrary
145 * PSKs up to 64 octets in length. Supporting longer identities and
146 * keys is RECOMMENDED.
147 *
148 * Therefore, no implementation should define a value smaller than 64
149 * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.
150 */
151#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
Antonio de Angelis377a1552018-11-22 17:02:40 +0000152
153/** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
154 *
155 * Maximum size of an asymmetric signature.
156 *
157 * This macro must expand to a compile-time constant integer. This value
158 * should be the maximum size of a MAC supported by the implementation,
159 * in bytes, and must be no smaller than this maximum.
160 */
161#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
162 PSA_BITS_TO_BYTES( \
163 PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \
164 PSA_VENDOR_RSA_MAX_KEY_BITS : \
165 PSA_VENDOR_ECC_MAX_CURVE_BITS \
166 )
167
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100168/** The maximum size of a block cipher supported by the implementation. */
169#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
Antonio de Angelis377a1552018-11-22 17:02:40 +0000170
171/** The size of the output of psa_mac_sign_finish(), in bytes.
172 *
173 * This is also the MAC size that psa_mac_verify_finish() expects.
174 *
175 * \param key_type The type of the MAC key.
176 * \param key_bits The size of the MAC key in bits.
177 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
178 * #PSA_ALG_IS_MAC(alg) is true).
179 *
180 * \return The MAC size for the specified algorithm with
181 * the specified key parameters.
182 * \return 0 if the MAC algorithm is not recognized.
183 * \return Either 0 or the correct size for a MAC algorithm that
184 * the implementation recognizes, but does not support.
185 * \return Unspecified if the key parameters are not consistent
186 * with the algorithm.
187 */
188#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100189 ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
190 PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
Antonio de Angelis377a1552018-11-22 17:02:40 +0000191 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100192 ((void)(key_type), (void)(key_bits), 0))
Antonio de Angelis377a1552018-11-22 17:02:40 +0000193
194/** The maximum size of the output of psa_aead_encrypt(), in bytes.
195 *
196 * If the size of the ciphertext buffer is at least this large, it is
197 * guaranteed that psa_aead_encrypt() will not fail due to an
198 * insufficient buffer size. Depending on the algorithm, the actual size of
199 * the ciphertext may be smaller.
200 *
201 * \param alg An AEAD algorithm
202 * (\c PSA_ALG_XXX value such that
203 * #PSA_ALG_IS_AEAD(alg) is true).
204 * \param plaintext_length Size of the plaintext in bytes.
205 *
206 * \return The AEAD ciphertext size for the specified
207 * algorithm.
208 * If the AEAD algorithm is not recognized, return 0.
209 * An implementation may return either 0 or a
210 * correct size for an AEAD algorithm that it
211 * recognizes, but does not support.
212 */
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100213#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
214 (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
215 (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
Antonio de Angelis377a1552018-11-22 17:02:40 +0000216 0)
217
218/** The maximum size of the output of psa_aead_decrypt(), in bytes.
219 *
220 * If the size of the plaintext buffer is at least this large, it is
221 * guaranteed that psa_aead_decrypt() will not fail due to an
222 * insufficient buffer size. Depending on the algorithm, the actual size of
223 * the plaintext may be smaller.
224 *
225 * \param alg An AEAD algorithm
226 * (\c PSA_ALG_XXX value such that
227 * #PSA_ALG_IS_AEAD(alg) is true).
228 * \param ciphertext_length Size of the plaintext in bytes.
229 *
230 * \return The AEAD ciphertext size for the specified
231 * algorithm.
232 * If the AEAD algorithm is not recognized, return 0.
233 * An implementation may return either 0 or a
234 * correct size for an AEAD algorithm that it
235 * recognizes, but does not support.
236 */
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100237#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
238 (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
239 (plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
Antonio de Angelis377a1552018-11-22 17:02:40 +0000240 0)
241
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100242#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
243 (PSA_ALG_IS_RSA_OAEP(alg) ? \
244 2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
245 11 /*PKCS#1v1.5*/)
246
247/**
248 * \brief ECDSA signature size for a given curve bit size
249 *
250 * \param curve_bits Curve size in bits.
251 * \return Signature size in bytes.
252 *
253 * \note This macro returns a compile-time constant if its argument is one.
254 */
255#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
256 (PSA_BITS_TO_BYTES(curve_bits) * 2)
257
Antonio de Angelis377a1552018-11-22 17:02:40 +0000258/** Safe signature buffer size for psa_asymmetric_sign().
259 *
260 * This macro returns a safe buffer size for a signature using a key
261 * of the specified type and size, with the specified algorithm.
262 * Note that the actual size of the signature may be smaller
263 * (some algorithms produce a variable-size signature).
264 *
265 * \warning This function may call its arguments multiple times or
266 * zero times, so you should not pass arguments that contain
267 * side effects.
268 *
269 * \param key_type An asymmetric key type (this may indifferently be a
270 * key pair type or a public key type).
271 * \param key_bits The size of the key in bits.
272 * \param alg The signature algorithm.
273 *
274 * \return If the parameters are valid and supported, return
275 * a buffer size in bytes that guarantees that
276 * psa_asymmetric_sign() will not fail with
277 * #PSA_ERROR_BUFFER_TOO_SMALL.
278 * If the parameters are a valid combination that is not supported
279 * by the implementation, this macro either shall return either a
280 * sensible size or 0.
281 * If the parameters are not valid, the
282 * return value is unspecified.
283 */
284#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
285 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
286 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
287 ((void)alg, 0))
288
289/** Safe output buffer size for psa_asymmetric_encrypt().
290 *
291 * This macro returns a safe buffer size for a ciphertext produced using
292 * a key of the specified type and size, with the specified algorithm.
293 * Note that the actual size of the ciphertext may be smaller, depending
294 * on the algorithm.
295 *
296 * \warning This function may call its arguments multiple times or
297 * zero times, so you should not pass arguments that contain
298 * side effects.
299 *
300 * \param key_type An asymmetric key type (this may indifferently be a
301 * key pair type or a public key type).
302 * \param key_bits The size of the key in bits.
303 * \param alg The signature algorithm.
304 *
305 * \return If the parameters are valid and supported, return
306 * a buffer size in bytes that guarantees that
307 * psa_asymmetric_encrypt() will not fail with
308 * #PSA_ERROR_BUFFER_TOO_SMALL.
309 * If the parameters are a valid combination that is not supported
310 * by the implementation, this macro either shall return either a
311 * sensible size or 0.
312 * If the parameters are not valid, the
313 * return value is unspecified.
314 */
315#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
316 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
317 ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
318 0)
319
320/** Safe output buffer size for psa_asymmetric_decrypt().
321 *
322 * This macro returns a safe buffer size for a ciphertext produced using
323 * a key of the specified type and size, with the specified algorithm.
324 * Note that the actual size of the ciphertext may be smaller, depending
325 * on the algorithm.
326 *
327 * \warning This function may call its arguments multiple times or
328 * zero times, so you should not pass arguments that contain
329 * side effects.
330 *
331 * \param key_type An asymmetric key type (this may indifferently be a
332 * key pair type or a public key type).
333 * \param key_bits The size of the key in bits.
334 * \param alg The signature algorithm.
335 *
336 * \return If the parameters are valid and supported, return
337 * a buffer size in bytes that guarantees that
338 * psa_asymmetric_decrypt() will not fail with
339 * #PSA_ERROR_BUFFER_TOO_SMALL.
340 * If the parameters are a valid combination that is not supported
341 * by the implementation, this macro either shall return either a
342 * sensible size or 0.
343 * If the parameters are not valid, the
344 * return value is unspecified.
345 */
346#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
347 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
348 PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
349 0)
350
Jamie Fox0e54ebc2019-04-09 14:21:04 +0100351/* Maximum size of the ASN.1 encoding of an INTEGER with the specified
352 * number of bits.
353 *
354 * This definition assumes that bits <= 2^19 - 9 so that the length field
355 * is at most 3 bytes. The length of the encoding is the length of the
356 * bit string padded to a whole number of bytes plus:
357 * - 1 type byte;
358 * - 1 to 3 length bytes;
359 * - 0 to 1 bytes of leading 0 due to the sign bit.
360 */
361#define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
362 ((bits) / 8 + 5)
363
364/* Maximum size of the export encoding of an RSA public key.
365 * Assumes that the public exponent is less than 2^32.
366 *
367 * RSAPublicKey ::= SEQUENCE {
368 * modulus INTEGER, -- n
369 * publicExponent INTEGER } -- e
370 *
371 * - 4 bytes of SEQUENCE overhead;
372 * - n : INTEGER;
373 * - 7 bytes for the public exponent.
374 */
375#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
376 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
377
378/* Maximum size of the export encoding of an RSA key pair.
379 * Assumes thatthe public exponent is less than 2^32 and that the size
380 * difference between the two primes is at most 1 bit.
381 *
382 * RSAPrivateKey ::= SEQUENCE {
383 * version Version, -- 0
384 * modulus INTEGER, -- N-bit
385 * publicExponent INTEGER, -- 32-bit
386 * privateExponent INTEGER, -- N-bit
387 * prime1 INTEGER, -- N/2-bit
388 * prime2 INTEGER, -- N/2-bit
389 * exponent1 INTEGER, -- N/2-bit
390 * exponent2 INTEGER, -- N/2-bit
391 * coefficient INTEGER, -- N/2-bit
392 * }
393 *
394 * - 4 bytes of SEQUENCE overhead;
395 * - 3 bytes of version;
396 * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
397 * overapproximated as 9 half-size INTEGERS;
398 * - 7 bytes for the public exponent.
399 */
400#define PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) \
401 (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
402
403/* Maximum size of the export encoding of a DSA public key.
404 *
405 * SubjectPublicKeyInfo ::= SEQUENCE {
406 * algorithm AlgorithmIdentifier,
407 * subjectPublicKey BIT STRING } -- contains DSAPublicKey
408 * AlgorithmIdentifier ::= SEQUENCE {
409 * algorithm OBJECT IDENTIFIER,
410 * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
411 * DSAPublicKey ::= INTEGER -- public key, Y
412 *
413 * - 3 * 4 bytes of SEQUENCE overhead;
414 * - 1 + 1 + 7 bytes of algorithm (DSA OID);
415 * - 4 bytes of BIT STRING overhead;
416 * - 3 full-size INTEGERs (p, g, y);
417 * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
418 */
419#define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
420 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
421
422/* Maximum size of the export encoding of a DSA key pair.
423 *
424 * DSAPrivateKey ::= SEQUENCE {
425 * version Version, -- 0
426 * prime INTEGER, -- p
427 * subprime INTEGER, -- q
428 * generator INTEGER, -- g
429 * public INTEGER, -- y
430 * private INTEGER, -- x
431 * }
432 *
433 * - 4 bytes of SEQUENCE overhead;
434 * - 3 bytes of version;
435 * - 3 full-size INTEGERs (p, g, y);
436 * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
437 */
438#define PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) \
439 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
440
441/* Maximum size of the export encoding of an ECC public key.
442 *
443 * The representation of an ECC public key is:
444 * - The byte 0x04;
445 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
446 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
447 * - where m is the bit size associated with the curve.
448 *
449 * - 1 byte + 2 * point size.
450 */
451#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
452 (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
453
454/* Maximum size of the export encoding of an ECC key pair.
455 *
456 * An ECC key pair is represented by the secret value.
457 */
458#define PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) \
459 (PSA_BITS_TO_BYTES(key_bits))
460
461/** Safe output buffer size for psa_export_key() or psa_export_public_key().
462 *
463 * This macro returns a compile-time constant if its arguments are
464 * compile-time constants.
465 *
466 * \warning This function may call its arguments multiple times or
467 * zero times, so you should not pass arguments that contain
468 * side effects.
469 *
470 * The following code illustrates how to allocate enough memory to export
471 * a key by querying the key type and size at runtime.
472 * \code{c}
473 * psa_key_type_t key_type;
474 * size_t key_bits;
475 * psa_status_t status;
476 * status = psa_get_key_information(key, &key_type, &key_bits);
477 * if (status != PSA_SUCCESS) handle_error(...);
478 * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
479 * unsigned char *buffer = malloc(buffer_size);
480 * if (buffer != NULL) handle_error(...);
481 * size_t buffer_length;
482 * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
483 * if (status != PSA_SUCCESS) handle_error(...);
484 * \endcode
485 *
486 * For psa_export_public_key(), calculate the buffer size from the
487 * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR
488 * to convert a key pair type to the corresponding public key type.
489 * \code{c}
490 * psa_key_type_t key_type;
491 * size_t key_bits;
492 * psa_status_t status;
493 * status = psa_get_key_information(key, &key_type, &key_bits);
494 * if (status != PSA_SUCCESS) handle_error(...);
495 * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(key_type);
496 * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
497 * unsigned char *buffer = malloc(buffer_size);
498 * if (buffer != NULL) handle_error(...);
499 * size_t buffer_length;
500 * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
501 * if (status != PSA_SUCCESS) handle_error(...);
502 * \endcode
503 *
504 * \param key_type A supported key type.
505 * \param key_bits The size of the key in bits.
506 *
507 * \return If the parameters are valid and supported, return
508 * a buffer size in bytes that guarantees that
509 * psa_asymmetric_sign() will not fail with
510 * #PSA_ERROR_BUFFER_TOO_SMALL.
511 * If the parameters are a valid combination that is not supported
512 * by the implementation, this macro either shall return either a
513 * sensible size or 0.
514 * If the parameters are not valid, the
515 * return value is unspecified.
516 */
517#define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
518 (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
519 (key_type) == PSA_KEY_TYPE_RSA_KEYPAIR ? PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) : \
520 (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
521 (key_type) == PSA_KEY_TYPE_DSA_KEYPAIR ? PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) : \
522 (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
523 PSA_KEY_TYPE_IS_ECC_KEYPAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) : \
524 PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
525 0)
526
Antonio de Angelis377a1552018-11-22 17:02:40 +0000527#endif /* PSA_CRYPTO_SIZES_H */