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