crypto_sizes.h

00001 /**
00002  * \file psa/crypto_sizes.h
00003  *
00004  * \brief PSA cryptography module: Mbed TLS buffer size macros
00005  *
00006  * \note This file may not be included directly. Applications must
00007  * include psa/crypto.h.
00008  *
00009  * This file contains the definitions of macros that are useful to
00010  * compute buffer sizes. The signatures and semantics of these macros
00011  * are standardized, but the definitions are not, because they depend on
00012  * the available algorithms and, in some cases, on permitted tolerances
00013  * on buffer sizes.
00014  *
00015  * In implementations with isolation between the application and the
00016  * cryptography module, implementers should take care to ensure that
00017  * the definitions that are exposed to applications match what the
00018  * module implements.
00019  *
00020  * Macros that compute sizes whose values do not depend on the
00021  * implementation are in crypto.h.
00022  */
00023 /*
00024  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00025  *  SPDX-License-Identifier: Apache-2.0
00026  *
00027  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00028  *  not use this file except in compliance with the License.
00029  *  You may obtain a copy of the License at
00030  *
00031  *  http://www.apache.org/licenses/LICENSE-2.0
00032  *
00033  *  Unless required by applicable law or agreed to in writing, software
00034  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00035  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00036  *  See the License for the specific language governing permissions and
00037  *  limitations under the License.
00038  *
00039  *  This file is part of mbed TLS (https://tls.mbed.org)
00040  */
00041 
00042 #ifndef PSA_CRYPTO_SIZES_H
00043 #define PSA_CRYPTO_SIZES_H
00044 
00045 /* Include the Mbed TLS configuration file, the way Mbed TLS does it
00046  * in each of its header files. */
00047 #if !defined(MBEDTLS_CONFIG_FILE)
00048 #include "mbedtls/config.h"
00049 #else
00050 #include MBEDTLS_CONFIG_FILE
00051 #endif
00052 
00053 #define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
00054 #define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
00055 
00056 #define PSA_ROUND_UP_TO_MULTIPLE(block_size, length) \
00057     (((length) + (block_size) - 1) / (block_size) * (block_size))
00058 
00059 /** The size of the output of psa_hash_finish(), in bytes.
00060  *
00061  * This is also the hash size that psa_hash_verify() expects.
00062  *
00063  * \param alg   A hash algorithm (\c PSA_ALG_XXX value such that
00064  *              #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm
00065  *              (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a
00066  *              hash algorithm).
00067  *
00068  * \return The hash size for the specified hash algorithm.
00069  *         If the hash algorithm is not recognized, return 0.
00070  *         An implementation may return either 0 or the correct size
00071  *         for a hash algorithm that it recognizes, but does not support.
00072  */
00073 #define PSA_HASH_SIZE(alg)                                      \
00074     (                                                           \
00075         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 :            \
00076         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 :            \
00077         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 :            \
00078         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 :      \
00079         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 :          \
00080         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 :        \
00081         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 :        \
00082         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 :        \
00083         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 :        \
00084         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 :    \
00085         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 :    \
00086         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 :       \
00087         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 :       \
00088         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 :       \
00089         PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 :       \
00090         0)
00091 
00092 /** \def PSA_HASH_MAX_SIZE
00093  *
00094  * Maximum size of a hash.
00095  *
00096  * This macro must expand to a compile-time constant integer. This value
00097  * should be the maximum size of a hash supported by the implementation,
00098  * in bytes, and must be no smaller than this maximum.
00099  */
00100 /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
00101  * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
00102  * HMAC-SHA3-512. */
00103 #if defined(MBEDTLS_SHA512_C)
00104 #define PSA_HASH_MAX_SIZE 64
00105 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
00106 #else
00107 #define PSA_HASH_MAX_SIZE 32
00108 #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 64
00109 #endif
00110 
00111 /** \def PSA_MAC_MAX_SIZE
00112  *
00113  * Maximum size of a MAC.
00114  *
00115  * This macro must expand to a compile-time constant integer. This value
00116  * should be the maximum size of a MAC supported by the implementation,
00117  * in bytes, and must be no smaller than this maximum.
00118  */
00119 /* All non-HMAC MACs have a maximum size that's smaller than the
00120  * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
00121 /* Note that the encoding of truncated MAC algorithms limits this value
00122  * to 64 bytes.
00123  */
00124 #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
00125 
00126 /** The tag size for an AEAD algorithm, in bytes.
00127  *
00128  * \param alg                 An AEAD algorithm
00129  *                            (\c PSA_ALG_XXX value such that
00130  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00131  *
00132  * \return                    The tag size for the specified algorithm.
00133  *                            If the AEAD algorithm does not have an identified
00134  *                            tag that can be distinguished from the rest of
00135  *                            the ciphertext, return 0.
00136  *                            If the AEAD algorithm is not recognized, return 0.
00137  *                            An implementation may return either 0 or a
00138  *                            correct size for an AEAD algorithm that it
00139  *                            recognizes, but does not support.
00140  */
00141 #define PSA_AEAD_TAG_LENGTH(alg)                                        \
00142     (PSA_ALG_IS_AEAD(alg) ?                                             \
00143      (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
00144      0)
00145 
00146 /* The maximum size of an RSA key on this implementation, in bits.
00147  * This is a vendor-specific macro.
00148  *
00149  * Mbed TLS does not set a hard limit on the size of RSA keys: any key
00150  * whose parameters fit in a bignum is accepted. However large keys can
00151  * induce a large memory usage and long computation times. Unlike other
00152  * auxiliary macros in this file and in crypto.h, which reflect how the
00153  * library is configured, this macro defines how the library is
00154  * configured. This implementation refuses to import or generate an
00155  * RSA key whose size is larger than the value defined here.
00156  *
00157  * Note that an implementation may set different size limits for different
00158  * operations, and does not need to accept all key sizes up to the limit. */
00159 #define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
00160 
00161 /* The maximum size of an ECC key on this implementation, in bits.
00162  * This is a vendor-specific macro. */
00163 #if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
00164 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 521
00165 #elif defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
00166 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 512
00167 #elif defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
00168 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 448
00169 #elif defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
00170 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
00171 #elif defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
00172 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 384
00173 #elif defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
00174 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
00175 #elif defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
00176 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
00177 #elif defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
00178 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 256
00179 #elif defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED)
00180 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 255
00181 #elif defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
00182 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
00183 #elif defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
00184 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 224
00185 #elif defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
00186 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
00187 #elif defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
00188 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 192
00189 #else
00190 #define PSA_VENDOR_ECC_MAX_CURVE_BITS 0
00191 #endif
00192 
00193 /** Bit size associated with an elliptic curve.
00194  *
00195  * \param curve     An elliptic curve (value of type #psa_ecc_curve_t).
00196  *
00197  * \return          The size associated with \p curve, in bits.
00198  *                  This may be 0 if the implementation does not support
00199  *                  the specified curve.
00200  */
00201 #define PSA_ECC_CURVE_BITS(curve)               \
00202     ((curve) == PSA_ECC_CURVE_SECT163K1        ? 163 : \
00203      (curve) == PSA_ECC_CURVE_SECT163R1        ? 163 : \
00204      (curve) == PSA_ECC_CURVE_SECT163R2        ? 163 : \
00205      (curve) == PSA_ECC_CURVE_SECT193R1        ? 193 : \
00206      (curve) == PSA_ECC_CURVE_SECT193R2        ? 193 : \
00207      (curve) == PSA_ECC_CURVE_SECT233K1        ? 233 : \
00208      (curve) == PSA_ECC_CURVE_SECT233R1        ? 233 : \
00209      (curve) == PSA_ECC_CURVE_SECT239K1        ? 239 : \
00210      (curve) == PSA_ECC_CURVE_SECT283K1        ? 283 : \
00211      (curve) == PSA_ECC_CURVE_SECT283R1        ? 283 : \
00212      (curve) == PSA_ECC_CURVE_SECT409K1        ? 409 : \
00213      (curve) == PSA_ECC_CURVE_SECT409R1        ? 409 : \
00214      (curve) == PSA_ECC_CURVE_SECT571K1        ? 571 : \
00215      (curve) == PSA_ECC_CURVE_SECT571R1        ? 571 : \
00216      (curve) == PSA_ECC_CURVE_SECP160K1        ? 160 : \
00217      (curve) == PSA_ECC_CURVE_SECP160R1        ? 160 : \
00218      (curve) == PSA_ECC_CURVE_SECP160R2        ? 160 : \
00219      (curve) == PSA_ECC_CURVE_SECP192K1        ? 192 : \
00220      (curve) == PSA_ECC_CURVE_SECP192R1        ? 192 : \
00221      (curve) == PSA_ECC_CURVE_SECP224K1        ? 224 : \
00222      (curve) == PSA_ECC_CURVE_SECP224R1        ? 224 : \
00223      (curve) == PSA_ECC_CURVE_SECP256K1        ? 256 : \
00224      (curve) == PSA_ECC_CURVE_SECP256R1        ? 256 : \
00225      (curve) == PSA_ECC_CURVE_SECP384R1        ? 384 : \
00226      (curve) == PSA_ECC_CURVE_SECP521R1        ? 521 : \
00227      (curve) == PSA_ECC_CURVE_BRAINPOOL_P256R1 ? 256 : \
00228      (curve) == PSA_ECC_CURVE_BRAINPOOL_P384R1 ? 384 : \
00229      (curve) == PSA_ECC_CURVE_BRAINPOOL_P512R1 ? 512 : \
00230      (curve) == PSA_ECC_CURVE_CURVE25519       ? 255 : \
00231      (curve) == PSA_ECC_CURVE_CURVE448         ? 448 : \
00232      0)
00233 
00234 /** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
00235  *
00236  * This macro returns the maximum length of the PSK supported
00237  * by the TLS-1.2 PSK-to-MS key derivation.
00238  *
00239  * Quoting RFC 4279, Sect 5.3:
00240  * TLS implementations supporting these ciphersuites MUST support
00241  * arbitrary PSK identities up to 128 octets in length, and arbitrary
00242  * PSKs up to 64 octets in length.  Supporting longer identities and
00243  * keys is RECOMMENDED.
00244  *
00245  * Therefore, no implementation should define a value smaller than 64
00246  * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.
00247  */
00248 #define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
00249 
00250 /** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
00251  *
00252  * Maximum size of an asymmetric signature.
00253  *
00254  * This macro must expand to a compile-time constant integer. This value
00255  * should be the maximum size of a MAC supported by the implementation,
00256  * in bytes, and must be no smaller than this maximum.
00257  */
00258 #define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE                               \
00259     PSA_BITS_TO_BYTES(                                                  \
00260         PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ?   \
00261         PSA_VENDOR_RSA_MAX_KEY_BITS :                                   \
00262         PSA_VENDOR_ECC_MAX_CURVE_BITS                                   \
00263         )
00264 
00265 /** The maximum size of a block cipher supported by the implementation. */
00266 #define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
00267 
00268 /** The size of the output of psa_mac_sign_finish(), in bytes.
00269  *
00270  * This is also the MAC size that psa_mac_verify_finish() expects.
00271  *
00272  * \param key_type      The type of the MAC key.
00273  * \param key_bits      The size of the MAC key in bits.
00274  * \param alg           A MAC algorithm (\c PSA_ALG_XXX value such that
00275  *                      #PSA_ALG_IS_MAC(\p alg) is true).
00276  *
00277  * \return              The MAC size for the specified algorithm with
00278  *                      the specified key parameters.
00279  * \return              0 if the MAC algorithm is not recognized.
00280  * \return              Either 0 or the correct size for a MAC algorithm that
00281  *                      the implementation recognizes, but does not support.
00282  * \return              Unspecified if the key parameters are not consistent
00283  *                      with the algorithm.
00284  */
00285 #define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg)                     \
00286     ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
00287      PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
00288      PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
00289      ((void)(key_type), (void)(key_bits), 0))
00290 
00291 /** The maximum size of the output of psa_aead_encrypt(), in bytes.
00292  *
00293  * If the size of the ciphertext buffer is at least this large, it is
00294  * guaranteed that psa_aead_encrypt() will not fail due to an
00295  * insufficient buffer size. Depending on the algorithm, the actual size of
00296  * the ciphertext may be smaller.
00297  *
00298  * \param alg                 An AEAD algorithm
00299  *                            (\c PSA_ALG_XXX value such that
00300  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00301  * \param plaintext_length    Size of the plaintext in bytes.
00302  *
00303  * \return                    The AEAD ciphertext size for the specified
00304  *                            algorithm.
00305  *                            If the AEAD algorithm is not recognized, return 0.
00306  *                            An implementation may return either 0 or a
00307  *                            correct size for an AEAD algorithm that it
00308  *                            recognizes, but does not support.
00309  */
00310 #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length)       \
00311     (PSA_AEAD_TAG_LENGTH(alg) != 0 ?                              \
00312      (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) :              \
00313      0)
00314 
00315 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
00316  *
00317  * If the size of the plaintext buffer is at least this large, it is
00318  * guaranteed that psa_aead_decrypt() will not fail due to an
00319  * insufficient buffer size. Depending on the algorithm, the actual size of
00320  * the plaintext may be smaller.
00321  *
00322  * \param alg                 An AEAD algorithm
00323  *                            (\c PSA_ALG_XXX value such that
00324  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00325  * \param ciphertext_length   Size of the plaintext in bytes.
00326  *
00327  * \return                    The AEAD ciphertext size for the specified
00328  *                            algorithm.
00329  *                            If the AEAD algorithm is not recognized, return 0.
00330  *                            An implementation may return either 0 or a
00331  *                            correct size for an AEAD algorithm that it
00332  *                            recognizes, but does not support.
00333  */
00334 #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length)      \
00335     (PSA_AEAD_TAG_LENGTH(alg) != 0 ?                              \
00336      (ciphertext_length) - PSA_AEAD_TAG_LENGTH(alg) :             \
00337      0)
00338 
00339 /** A sufficient output buffer size for psa_aead_update().
00340  *
00341  * If the size of the output buffer is at least this large, it is
00342  * guaranteed that psa_aead_update() will not fail due to an
00343  * insufficient buffer size. The actual size of the output may be smaller
00344  * in any given call.
00345  *
00346  * \param alg                 An AEAD algorithm
00347  *                            (\c PSA_ALG_XXX value such that
00348  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00349  * \param input_length        Size of the input in bytes.
00350  *
00351  * \return                    A sufficient output buffer size for the specified
00352  *                            algorithm.
00353  *                            If the AEAD algorithm is not recognized, return 0.
00354  *                            An implementation may return either 0 or a
00355  *                            correct size for an AEAD algorithm that it
00356  *                            recognizes, but does not support.
00357  */
00358 /* For all the AEAD modes defined in this specification, it is possible
00359  * to emit output without delay. However, hardware may not always be
00360  * capable of this. So for modes based on a block cipher, allow the
00361  * implementation to delay the output until it has a full block. */
00362 #define PSA_AEAD_UPDATE_OUTPUT_SIZE(alg, input_length)                  \
00363     (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
00364      PSA_ROUND_UP_TO_MULTIPLE(PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE, (input_length)) : \
00365      (input_length))
00366 
00367 /** A sufficient ciphertext buffer size for psa_aead_finish().
00368  *
00369  * If the size of the ciphertext buffer is at least this large, it is
00370  * guaranteed that psa_aead_finish() will not fail due to an
00371  * insufficient ciphertext buffer size. The actual size of the output may
00372  * be smaller in any given call.
00373  *
00374  * \param alg                 An AEAD algorithm
00375  *                            (\c PSA_ALG_XXX value such that
00376  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00377  *
00378  * \return                    A sufficient ciphertext buffer size for the
00379  *                            specified algorithm.
00380  *                            If the AEAD algorithm is not recognized, return 0.
00381  *                            An implementation may return either 0 or a
00382  *                            correct size for an AEAD algorithm that it
00383  *                            recognizes, but does not support.
00384  */
00385 #define PSA_AEAD_FINISH_OUTPUT_SIZE(alg)                                \
00386     (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
00387      PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE :                                  \
00388      0)
00389 
00390 /** A sufficient plaintext buffer size for psa_aead_verify().
00391  *
00392  * If the size of the plaintext buffer is at least this large, it is
00393  * guaranteed that psa_aead_verify() will not fail due to an
00394  * insufficient plaintext buffer size. The actual size of the output may
00395  * be smaller in any given call.
00396  *
00397  * \param alg                 An AEAD algorithm
00398  *                            (\c PSA_ALG_XXX value such that
00399  *                            #PSA_ALG_IS_AEAD(\p alg) is true).
00400  *
00401  * \return                    A sufficient plaintext buffer size for the
00402  *                            specified algorithm.
00403  *                            If the AEAD algorithm is not recognized, return 0.
00404  *                            An implementation may return either 0 or a
00405  *                            correct size for an AEAD algorithm that it
00406  *                            recognizes, but does not support.
00407  */
00408 #define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg)                                \
00409     (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ?                             \
00410      PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE :                                  \
00411      0)
00412 
00413 #define PSA_RSA_MINIMUM_PADDING_SIZE(alg)                         \
00414     (PSA_ALG_IS_RSA_OAEP(alg) ?                                   \
00415      2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 :      \
00416      11 /*PKCS#1v1.5*/)
00417 
00418 /**
00419  * \brief ECDSA signature size for a given curve bit size
00420  *
00421  * \param curve_bits    Curve size in bits.
00422  * \return              Signature size in bytes.
00423  *
00424  * \note This macro returns a compile-time constant if its argument is one.
00425  */
00426 #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits)    \
00427     (PSA_BITS_TO_BYTES(curve_bits) * 2)
00428 
00429 /** Sufficient signature buffer size for psa_asymmetric_sign().
00430  *
00431  * This macro returns a sufficient buffer size for a signature using a key
00432  * of the specified type and size, with the specified algorithm.
00433  * Note that the actual size of the signature may be smaller
00434  * (some algorithms produce a variable-size signature).
00435  *
00436  * \warning This function may call its arguments multiple times or
00437  *          zero times, so you should not pass arguments that contain
00438  *          side effects.
00439  *
00440  * \param key_type  An asymmetric key type (this may indifferently be a
00441  *                  key pair type or a public key type).
00442  * \param key_bits  The size of the key in bits.
00443  * \param alg       The signature algorithm.
00444  *
00445  * \return If the parameters are valid and supported, return
00446  *         a buffer size in bytes that guarantees that
00447  *         psa_asymmetric_sign() will not fail with
00448  *         #PSA_ERROR_BUFFER_TOO_SMALL.
00449  *         If the parameters are a valid combination that is not supported
00450  *         by the implementation, this macro shall return either a
00451  *         sensible size or 0.
00452  *         If the parameters are not valid, the
00453  *         return value is unspecified.
00454  */
00455 #define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)        \
00456     (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
00457      PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
00458      ((void)alg, 0))
00459 
00460 /** Sufficient output buffer size for psa_asymmetric_encrypt().
00461  *
00462  * This macro returns a sufficient buffer size for a ciphertext produced using
00463  * a key of the specified type and size, with the specified algorithm.
00464  * Note that the actual size of the ciphertext may be smaller, depending
00465  * on the algorithm.
00466  *
00467  * \warning This function may call its arguments multiple times or
00468  *          zero times, so you should not pass arguments that contain
00469  *          side effects.
00470  *
00471  * \param key_type  An asymmetric key type (this may indifferently be a
00472  *                  key pair type or a public key type).
00473  * \param key_bits  The size of the key in bits.
00474  * \param alg       The signature algorithm.
00475  *
00476  * \return If the parameters are valid and supported, return
00477  *         a buffer size in bytes that guarantees that
00478  *         psa_asymmetric_encrypt() will not fail with
00479  *         #PSA_ERROR_BUFFER_TOO_SMALL.
00480  *         If the parameters are a valid combination that is not supported
00481  *         by the implementation, this macro shall return either a
00482  *         sensible size or 0.
00483  *         If the parameters are not valid, the
00484  *         return value is unspecified.
00485  */
00486 #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg)     \
00487     (PSA_KEY_TYPE_IS_RSA(key_type) ?                                    \
00488      ((void)alg, PSA_BITS_TO_BYTES(key_bits)) :                         \
00489      0)
00490 
00491 /** Sufficient output buffer size for psa_asymmetric_decrypt().
00492  *
00493  * This macro returns a sufficient buffer size for a ciphertext produced using
00494  * a key of the specified type and size, with the specified algorithm.
00495  * Note that the actual size of the ciphertext may be smaller, depending
00496  * on the algorithm.
00497  *
00498  * \warning This function may call its arguments multiple times or
00499  *          zero times, so you should not pass arguments that contain
00500  *          side effects.
00501  *
00502  * \param key_type  An asymmetric key type (this may indifferently be a
00503  *                  key pair type or a public key type).
00504  * \param key_bits  The size of the key in bits.
00505  * \param alg       The signature algorithm.
00506  *
00507  * \return If the parameters are valid and supported, return
00508  *         a buffer size in bytes that guarantees that
00509  *         psa_asymmetric_decrypt() will not fail with
00510  *         #PSA_ERROR_BUFFER_TOO_SMALL.
00511  *         If the parameters are a valid combination that is not supported
00512  *         by the implementation, this macro shall return either a
00513  *         sensible size or 0.
00514  *         If the parameters are not valid, the
00515  *         return value is unspecified.
00516  */
00517 #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg)     \
00518     (PSA_KEY_TYPE_IS_RSA(key_type) ?                                    \
00519      PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) :  \
00520      0)
00521 
00522 /* Maximum size of the ASN.1 encoding of an INTEGER with the specified
00523  * number of bits.
00524  *
00525  * This definition assumes that bits <= 2^19 - 9 so that the length field
00526  * is at most 3 bytes. The length of the encoding is the length of the
00527  * bit string padded to a whole number of bytes plus:
00528  * - 1 type byte;
00529  * - 1 to 3 length bytes;
00530  * - 0 to 1 bytes of leading 0 due to the sign bit.
00531  */
00532 #define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits)      \
00533     ((bits) / 8 + 5)
00534 
00535 /* Maximum size of the export encoding of an RSA public key.
00536  * Assumes that the public exponent is less than 2^32.
00537  *
00538  * RSAPublicKey  ::=  SEQUENCE  {
00539  *    modulus            INTEGER,    -- n
00540  *    publicExponent     INTEGER  }  -- e
00541  *
00542  * - 4 bytes of SEQUENCE overhead;
00543  * - n : INTEGER;
00544  * - 7 bytes for the public exponent.
00545  */
00546 #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits)        \
00547     (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
00548 
00549 /* Maximum size of the export encoding of an RSA key pair.
00550  * Assumes thatthe public exponent is less than 2^32 and that the size
00551  * difference between the two primes is at most 1 bit.
00552  *
00553  * RSAPrivateKey ::= SEQUENCE {
00554  *     version           Version,  -- 0
00555  *     modulus           INTEGER,  -- N-bit
00556  *     publicExponent    INTEGER,  -- 32-bit
00557  *     privateExponent   INTEGER,  -- N-bit
00558  *     prime1            INTEGER,  -- N/2-bit
00559  *     prime2            INTEGER,  -- N/2-bit
00560  *     exponent1         INTEGER,  -- N/2-bit
00561  *     exponent2         INTEGER,  -- N/2-bit
00562  *     coefficient       INTEGER,  -- N/2-bit
00563  * }
00564  *
00565  * - 4 bytes of SEQUENCE overhead;
00566  * - 3 bytes of version;
00567  * - 7 half-size INTEGERs plus 2 full-size INTEGERs,
00568  *   overapproximated as 9 half-size INTEGERS;
00569  * - 7 bytes for the public exponent.
00570  */
00571 #define PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits)   \
00572     (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
00573 
00574 /* Maximum size of the export encoding of a DSA public key.
00575  *
00576  * SubjectPublicKeyInfo  ::=  SEQUENCE  {
00577  *      algorithm            AlgorithmIdentifier,
00578  *      subjectPublicKey     BIT STRING  } -- contains DSAPublicKey
00579  * AlgorithmIdentifier  ::=  SEQUENCE  {
00580  *      algorithm               OBJECT IDENTIFIER,
00581  *      parameters              Dss-Parms  } -- SEQUENCE of 3 INTEGERs
00582  * DSAPublicKey  ::=  INTEGER -- public key, Y
00583  *
00584  * - 3 * 4 bytes of SEQUENCE overhead;
00585  * - 1 + 1 + 7 bytes of algorithm (DSA OID);
00586  * - 4 bytes of BIT STRING overhead;
00587  * - 3 full-size INTEGERs (p, g, y);
00588  * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits).
00589  */
00590 #define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits)        \
00591     (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
00592 
00593 /* Maximum size of the export encoding of a DSA key pair.
00594  *
00595  * DSAPrivateKey ::= SEQUENCE {
00596  *     version             Version,  -- 0
00597  *     prime               INTEGER,  -- p
00598  *     subprime            INTEGER,  -- q
00599  *     generator           INTEGER,  -- g
00600  *     public              INTEGER,  -- y
00601  *     private             INTEGER,  -- x
00602  * }
00603  *
00604  * - 4 bytes of SEQUENCE overhead;
00605  * - 3 bytes of version;
00606  * - 3 full-size INTEGERs (p, g, y);
00607  * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits).
00608  */
00609 #define PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits)   \
00610     (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
00611 
00612 /* Maximum size of the export encoding of an ECC public key.
00613  *
00614  * The representation of an ECC public key is:
00615  *      - The byte 0x04;
00616  *      - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
00617  *      - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
00618  *      - where m is the bit size associated with the curve.
00619  *
00620  * - 1 byte + 2 * point size.
00621  */
00622 #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)        \
00623     (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
00624 
00625 /* Maximum size of the export encoding of an ECC key pair.
00626  *
00627  * An ECC key pair is represented by the secret value.
00628  */
00629 #define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits)   \
00630     (PSA_BITS_TO_BYTES(key_bits))
00631 
00632 /** Sufficient output buffer size for psa_export_key() or psa_export_public_key().
00633  *
00634  * This macro returns a compile-time constant if its arguments are
00635  * compile-time constants.
00636  *
00637  * \warning This function may call its arguments multiple times or
00638  *          zero times, so you should not pass arguments that contain
00639  *          side effects.
00640  *
00641  * The following code illustrates how to allocate enough memory to export
00642  * a key by querying the key type and size at runtime.
00643  * \code{c}
00644  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
00645  * psa_status_t status;
00646  * status = psa_get_key_attributes(key, &attributes);
00647  * if (status != PSA_SUCCESS) handle_error(...);
00648  * psa_key_type_t key_type = psa_get_key_type(&attributes);
00649  * size_t key_bits = psa_get_key_bits(&attributes);
00650  * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
00651  * psa_reset_key_attributes(&attributes);
00652  * uint8_t *buffer = malloc(buffer_size);
00653  * if (buffer == NULL) handle_error(...);
00654  * size_t buffer_length;
00655  * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
00656  * if (status != PSA_SUCCESS) handle_error(...);
00657  * \endcode
00658  *
00659  * For psa_export_public_key(), calculate the buffer size from the
00660  * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
00661  * to convert a key pair type to the corresponding public key type.
00662  * \code{c}
00663  * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
00664  * psa_status_t status;
00665  * status = psa_get_key_attributes(key, &attributes);
00666  * if (status != PSA_SUCCESS) handle_error(...);
00667  * psa_key_type_t key_type = psa_get_key_type(&attributes);
00668  * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type);
00669  * size_t key_bits = psa_get_key_bits(&attributes);
00670  * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
00671  * psa_reset_key_attributes(&attributes);
00672  * uint8_t *buffer = malloc(buffer_size);
00673  * if (buffer == NULL) handle_error(...);
00674  * size_t buffer_length;
00675  * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
00676  * if (status != PSA_SUCCESS) handle_error(...);
00677  * \endcode
00678  *
00679  * \param key_type  A supported key type.
00680  * \param key_bits  The size of the key in bits.
00681  *
00682  * \return If the parameters are valid and supported, return
00683  *         a buffer size in bytes that guarantees that
00684  *         psa_asymmetric_sign() will not fail with
00685  *         #PSA_ERROR_BUFFER_TOO_SMALL.
00686  *         If the parameters are a valid combination that is not supported
00687  *         by the implementation, this macro shall return either a
00688  *         sensible size or 0.
00689  *         If the parameters are not valid, the
00690  *         return value is unspecified.
00691  */
00692 #define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits)                     \
00693     (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
00694      (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) : \
00695      (key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
00696      (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
00697      (key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
00698      PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
00699      PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
00700      0)
00701 
00702 #endif /* PSA_CRYPTO_SIZES_H */