blob: 7e1795673679f040d963f0628ffe3c6699c27abc [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
Hanno Becker8dbfca42018-10-12 11:56:55 +0100134/** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
135 *
136 * This macro returns the maximum length of the PSK supported
137 * by the TLS-1.2 PSK-to-MS key derivation.
138 *
139 * Quoting RFC 4279, Sect 5.3:
140 * TLS implementations supporting these ciphersuites MUST support
141 * arbitrary PSK identities up to 128 octets in length, and arbitrary
142 * PSKs up to 64 octets in length. Supporting longer identities and
143 * keys is RECOMMENDED.
144 *
145 * Therefore, no implementation should define a value smaller than 64
146 * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.
147 */
148#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
149
Gilles Peskineaf3baab2018-06-27 22:55:52 +0200150/** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
151 *
152 * Maximum size of an asymmetric signature.
153 *
154 * This macro must expand to a compile-time constant integer. This value
155 * should be the maximum size of a MAC supported by the implementation,
156 * in bytes, and must be no smaller than this maximum.
157 */
158#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
159 PSA_BITS_TO_BYTES( \
160 PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \
161 PSA_VENDOR_RSA_MAX_KEY_BITS : \
162 PSA_VENDOR_ECC_MAX_CURVE_BITS \
163 )
164
Gilles Peskined911eb72018-08-14 15:18:45 +0200165/** The maximum size of a block cipher supported by the implementation. */
166#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200167
Gilles Peskineacd4be32018-07-08 19:56:25 +0200168/** The size of the output of psa_mac_sign_finish(), in bytes.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200169 *
Gilles Peskineacd4be32018-07-08 19:56:25 +0200170 * This is also the MAC size that psa_mac_verify_finish() expects.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200171 *
172 * \param key_type The type of the MAC key.
173 * \param key_bits The size of the MAC key in bits.
174 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
175 * #PSA_ALG_IS_MAC(alg) is true).
176 *
177 * \return The MAC size for the specified algorithm with
178 * the specified key parameters.
179 * \return 0 if the MAC algorithm is not recognized.
180 * \return Either 0 or the correct size for a MAC algorithm that
181 * the implementation recognizes, but does not support.
182 * \return Unspecified if the key parameters are not consistent
183 * with the algorithm.
184 */
185#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
Gilles Peskined911eb72018-08-14 15:18:45 +0200186 ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
187 PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200188 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
Gilles Peskine35fe2032018-08-22 18:26:02 +0200189 ((void)(key_type), (void)(key_bits), 0))
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200190
191/** The maximum size of the output of psa_aead_encrypt(), in bytes.
192 *
193 * If the size of the ciphertext buffer is at least this large, it is
194 * guaranteed that psa_aead_encrypt() will not fail due to an
195 * insufficient buffer size. Depending on the algorithm, the actual size of
196 * the ciphertext 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 plaintext_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 */
Gilles Peskine23cc2ff2018-08-17 19:47:52 +0200210#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
211 (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
212 (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200213 0)
214
215/** The maximum size of the output of psa_aead_decrypt(), in bytes.
216 *
217 * If the size of the plaintext buffer is at least this large, it is
218 * guaranteed that psa_aead_decrypt() will not fail due to an
219 * insufficient buffer size. Depending on the algorithm, the actual size of
220 * the plaintext may be smaller.
221 *
222 * \param alg An AEAD algorithm
223 * (\c PSA_ALG_XXX value such that
224 * #PSA_ALG_IS_AEAD(alg) is true).
225 * \param ciphertext_length Size of the plaintext in bytes.
226 *
227 * \return The AEAD ciphertext size for the specified
228 * algorithm.
229 * If the AEAD algorithm is not recognized, return 0.
230 * An implementation may return either 0 or a
231 * correct size for an AEAD algorithm that it
232 * recognizes, but does not support.
233 */
Gilles Peskine23cc2ff2018-08-17 19:47:52 +0200234#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
235 (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
236 (plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200237 0)
238
239/** Safe signature buffer size for psa_asymmetric_sign().
240 *
241 * This macro returns a safe buffer size for a signature using a key
242 * of the specified type and size, with the specified algorithm.
243 * Note that the actual size of the signature may be smaller
244 * (some algorithms produce a variable-size signature).
245 *
246 * \warning This function may call its arguments multiple times or
247 * zero times, so you should not pass arguments that contain
248 * side effects.
249 *
250 * \param key_type An asymmetric key type (this may indifferently be a
251 * key pair type or a public key type).
252 * \param key_bits The size of the key in bits.
253 * \param alg The signature algorithm.
254 *
255 * \return If the parameters are valid and supported, return
256 * a buffer size in bytes that guarantees that
257 * psa_asymmetric_sign() will not fail with
258 * #PSA_ERROR_BUFFER_TOO_SMALL.
259 * If the parameters are a valid combination that is not supported
260 * by the implementation, this macro either shall return either a
261 * sensible size or 0.
262 * If the parameters are not valid, the
263 * return value is unspecified.
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200264 */
265#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
266 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
267 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
268 ((void)alg, 0))
269
Gilles Peskinedcd14942018-07-12 00:30:52 +0200270/** Safe output buffer size for psa_asymmetric_encrypt().
271 *
272 * This macro returns a safe buffer size for a ciphertext produced using
273 * a key of the specified type and size, with the specified algorithm.
274 * Note that the actual size of the ciphertext may be smaller, depending
275 * on the algorithm.
276 *
277 * \warning This function may call its arguments multiple times or
278 * zero times, so you should not pass arguments that contain
279 * side effects.
280 *
281 * \param key_type An asymmetric key type (this may indifferently be a
282 * key pair type or a public key type).
283 * \param key_bits The size of the key in bits.
284 * \param alg The signature algorithm.
285 *
286 * \return If the parameters are valid and supported, return
287 * a buffer size in bytes that guarantees that
288 * psa_asymmetric_encrypt() will not fail with
289 * #PSA_ERROR_BUFFER_TOO_SMALL.
290 * If the parameters are a valid combination that is not supported
291 * by the implementation, this macro either shall return either a
292 * sensible size or 0.
293 * If the parameters are not valid, the
294 * return value is unspecified.
295 */
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200296#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
297 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
298 ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
299 0)
Gilles Peskinedcd14942018-07-12 00:30:52 +0200300
301/** Safe output buffer size for psa_asymmetric_decrypt().
302 *
303 * This macro returns a safe buffer size for a ciphertext produced using
304 * a key of the specified type and size, with the specified algorithm.
305 * Note that the actual size of the ciphertext may be smaller, depending
306 * on the algorithm.
307 *
308 * \warning This function may call its arguments multiple times or
309 * zero times, so you should not pass arguments that contain
310 * side effects.
311 *
312 * \param key_type An asymmetric key type (this may indifferently be a
313 * key pair type or a public key type).
314 * \param key_bits The size of the key in bits.
315 * \param alg The signature algorithm.
316 *
317 * \return If the parameters are valid and supported, return
318 * a buffer size in bytes that guarantees that
319 * psa_asymmetric_decrypt() will not fail with
320 * #PSA_ERROR_BUFFER_TOO_SMALL.
321 * If the parameters are a valid combination that is not supported
322 * by the implementation, this macro either shall return either a
323 * sensible size or 0.
324 * If the parameters are not valid, the
325 * return value is unspecified.
326 */
Gilles Peskine49cee6c2018-06-27 21:03:58 +0200327#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
328 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
329 PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
330 0)
331
Gilles Peskine1be949b2018-08-10 19:06:59 +0200332/* Maximum size of the ASN.1 encoding of an INTEGER with the specified
333 * number of bits.
334 *
335 * This definition assumes that bits <= 2^19 - 9 so that the length field
336 * is at most 3 bytes. The length of the encoding is the length of the
337 * bit string padded to a whole number of bytes plus:
338 * - 1 type byte;
339 * - 1 to 3 length bytes;
340 * - 0 to 1 bytes of leading 0 due to the sign bit.
341 */
342#define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \
343 ((bits) / 8 + 5)
344
345/* Maximum size of the export encoding of an RSA public key.
346 * Assumes that the public exponent is less than 2^32.
347 *
348 * SubjectPublicKeyInfo ::= SEQUENCE {
349 * algorithm AlgorithmIdentifier,
350 * subjectPublicKey BIT STRING } -- contains RSAPublicKey
351 * AlgorithmIdentifier ::= SEQUENCE {
352 * algorithm OBJECT IDENTIFIER,
353 * parameters NULL }
354 * RSAPublicKey ::= SEQUENCE {
355 * modulus INTEGER, -- n
356 * publicExponent INTEGER } -- e
357 *
358 * - 3 * 4 bytes of SEQUENCE overhead;
359 * - 1 + 1 + 9 bytes of algorithm (RSA OID);
360 * - 2 bytes of NULL;
361 * - 4 bytes of BIT STRING overhead;
362 * - n : INTEGER;
363 * - 7 bytes for the public exponent.
364 */
365#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
366 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
367
368/* Maximum size of the export encoding of an RSA key pair.
369 * Assumes thatthe public exponent is less than 2^32 and that the size
370 * difference between the two primes is at most 1 bit.
371 *
372 * RSAPrivateKey ::= SEQUENCE {
373 * version Version, -- 0
374 * modulus INTEGER, -- N-bit
375 * publicExponent INTEGER, -- 32-bit
376 * privateExponent INTEGER, -- N-bit
377 * prime1 INTEGER, -- N/2-bit
378 * prime2 INTEGER, -- N/2-bit
379 * exponent1 INTEGER, -- N/2-bit
380 * exponent2 INTEGER, -- N/2-bit
381 * coefficient INTEGER, -- N/2-bit
382 * }
383 *
384 * - 4 bytes of SEQUENCE overhead;
385 * - 3 bytes of version;
386 * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
387 * overapproximated as 9 half-size INTEGERS;
388 * - 7 bytes for the public exponent.
389 */
390#define PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) \
391 (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
392
393/* Maximum size of the export encoding of a DSA public key.
394 *
395 * SubjectPublicKeyInfo ::= SEQUENCE {
396 * algorithm AlgorithmIdentifier,
397 * subjectPublicKey BIT STRING } -- contains DSAPublicKey
398 * AlgorithmIdentifier ::= SEQUENCE {
399 * algorithm OBJECT IDENTIFIER,
400 * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs
401 * DSAPublicKey ::= INTEGER -- public key, Y
402 *
403 * - 3 * 4 bytes of SEQUENCE overhead;
404 * - 1 + 1 + 7 bytes of algorithm (DSA OID);
405 * - 4 bytes of BIT STRING overhead;
406 * - 3 full-size INTEGERs (p, g, y);
407 * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
408 */
409#define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
410 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
411
412/* Maximum size of the export encoding of a DSA key pair.
413 *
414 * DSAPrivateKey ::= SEQUENCE {
415 * version Version, -- 0
416 * prime INTEGER, -- p
417 * subprime INTEGER, -- q
418 * generator INTEGER, -- g
419 * public INTEGER, -- y
420 * private INTEGER, -- x
421 * }
422 *
423 * - 4 bytes of SEQUENCE overhead;
424 * - 3 bytes of version;
425 * - 3 full-size INTEGERs (p, g, y);
426 * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
427 */
428#define PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) \
429 (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
430
431/* Maximum size of the export encoding of an ECC public key.
432 *
433 * SubjectPublicKeyInfo ::= SEQUENCE {
434 * algorithm AlgorithmIdentifier,
435 * subjectPublicKey BIT STRING } -- contains ECPoint
436 * AlgorithmIdentifier ::= SEQUENCE {
437 * algorithm OBJECT IDENTIFIER,
438 * parameters OBJECT IDENTIFIER } -- namedCurve
Gilles Peskinecb6adbb2018-08-11 01:18:12 +0200439 * ECPoint ::= ...
440 * -- first 8 bits: 0x04;
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100441 * -- then x_P as a `ceiling(m/8)`-byte string, big endian;
442 * -- then y_P as a `ceiling(m/8)`-byte string, big endian;
443 * -- where `m` is the bit size associated with the curve.
Gilles Peskine1be949b2018-08-10 19:06:59 +0200444 *
445 * - 2 * 4 bytes of SEQUENCE overhead;
446 * - 1 + 1 + 7 bytes of algorithm (id-ecPublicKey OID);
447 * - 1 + 1 + 12 bytes of namedCurve OID;
448 * - 4 bytes of BIT STRING overhead;
449 * - 1 byte + 2 * point size in ECPoint.
450 */
451#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
452 (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
453
454/* Maximum size of the export encoding of an ECC key pair.
455 *
Gilles Peskine5eb15212018-10-31 13:24:35 +0100456 * An ECC key pair is represented by the secret value.
Gilles Peskine1be949b2018-08-10 19:06:59 +0200457 */
458#define PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) \
Gilles Peskine5eb15212018-10-31 13:24:35 +0100459 (PSA_BITS_TO_BYTES(key_bits))
Gilles Peskine1be949b2018-08-10 19:06:59 +0200460
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.
Gilles Peskine1be949b2018-08-10 19:06:59 +0200506 *
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
Gilles Peskine0cad07c2018-06-27 19:49:02 +0200527#endif /* PSA_CRYPTO_SIZES_H */