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