blob: edb240be0815560bfceb6cea0a970b809a66599a [file] [log] [blame]
Gilles Peskine0cad07c2018-06-27 19:49:02 +02001/**
2 * \file psa/crypto_sizes.h
3 *
4 * \brief PSA cryptography module: Mbed TLS buffer size macros
5 *
Gilles Peskine07c91f52018-06-28 18:02:53 +02006 * \note This file may not be included directly. Applications must
7 * include psa/crypto.h.
8 *
Gilles Peskine0cad07c2018-06-27 19:49:02 +02009 * 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.
Gilles Peskine49cee6c2018-06-27 21:03:58 +020014 *
Gilles Peskine07c91f52018-06-28 18:02:53 +020015 * 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 *
Gilles Peskine49cee6c2018-06-27 21:03:58 +020020 * Macros that compute sizes whose values do not depend on the
21 * implementation are in crypto.h.
Gilles Peskine0cad07c2018-06-27 19:49:02 +020022 */
23/*
24 * Copyright (C) 2018, ARM Limited, All Rights Reserved
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 * This file is part of mbed TLS (https://tls.mbed.org)
40 */
41
42#ifndef PSA_CRYPTO_SIZES_H
43#define PSA_CRYPTO_SIZES_H
44
45/* Include the Mbed TLS configuration file, the way Mbed TLS does it
46 * in each of its header files. */
47#if !defined(MBEDTLS_CONFIG_FILE)
48#include "../mbedtls/config.h"
49#else
50#include MBEDTLS_CONFIG_FILE
51#endif
52
Gilles Peskineaf3baab2018-06-27 22:55:52 +020053/** \def PSA_HASH_MAX_SIZE
54 *
55 * Maximum size of a hash.
56 *
57 * This macro must expand to a compile-time constant integer. This value
58 * should be the maximum size of a hash supported by the implementation,
59 * in bytes, and must be no smaller than this maximum.
60 */
Gilles Peskine3052f532018-09-17 14:13:26 +020061/* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
62 * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
63 * HMAC-SHA3-512. */
Gilles Peskine0cad07c2018-06-27 19:49:02 +020064#if defined(MBEDTLS_SHA512_C)
65#define PSA_HASH_MAX_SIZE 64
66#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
67#else
68#define PSA_HASH_MAX_SIZE 32
69#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 64
70#endif
71
Gilles Peskineaf3baab2018-06-27 22:55:52 +020072/** \def PSA_MAC_MAX_SIZE
73 *
74 * Maximum size of a MAC.
75 *
76 * This macro must expand to a compile-time constant integer. This value
77 * should be the maximum size of a MAC supported by the implementation,
78 * in bytes, and must be no smaller than this maximum.
79 */
80/* All non-HMAC MACs have a maximum size that's smaller than the
81 * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
82#define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
83
84/* The maximum size of an RSA key on this implementation, in bits.
85 * This is a vendor-specific macro.
86 *
87 * Mbed TLS does not set a hard limit on the size of RSA keys: any key
88 * whose parameters fit in a bignum is accepted. However large keys can
89 * induce a large memory usage and long computation times. Unlike other
90 * auxiliary macros in this file and in crypto.h, which reflect how the
91 * library is configured, this macro defines how the library is
92 * configured. This implementation refuses to import or generate an
93 * RSA key whose size is larger than the value defined here.
94 *
95 * Note that an implementation may set different size limits for different
96 * operations, and does not need to accept all key sizes up to the limit. */
97#define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
98
99/* The maximum size of an ECC key on this implementation, in bits.
100 * This is a vendor-specific macro. */
101#if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
102#define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
103#elif defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
104#define PSA_VENDOR_ECC_MAX_CURVE_BITS 512
105#elif defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
106#define PSA_VENDOR_ECC_MAX_CURVE_BITS 448
107#elif defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
108#define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
109#elif defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
110#define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
111#elif defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
112#define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
113#elif defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
114#define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
115#elif defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
116#define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
117#elif defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED)
118#define PSA_VENDOR_ECC_MAX_CURVE_BITS 255
119#elif defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
120#define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
121#elif defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
122#define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
123#elif defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
124#define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
125#elif defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
126#define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
127#else
128#define PSA_VENDOR_ECC_MAX_CURVE_BITS 0
129#endif
130
131/** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
132 *
133 * Maximum size of an asymmetric signature.
134 *
135 * This macro must expand to a compile-time constant integer. This value
136 * should be the maximum size of a MAC supported by the implementation,
137 * in bytes, and must be no smaller than this maximum.
138 */
139#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
140 PSA_BITS_TO_BYTES( \
141 PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \
142 PSA_VENDOR_RSA_MAX_KEY_BITS : \
143 PSA_VENDOR_ECC_MAX_CURVE_BITS \
144 )
145
146
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200147
Gilles Peskineacd4be32018-07-08 19:56:25 +0200148/** The size of the output of psa_mac_sign_finish(), in bytes.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200149 *
Gilles Peskineacd4be32018-07-08 19:56:25 +0200150 * This is also the MAC size that psa_mac_verify_finish() expects.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200151 *
152 * \param key_type The type of the MAC key.
153 * \param key_bits The size of the MAC key in bits.
154 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
155 * #PSA_ALG_IS_MAC(alg) is true).
156 *
157 * \return The MAC size for the specified algorithm with
158 * the specified key parameters.
159 * \return 0 if the MAC algorithm is not recognized.
160 * \return Either 0 or the correct size for a MAC algorithm that
161 * the implementation recognizes, but does not support.
162 * \return Unspecified if the key parameters are not consistent
163 * with the algorithm.
164 */
165#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
Gilles Peskine00709fa2018-08-22 18:25:41 +0200166 (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200167 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
Gilles Peskine35fe2032018-08-22 18:26:02 +0200168 ((void)(key_type), (void)(key_bits), 0))
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200169
170/** The maximum size of the output of psa_aead_encrypt(), in bytes.
171 *
172 * If the size of the ciphertext buffer is at least this large, it is
173 * guaranteed that psa_aead_encrypt() will not fail due to an
174 * insufficient buffer size. Depending on the algorithm, the actual size of
175 * the ciphertext may be smaller.
176 *
177 * \param alg An AEAD algorithm
178 * (\c PSA_ALG_XXX value such that
179 * #PSA_ALG_IS_AEAD(alg) is true).
180 * \param plaintext_length Size of the plaintext in bytes.
181 *
182 * \return The AEAD ciphertext size for the specified
183 * algorithm.
184 * If the AEAD algorithm is not recognized, return 0.
185 * An implementation may return either 0 or a
186 * correct size for an AEAD algorithm that it
187 * recognizes, but does not support.
188 */
189#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
190 (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
191 (plaintext_length) + PSA_AEAD_TAG_SIZE(alg) : \
192 0)
193
194/** The maximum size of the output of psa_aead_decrypt(), in bytes.
195 *
196 * If the size of the plaintext buffer is at least this large, it is
197 * guaranteed that psa_aead_decrypt() will not fail due to an
198 * insufficient buffer size. Depending on the algorithm, the actual size of
199 * the plaintext 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 ciphertext_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 */
213#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
214 (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
215 (plaintext_length) - PSA_AEAD_TAG_SIZE(alg) : \
216 0)
217
218/** Safe signature buffer size for psa_asymmetric_sign().
219 *
220 * This macro returns a safe buffer size for a signature using a key
221 * of the specified type and size, with the specified algorithm.
222 * Note that the actual size of the signature may be smaller
223 * (some algorithms produce a variable-size signature).
224 *
225 * \warning This function may call its arguments multiple times or
226 * zero times, so you should not pass arguments that contain
227 * side effects.
228 *
229 * \param key_type An asymmetric key type (this may indifferently be a
230 * key pair type or a public key type).
231 * \param key_bits The size of the key in bits.
232 * \param alg The signature algorithm.
233 *
234 * \return If the parameters are valid and supported, return
235 * a buffer size in bytes that guarantees that
236 * psa_asymmetric_sign() will not fail with
237 * #PSA_ERROR_BUFFER_TOO_SMALL.
238 * If the parameters are a valid combination that is not supported
239 * by the implementation, this macro either shall return either a
240 * sensible size or 0.
241 * If the parameters are not valid, the
242 * return value is unspecified.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200243 */
244#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
245 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
246 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
247 ((void)alg, 0))
248
Gilles Peskinedcd14942018-07-12 00:30:52 +0200249/** Safe output buffer size for psa_asymmetric_encrypt().
250 *
251 * This macro returns a safe buffer size for a ciphertext produced using
252 * a key of the specified type and size, with the specified algorithm.
253 * Note that the actual size of the ciphertext may be smaller, depending
254 * on the algorithm.
255 *
256 * \warning This function may call its arguments multiple times or
257 * zero times, so you should not pass arguments that contain
258 * side effects.
259 *
260 * \param key_type An asymmetric key type (this may indifferently be a
261 * key pair type or a public key type).
262 * \param key_bits The size of the key in bits.
263 * \param alg The signature algorithm.
264 *
265 * \return If the parameters are valid and supported, return
266 * a buffer size in bytes that guarantees that
267 * psa_asymmetric_encrypt() will not fail with
268 * #PSA_ERROR_BUFFER_TOO_SMALL.
269 * If the parameters are a valid combination that is not supported
270 * by the implementation, this macro either shall return either a
271 * sensible size or 0.
272 * If the parameters are not valid, the
273 * return value is unspecified.
274 */
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200275#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
276 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
277 ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
278 0)
Gilles Peskinedcd14942018-07-12 00:30:52 +0200279
280/** Safe output buffer size for psa_asymmetric_decrypt().
281 *
282 * This macro returns a safe buffer size for a ciphertext produced using
283 * a key of the specified type and size, with the specified algorithm.
284 * Note that the actual size of the ciphertext may be smaller, depending
285 * on the algorithm.
286 *
287 * \warning This function may call its arguments multiple times or
288 * zero times, so you should not pass arguments that contain
289 * side effects.
290 *
291 * \param key_type An asymmetric key type (this may indifferently be a
292 * key pair type or a public key type).
293 * \param key_bits The size of the key in bits.
294 * \param alg The signature algorithm.
295 *
296 * \return If the parameters are valid and supported, return
297 * a buffer size in bytes that guarantees that
298 * psa_asymmetric_decrypt() will not fail with
299 * #PSA_ERROR_BUFFER_TOO_SMALL.
300 * If the parameters are a valid combination that is not supported
301 * by the implementation, this macro either shall return either a
302 * sensible size or 0.
303 * If the parameters are not valid, the
304 * return value is unspecified.
305 */
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200306#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
307 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
308 PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
309 0)
310
Gilles Peskine1be949b2018-08-10 19:06:59 +0200311/* Maximum size of the ASN.1 encoding of an INTEGER with the specified
312 * number of bits.
313 *
314 * This definition assumes that bits <= 2^19 - 9 so that the length field
315 * is at most 3 bytes. The length of the encoding is the length of the
316 * bit string padded to a whole number of bytes plus:
317 * - 1 type byte;
318 * - 1 to 3 length bytes;
319 * - 0 to 1 bytes of leading 0 due to the sign bit.
320 */
321#define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
322 ((bits) / 8 + 5)
323
324/* Maximum size of the export encoding of an RSA public key.
325 * Assumes that the public exponent is less than 2^32.
326 *
327 * SubjectPublicKeyInfo ::= SEQUENCE {
328 * algorithm AlgorithmIdentifier,
329 * subjectPublicKey BIT STRING } -- contains RSAPublicKey
330 * AlgorithmIdentifier ::= SEQUENCE {
331 * algorithm OBJECT IDENTIFIER,
332 * parameters NULL }
333 * RSAPublicKey ::= SEQUENCE {
334 * modulus INTEGER, -- n
335 * publicExponent INTEGER } -- e
336 *
337 * - 3 * 4 bytes of SEQUENCE overhead;
338 * - 1 + 1 + 9 bytes of algorithm (RSA OID);
339 * - 2 bytes of NULL;
340 * - 4 bytes of BIT STRING overhead;
341 * - n : INTEGER;
342 * - 7 bytes for the public exponent.
343 */
344#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
345 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
346
347/* Maximum size of the export encoding of an RSA key pair.
348 * Assumes thatthe public exponent is less than 2^32 and that the size
349 * difference between the two primes is at most 1 bit.
350 *
351 * RSAPrivateKey ::= SEQUENCE {
352 * version Version, -- 0
353 * modulus INTEGER, -- N-bit
354 * publicExponent INTEGER, -- 32-bit
355 * privateExponent INTEGER, -- N-bit
356 * prime1 INTEGER, -- N/2-bit
357 * prime2 INTEGER, -- N/2-bit
358 * exponent1 INTEGER, -- N/2-bit
359 * exponent2 INTEGER, -- N/2-bit
360 * coefficient INTEGER, -- N/2-bit
361 * }
362 *
363 * - 4 bytes of SEQUENCE overhead;
364 * - 3 bytes of version;
365 * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
366 * overapproximated as 9 half-size INTEGERS;
367 * - 7 bytes for the public exponent.
368 */
369#define PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) \
370 (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
371
372/* Maximum size of the export encoding of a DSA public key.
373 *
374 * SubjectPublicKeyInfo ::= SEQUENCE {
375 * algorithm AlgorithmIdentifier,
376 * subjectPublicKey BIT STRING } -- contains DSAPublicKey
377 * AlgorithmIdentifier ::= SEQUENCE {
378 * algorithm OBJECT IDENTIFIER,
379 * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
380 * DSAPublicKey ::= INTEGER -- public key, Y
381 *
382 * - 3 * 4 bytes of SEQUENCE overhead;
383 * - 1 + 1 + 7 bytes of algorithm (DSA OID);
384 * - 4 bytes of BIT STRING overhead;
385 * - 3 full-size INTEGERs (p, g, y);
386 * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
387 */
388#define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
389 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
390
391/* Maximum size of the export encoding of a DSA key pair.
392 *
393 * DSAPrivateKey ::= SEQUENCE {
394 * version Version, -- 0
395 * prime INTEGER, -- p
396 * subprime INTEGER, -- q
397 * generator INTEGER, -- g
398 * public INTEGER, -- y
399 * private INTEGER, -- x
400 * }
401 *
402 * - 4 bytes of SEQUENCE overhead;
403 * - 3 bytes of version;
404 * - 3 full-size INTEGERs (p, g, y);
405 * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
406 */
407#define PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) \
408 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
409
410/* Maximum size of the export encoding of an ECC public key.
411 *
412 * SubjectPublicKeyInfo ::= SEQUENCE {
413 * algorithm AlgorithmIdentifier,
414 * subjectPublicKey BIT STRING } -- contains ECPoint
415 * AlgorithmIdentifier ::= SEQUENCE {
416 * algorithm OBJECT IDENTIFIER,
417 * parameters OBJECT IDENTIFIER } -- namedCurve
Gilles Peskinecb6adbb2018-08-11 01:18:12 +0200418 * ECPoint ::= ...
419 * -- first 8 bits: 0x04;
420 * -- then x_P as an n-bit string, big endian;
421 * -- then y_P as a n-bit string, big endian,
Gilles Peskine1be949b2018-08-10 19:06:59 +0200422 * -- where n is the order of the curve.
423 *
424 * - 2 * 4 bytes of SEQUENCE overhead;
425 * - 1 + 1 + 7 bytes of algorithm (id-ecPublicKey OID);
426 * - 1 + 1 + 12 bytes of namedCurve OID;
427 * - 4 bytes of BIT STRING overhead;
428 * - 1 byte + 2 * point size in ECPoint.
429 */
430#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
431 (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
432
433/* Maximum size of the export encoding of an ECC key pair.
434 *
435 * ECPrivateKey ::= SEQUENCE {
436 * version INTEGER, -- must be 1
437 * privateKey OCTET STRING,
Gilles Peskinecb6adbb2018-08-11 01:18:12 +0200438 * -- `ceiling(log2(n)/8)`-byte string, big endian,
Gilles Peskine1be949b2018-08-10 19:06:59 +0200439 * -- where n is the order of the curve.
Gilles Peskinecb6adbb2018-08-11 01:18:12 +0200440 * parameters [0] IMPLICIT ECParameters {{ NamedCurve }},
441 * publicKey [1] IMPLICIT BIT STRING
Gilles Peskine1be949b2018-08-10 19:06:59 +0200442 * }
443 *
444 * - 4 bytes of SEQUENCE overhead;
445 * - 1 * point size in privateKey
446 * - 1 + 1 + 12 bytes of namedCurve OID;
447 * - 4 bytes of BIT STRING overhead;
448 * - public key as for #PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE.
449 */
450#define PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) \
451 (3 * PSA_BITS_TO_BYTES(key_bits) + 56)
452
453/** Safe output buffer size for psa_export_key() or psa_export_public_key().
454 *
455 * This macro returns a compile-time constant if its arguments are
456 * compile-time constants.
457 *
458 * \warning This function may call its arguments multiple times or
459 * zero times, so you should not pass arguments that contain
460 * side effects.
461 *
462 * The following code illustrates how to allocate enough memory to export
463 * a key by querying the key type and size at runtime.
464 * \code{c}
465 * psa_key_type_t key_type;
466 * size_t key_bits;
467 * psa_status_t status;
468 * status = psa_get_key_information(key, &key_type, &key_bits);
469 * if (status != PSA_SUCCESS) handle_error(...);
470 * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
471 * unsigned char *buffer = malloc(buffer_size);
472 * if (buffer != NULL) handle_error(...);
473 * size_t buffer_length;
474 * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
475 * if (status != PSA_SUCCESS) handle_error(...);
476 * \endcode
477 *
478 * For psa_export_public_key(), calculate the buffer size from the
479 * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR
480 * to convert a key pair type to the corresponding public key type.
481 * \code{c}
482 * psa_key_type_t key_type;
483 * size_t key_bits;
484 * psa_status_t status;
485 * status = psa_get_key_information(key, &key_type, &key_bits);
486 * if (status != PSA_SUCCESS) handle_error(...);
487 * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(key_type);
488 * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
489 * unsigned char *buffer = malloc(buffer_size);
490 * if (buffer != NULL) handle_error(...);
491 * size_t buffer_length;
492 * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
493 * if (status != PSA_SUCCESS) handle_error(...);
494 * \endcode
495 *
496 * \param key_type A supported key type.
497 * \param key_bits The size of the key in bits.
Gilles Peskine1be949b2018-08-10 19:06:59 +0200498 *
499 * \return If the parameters are valid and supported, return
500 * a buffer size in bytes that guarantees that
501 * psa_asymmetric_sign() will not fail with
502 * #PSA_ERROR_BUFFER_TOO_SMALL.
503 * If the parameters are a valid combination that is not supported
504 * by the implementation, this macro either shall return either a
505 * sensible size or 0.
506 * If the parameters are not valid, the
507 * return value is unspecified.
508 */
509#define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
510 (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
511 (key_type) == PSA_KEY_TYPE_RSA_KEYPAIR ? PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) : \
512 (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
513 (key_type) == PSA_KEY_TYPE_DSA_KEYPAIR ? PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) : \
514 (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
515 PSA_KEY_TYPE_IS_ECC_KEYPAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) : \
516 PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
517 0)
518
Gilles Peskine0cad07c2018-06-27 19:49:02 +0200519#endif /* PSA_CRYPTO_SIZES_H */