Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 1 | /* |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 2 | * Copyright (c) 2018-2019, Arm Limited. All rights reserved. |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 3 | * |
| 4 | * SPDX-License-Identifier: BSD-3-Clause |
| 5 | * |
| 6 | */ |
| 7 | /** |
| 8 | * \file psa_crypto_sizes.h |
| 9 | * |
| 10 | * \brief PSA cryptography module: buffer size macros |
| 11 | * |
| 12 | * \note This file may not be included directly. Applications must |
| 13 | * include psa_crypto.h. |
| 14 | * |
| 15 | * This file contains the definitions of macros that are useful to |
| 16 | * compute buffer sizes. The signatures and semantics of these macros |
| 17 | * are standardized, but the definitions are not, because they depend on |
| 18 | * the available algorithms and, in some cases, on permitted tolerances |
| 19 | * on buffer sizes. |
| 20 | * |
| 21 | * In implementations with isolation between the application and the |
| 22 | * cryptography module, implementers should take care to ensure that |
| 23 | * the definitions that are exposed to applications match what the |
| 24 | * module implements. |
| 25 | * |
| 26 | * Macros that compute sizes whose values do not depend on the |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 27 | * implementation are in crypto.h. |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 28 | */ |
| 29 | |
| 30 | #ifndef PSA_CRYPTO_SIZES_H |
| 31 | #define PSA_CRYPTO_SIZES_H |
| 32 | |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 33 | #define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8) |
| 34 | #define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8) |
| 35 | |
| 36 | /** The size of the output of psa_hash_finish(), in bytes. |
| 37 | * |
| 38 | * This is also the hash size that psa_hash_verify() expects. |
| 39 | * |
| 40 | * \param alg A hash algorithm (\c PSA_ALG_XXX value such that |
| 41 | * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm |
| 42 | * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a |
| 43 | * hash algorithm). |
| 44 | * |
| 45 | * \return The hash size for the specified hash algorithm. |
| 46 | * If the hash algorithm is not recognized, return 0. |
| 47 | * An implementation may return either 0 or the correct size |
| 48 | * for a hash algorithm that it recognizes, but does not support. |
| 49 | */ |
| 50 | #define PSA_HASH_SIZE(alg) \ |
| 51 | ( \ |
| 52 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \ |
| 53 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \ |
| 54 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \ |
| 55 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \ |
| 56 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \ |
| 57 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \ |
| 58 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \ |
| 59 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \ |
| 60 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \ |
| 61 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \ |
| 62 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \ |
| 63 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \ |
| 64 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \ |
| 65 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \ |
| 66 | PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \ |
| 67 | 0) |
| 68 | |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 69 | /** \def PSA_HASH_MAX_SIZE |
| 70 | * |
| 71 | * Maximum size of a hash. |
| 72 | * |
| 73 | * This macro must expand to a compile-time constant integer. This value |
| 74 | * should be the maximum size of a hash supported by the implementation, |
| 75 | * in bytes, and must be no smaller than this maximum. |
| 76 | */ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 77 | /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226, |
| 78 | * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for |
| 79 | * HMAC-SHA3-512. */ |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 80 | #define PSA_HASH_MAX_SIZE 64 |
| 81 | #define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128 |
| 82 | |
| 83 | /** \def PSA_MAC_MAX_SIZE |
| 84 | * |
| 85 | * Maximum size of a MAC. |
| 86 | * |
| 87 | * This macro must expand to a compile-time constant integer. This value |
| 88 | * should be the maximum size of a MAC supported by the implementation, |
| 89 | * in bytes, and must be no smaller than this maximum. |
| 90 | */ |
| 91 | /* All non-HMAC MACs have a maximum size that's smaller than the |
| 92 | * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 93 | /* Note that the encoding of truncated MAC algorithms limits this value |
| 94 | * to 64 bytes. |
| 95 | */ |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 96 | #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE |
| 97 | |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 98 | /** The tag size for an AEAD algorithm, in bytes. |
| 99 | * |
| 100 | * \param alg An AEAD algorithm |
| 101 | * (\c PSA_ALG_XXX value such that |
| 102 | * #PSA_ALG_IS_AEAD(\p alg) is true). |
| 103 | * |
| 104 | * \return The tag size for the specified algorithm. |
| 105 | * If the AEAD algorithm does not have an identified |
| 106 | * tag that can be distinguished from the rest of |
| 107 | * the ciphertext, return 0. |
| 108 | * If the AEAD algorithm is not recognized, return 0. |
| 109 | * An implementation may return either 0 or a |
| 110 | * correct size for an AEAD algorithm that it |
| 111 | * recognizes, but does not support. |
| 112 | */ |
| 113 | #define PSA_AEAD_TAG_LENGTH(alg) \ |
| 114 | (PSA_ALG_IS_AEAD(alg) ? \ |
| 115 | (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \ |
| 116 | 0) |
| 117 | |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 118 | /* The maximum size of an RSA key on this implementation, in bits. |
| 119 | * This is a vendor-specific macro. |
| 120 | * |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 121 | * Mbed TLS does not set a hard limit on the size of RSA keys: any key |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 122 | * whose parameters fit in a bignum is accepted. However large keys can |
| 123 | * induce a large memory usage and long computation times. Unlike other |
| 124 | * auxiliary macros in this file and in crypto.h, which reflect how the |
| 125 | * library is configured, this macro defines how the library is |
| 126 | * configured. This implementation refuses to import or generate an |
| 127 | * RSA key whose size is larger than the value defined here. |
| 128 | * |
| 129 | * Note that an implementation may set different size limits for different |
| 130 | * operations, and does not need to accept all key sizes up to the limit. */ |
| 131 | #define PSA_VENDOR_RSA_MAX_KEY_BITS 4096 |
| 132 | |
| 133 | /* The maximum size of an ECC key on this implementation, in bits. |
| 134 | * This is a vendor-specific macro. */ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 135 | #define PSA_VENDOR_ECC_MAX_CURVE_BITS 521 |
| 136 | |
| 137 | /** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN |
| 138 | * |
| 139 | * This macro returns the maximum length of the PSK supported |
| 140 | * by the TLS-1.2 PSK-to-MS key derivation. |
| 141 | * |
| 142 | * Quoting RFC 4279, Sect 5.3: |
| 143 | * TLS implementations supporting these ciphersuites MUST support |
| 144 | * arbitrary PSK identities up to 128 octets in length, and arbitrary |
| 145 | * PSKs up to 64 octets in length. Supporting longer identities and |
| 146 | * keys is RECOMMENDED. |
| 147 | * |
| 148 | * Therefore, no implementation should define a value smaller than 64 |
| 149 | * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN. |
| 150 | */ |
| 151 | #define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128 |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 152 | |
| 153 | /** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE |
| 154 | * |
| 155 | * Maximum size of an asymmetric signature. |
| 156 | * |
| 157 | * This macro must expand to a compile-time constant integer. This value |
| 158 | * should be the maximum size of a MAC supported by the implementation, |
| 159 | * in bytes, and must be no smaller than this maximum. |
| 160 | */ |
| 161 | #define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \ |
| 162 | PSA_BITS_TO_BYTES( \ |
| 163 | PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \ |
| 164 | PSA_VENDOR_RSA_MAX_KEY_BITS : \ |
| 165 | PSA_VENDOR_ECC_MAX_CURVE_BITS \ |
| 166 | ) |
| 167 | |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 168 | /** The maximum size of a block cipher supported by the implementation. */ |
| 169 | #define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16 |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 170 | |
| 171 | /** The size of the output of psa_mac_sign_finish(), in bytes. |
| 172 | * |
| 173 | * This is also the MAC size that psa_mac_verify_finish() expects. |
| 174 | * |
| 175 | * \param key_type The type of the MAC key. |
| 176 | * \param key_bits The size of the MAC key in bits. |
| 177 | * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that |
| 178 | * #PSA_ALG_IS_MAC(alg) is true). |
| 179 | * |
| 180 | * \return The MAC size for the specified algorithm with |
| 181 | * the specified key parameters. |
| 182 | * \return 0 if the MAC algorithm is not recognized. |
| 183 | * \return Either 0 or the correct size for a MAC algorithm that |
| 184 | * the implementation recognizes, but does not support. |
| 185 | * \return Unspecified if the key parameters are not consistent |
| 186 | * with the algorithm. |
| 187 | */ |
| 188 | #define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 189 | ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \ |
| 190 | PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \ |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 191 | PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 192 | ((void)(key_type), (void)(key_bits), 0)) |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 193 | |
| 194 | /** The maximum size of the output of psa_aead_encrypt(), in bytes. |
| 195 | * |
| 196 | * If the size of the ciphertext buffer is at least this large, it is |
| 197 | * guaranteed that psa_aead_encrypt() will not fail due to an |
| 198 | * insufficient buffer size. Depending on the algorithm, the actual size of |
| 199 | * the ciphertext may be smaller. |
| 200 | * |
| 201 | * \param alg An AEAD algorithm |
| 202 | * (\c PSA_ALG_XXX value such that |
| 203 | * #PSA_ALG_IS_AEAD(alg) is true). |
| 204 | * \param plaintext_length Size of the plaintext in bytes. |
| 205 | * |
| 206 | * \return The AEAD ciphertext size for the specified |
| 207 | * algorithm. |
| 208 | * If the AEAD algorithm is not recognized, return 0. |
| 209 | * An implementation may return either 0 or a |
| 210 | * correct size for an AEAD algorithm that it |
| 211 | * recognizes, but does not support. |
| 212 | */ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 213 | #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \ |
| 214 | (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \ |
| 215 | (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \ |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 216 | 0) |
| 217 | |
| 218 | /** The maximum size of the output of psa_aead_decrypt(), in bytes. |
| 219 | * |
| 220 | * If the size of the plaintext buffer is at least this large, it is |
| 221 | * guaranteed that psa_aead_decrypt() will not fail due to an |
| 222 | * insufficient buffer size. Depending on the algorithm, the actual size of |
| 223 | * the plaintext may be smaller. |
| 224 | * |
| 225 | * \param alg An AEAD algorithm |
| 226 | * (\c PSA_ALG_XXX value such that |
| 227 | * #PSA_ALG_IS_AEAD(alg) is true). |
| 228 | * \param ciphertext_length Size of the plaintext in bytes. |
| 229 | * |
| 230 | * \return The AEAD ciphertext size for the specified |
| 231 | * algorithm. |
| 232 | * If the AEAD algorithm is not recognized, return 0. |
| 233 | * An implementation may return either 0 or a |
| 234 | * correct size for an AEAD algorithm that it |
| 235 | * recognizes, but does not support. |
| 236 | */ |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 237 | #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \ |
| 238 | (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \ |
| 239 | (plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \ |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 240 | 0) |
| 241 | |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 242 | #define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \ |
| 243 | (PSA_ALG_IS_RSA_OAEP(alg) ? \ |
| 244 | 2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \ |
| 245 | 11 /*PKCS#1v1.5*/) |
| 246 | |
| 247 | /** |
| 248 | * \brief ECDSA signature size for a given curve bit size |
| 249 | * |
| 250 | * \param curve_bits Curve size in bits. |
| 251 | * \return Signature size in bytes. |
| 252 | * |
| 253 | * \note This macro returns a compile-time constant if its argument is one. |
| 254 | */ |
| 255 | #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \ |
| 256 | (PSA_BITS_TO_BYTES(curve_bits) * 2) |
| 257 | |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 258 | /** Safe signature buffer size for psa_asymmetric_sign(). |
| 259 | * |
| 260 | * This macro returns a safe buffer size for a signature using a key |
| 261 | * of the specified type and size, with the specified algorithm. |
| 262 | * Note that the actual size of the signature may be smaller |
| 263 | * (some algorithms produce a variable-size signature). |
| 264 | * |
| 265 | * \warning This function may call its arguments multiple times or |
| 266 | * zero times, so you should not pass arguments that contain |
| 267 | * side effects. |
| 268 | * |
| 269 | * \param key_type An asymmetric key type (this may indifferently be a |
| 270 | * key pair type or a public key type). |
| 271 | * \param key_bits The size of the key in bits. |
| 272 | * \param alg The signature algorithm. |
| 273 | * |
| 274 | * \return If the parameters are valid and supported, return |
| 275 | * a buffer size in bytes that guarantees that |
| 276 | * psa_asymmetric_sign() will not fail with |
| 277 | * #PSA_ERROR_BUFFER_TOO_SMALL. |
| 278 | * If the parameters are a valid combination that is not supported |
| 279 | * by the implementation, this macro either shall return either a |
| 280 | * sensible size or 0. |
| 281 | * If the parameters are not valid, the |
| 282 | * return value is unspecified. |
| 283 | */ |
| 284 | #define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \ |
| 285 | (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \ |
| 286 | PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \ |
| 287 | ((void)alg, 0)) |
| 288 | |
| 289 | /** Safe output buffer size for psa_asymmetric_encrypt(). |
| 290 | * |
| 291 | * This macro returns a safe buffer size for a ciphertext produced using |
| 292 | * a key of the specified type and size, with the specified algorithm. |
| 293 | * Note that the actual size of the ciphertext may be smaller, depending |
| 294 | * on the algorithm. |
| 295 | * |
| 296 | * \warning This function may call its arguments multiple times or |
| 297 | * zero times, so you should not pass arguments that contain |
| 298 | * side effects. |
| 299 | * |
| 300 | * \param key_type An asymmetric key type (this may indifferently be a |
| 301 | * key pair type or a public key type). |
| 302 | * \param key_bits The size of the key in bits. |
| 303 | * \param alg The signature algorithm. |
| 304 | * |
| 305 | * \return If the parameters are valid and supported, return |
| 306 | * a buffer size in bytes that guarantees that |
| 307 | * psa_asymmetric_encrypt() will not fail with |
| 308 | * #PSA_ERROR_BUFFER_TOO_SMALL. |
| 309 | * If the parameters are a valid combination that is not supported |
| 310 | * by the implementation, this macro either shall return either a |
| 311 | * sensible size or 0. |
| 312 | * If the parameters are not valid, the |
| 313 | * return value is unspecified. |
| 314 | */ |
| 315 | #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ |
| 316 | (PSA_KEY_TYPE_IS_RSA(key_type) ? \ |
| 317 | ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \ |
| 318 | 0) |
| 319 | |
| 320 | /** Safe output buffer size for psa_asymmetric_decrypt(). |
| 321 | * |
| 322 | * This macro returns a safe buffer size for a ciphertext produced using |
| 323 | * a key of the specified type and size, with the specified algorithm. |
| 324 | * Note that the actual size of the ciphertext may be smaller, depending |
| 325 | * on the algorithm. |
| 326 | * |
| 327 | * \warning This function may call its arguments multiple times or |
| 328 | * zero times, so you should not pass arguments that contain |
| 329 | * side effects. |
| 330 | * |
| 331 | * \param key_type An asymmetric key type (this may indifferently be a |
| 332 | * key pair type or a public key type). |
| 333 | * \param key_bits The size of the key in bits. |
| 334 | * \param alg The signature algorithm. |
| 335 | * |
| 336 | * \return If the parameters are valid and supported, return |
| 337 | * a buffer size in bytes that guarantees that |
| 338 | * psa_asymmetric_decrypt() will not fail with |
| 339 | * #PSA_ERROR_BUFFER_TOO_SMALL. |
| 340 | * If the parameters are a valid combination that is not supported |
| 341 | * by the implementation, this macro either shall return either a |
| 342 | * sensible size or 0. |
| 343 | * If the parameters are not valid, the |
| 344 | * return value is unspecified. |
| 345 | */ |
| 346 | #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \ |
| 347 | (PSA_KEY_TYPE_IS_RSA(key_type) ? \ |
| 348 | PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \ |
| 349 | 0) |
| 350 | |
Jamie Fox | 0e54ebc | 2019-04-09 14:21:04 +0100 | [diff] [blame^] | 351 | /* Maximum size of the ASN.1 encoding of an INTEGER with the specified |
| 352 | * number of bits. |
| 353 | * |
| 354 | * This definition assumes that bits <= 2^19 - 9 so that the length field |
| 355 | * is at most 3 bytes. The length of the encoding is the length of the |
| 356 | * bit string padded to a whole number of bytes plus: |
| 357 | * - 1 type byte; |
| 358 | * - 1 to 3 length bytes; |
| 359 | * - 0 to 1 bytes of leading 0 due to the sign bit. |
| 360 | */ |
| 361 | #define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits) \ |
| 362 | ((bits) / 8 + 5) |
| 363 | |
| 364 | /* Maximum size of the export encoding of an RSA public key. |
| 365 | * Assumes that the public exponent is less than 2^32. |
| 366 | * |
| 367 | * RSAPublicKey ::= SEQUENCE { |
| 368 | * modulus INTEGER, -- n |
| 369 | * publicExponent INTEGER } -- e |
| 370 | * |
| 371 | * - 4 bytes of SEQUENCE overhead; |
| 372 | * - n : INTEGER; |
| 373 | * - 7 bytes for the public exponent. |
| 374 | */ |
| 375 | #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \ |
| 376 | (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11) |
| 377 | |
| 378 | /* Maximum size of the export encoding of an RSA key pair. |
| 379 | * Assumes thatthe public exponent is less than 2^32 and that the size |
| 380 | * difference between the two primes is at most 1 bit. |
| 381 | * |
| 382 | * RSAPrivateKey ::= SEQUENCE { |
| 383 | * version Version, -- 0 |
| 384 | * modulus INTEGER, -- N-bit |
| 385 | * publicExponent INTEGER, -- 32-bit |
| 386 | * privateExponent INTEGER, -- N-bit |
| 387 | * prime1 INTEGER, -- N/2-bit |
| 388 | * prime2 INTEGER, -- N/2-bit |
| 389 | * exponent1 INTEGER, -- N/2-bit |
| 390 | * exponent2 INTEGER, -- N/2-bit |
| 391 | * coefficient INTEGER, -- N/2-bit |
| 392 | * } |
| 393 | * |
| 394 | * - 4 bytes of SEQUENCE overhead; |
| 395 | * - 3 bytes of version; |
| 396 | * - 7 half-size INTEGERs plus 2 full-size INTEGERs, |
| 397 | * overapproximated as 9 half-size INTEGERS; |
| 398 | * - 7 bytes for the public exponent. |
| 399 | */ |
| 400 | #define PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) \ |
| 401 | (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14) |
| 402 | |
| 403 | /* Maximum size of the export encoding of a DSA public key. |
| 404 | * |
| 405 | * SubjectPublicKeyInfo ::= SEQUENCE { |
| 406 | * algorithm AlgorithmIdentifier, |
| 407 | * subjectPublicKey BIT STRING } -- contains DSAPublicKey |
| 408 | * AlgorithmIdentifier ::= SEQUENCE { |
| 409 | * algorithm OBJECT IDENTIFIER, |
| 410 | * parameters Dss-Parms } -- SEQUENCE of 3 INTEGERs |
| 411 | * DSAPublicKey ::= INTEGER -- public key, Y |
| 412 | * |
| 413 | * - 3 * 4 bytes of SEQUENCE overhead; |
| 414 | * - 1 + 1 + 7 bytes of algorithm (DSA OID); |
| 415 | * - 4 bytes of BIT STRING overhead; |
| 416 | * - 3 full-size INTEGERs (p, g, y); |
| 417 | * - 1 + 1 + 32 bytes for 1 sub-size INTEGER (q <= 256 bits). |
| 418 | */ |
| 419 | #define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) \ |
| 420 | (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59) |
| 421 | |
| 422 | /* Maximum size of the export encoding of a DSA key pair. |
| 423 | * |
| 424 | * DSAPrivateKey ::= SEQUENCE { |
| 425 | * version Version, -- 0 |
| 426 | * prime INTEGER, -- p |
| 427 | * subprime INTEGER, -- q |
| 428 | * generator INTEGER, -- g |
| 429 | * public INTEGER, -- y |
| 430 | * private INTEGER, -- x |
| 431 | * } |
| 432 | * |
| 433 | * - 4 bytes of SEQUENCE overhead; |
| 434 | * - 3 bytes of version; |
| 435 | * - 3 full-size INTEGERs (p, g, y); |
| 436 | * - 2 * (1 + 1 + 32) bytes for 2 sub-size INTEGERs (q, x <= 256 bits). |
| 437 | */ |
| 438 | #define PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) \ |
| 439 | (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75) |
| 440 | |
| 441 | /* Maximum size of the export encoding of an ECC public key. |
| 442 | * |
| 443 | * The representation of an ECC public key is: |
| 444 | * - The byte 0x04; |
| 445 | * - `x_P` as a `ceiling(m/8)`-byte string, big-endian; |
| 446 | * - `y_P` as a `ceiling(m/8)`-byte string, big-endian; |
| 447 | * - where m is the bit size associated with the curve. |
| 448 | * |
| 449 | * - 1 byte + 2 * point size. |
| 450 | */ |
| 451 | #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \ |
| 452 | (2 * PSA_BITS_TO_BYTES(key_bits) + 1) |
| 453 | |
| 454 | /* Maximum size of the export encoding of an ECC key pair. |
| 455 | * |
| 456 | * An ECC key pair is represented by the secret value. |
| 457 | */ |
| 458 | #define PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) \ |
| 459 | (PSA_BITS_TO_BYTES(key_bits)) |
| 460 | |
| 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. |
| 506 | * |
| 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 | |
Antonio de Angelis | 377a155 | 2018-11-22 17:02:40 +0000 | [diff] [blame] | 527 | #endif /* PSA_CRYPTO_SIZES_H */ |