Platform Security Architecture — cryptography and keystore interface  beta 2 — 2019-02-22
Macros
crypto_sizes.h File Reference

PSA cryptography module: Mbed TLS buffer size macros. More...

#include "../mbedtls/config.h"
Include dependency graph for crypto_sizes.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define PSA_BITS_TO_BYTES(bits)   (((bits) + 7) / 8)
 
#define PSA_BYTES_TO_BITS(bytes)   ((bytes) * 8)
 
#define PSA_HASH_SIZE(alg)
 
#define PSA_HASH_MAX_SIZE   64
 
#define PSA_HMAC_MAX_HASH_BLOCK_SIZE   128
 
#define PSA_MAC_MAX_SIZE   PSA_HASH_MAX_SIZE
 
#define PSA_AEAD_TAG_LENGTH(alg)
 
#define PSA_VENDOR_RSA_MAX_KEY_BITS   4096
 
#define PSA_VENDOR_ECC_MAX_CURVE_BITS   521
 
#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN   128
 
#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
 
#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE   16
 
#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg)
 
#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length)
 
#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg)   ((size_t)0)
 
#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length)
 
#define PSA_RSA_MINIMUM_PADDING_SIZE(alg)
 
#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits)   (PSA_BITS_TO_BYTES(curve_bits) * 2)
 ECDSA signature size for a given curve bit size. More...
 
#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
 
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
 
#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
 
#define PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits)   ((bits) / 8 + 5)
 
#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits)   (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
 
#define PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits)   (9 * PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE((key_bits) / 2 + 1) + 14)
 
#define PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits)   (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 59)
 
#define PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits)   (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) * 3 + 75)
 
#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)   (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
 
#define PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits)   (PSA_BITS_TO_BYTES(key_bits))
 
#define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits)
 

Detailed Description

PSA cryptography module: Mbed TLS buffer size macros.

Note
This file may not be included directly. Applications must include psa/crypto.h.

This file contains the definitions of macros that are useful to compute buffer sizes. The signatures and semantics of these macros are standardized, but the definitions are not, because they depend on the available algorithms and, in some cases, on permitted tolerances on buffer sizes.

In implementations with isolation between the application and the cryptography module, implementers should take care to ensure that the definitions that are exposed to applications match what the module implements.

Macros that compute sizes whose values do not depend on the implementation are in crypto.h.

Macro Definition Documentation

#define PSA_AEAD_DECRYPT_OUTPUT_SIZE (   alg,
  ciphertext_length 
)
Value:
(PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
(plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
0)
#define PSA_AEAD_TAG_LENGTH(alg)
Definition: crypto_sizes.h:138

The maximum size of the output of psa_aead_decrypt(), in bytes.

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the plaintext may be smaller.

Parameters
algAn AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
ciphertext_lengthSize of the plaintext in bytes.
Returns
The AEAD ciphertext size for the specified algorithm. If the AEAD algorithm is not recognized, return 0. An implementation may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.
#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE (   alg,
  plaintext_length 
)
Value:
(PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
(plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
0)
#define PSA_AEAD_TAG_LENGTH(alg)
Definition: crypto_sizes.h:138

The maximum size of the output of psa_aead_encrypt(), in bytes.

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext may be smaller.

Parameters
algAn AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
plaintext_lengthSize of the plaintext in bytes.
Returns
The AEAD ciphertext size for the specified algorithm. If the AEAD algorithm is not recognized, return 0. An implementation may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.
#define PSA_AEAD_FINISH_OUTPUT_SIZE (   alg)    ((size_t)0)

The maximum size of the output of psa_aead_finish(), in bytes.

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_finish() will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext may be smaller.

Parameters
algAn AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
Returns
The maximum trailing ciphertext size for the specified algorithm. If the AEAD algorithm is not recognized, return 0. An implementation may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.
#define PSA_AEAD_TAG_LENGTH (   alg)
Value:
(PSA_ALG_IS_AEAD(alg) ? \
(((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
0)
#define PSA_ALG_IS_AEAD(alg)
Definition: crypto_values.h:591

The tag size for an AEAD algorithm, in bytes.

Parameters
algAn AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
Returns
The tag size for the specified algorithm. If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return 0. If the AEAD algorithm is not recognized, return 0. An implementation may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.
#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN   128

This macro returns the maximum length of the PSK supported by the TLS-1.2 PSK-to-MS key derivation.

Quoting RFC 4279, Sect 5.3: TLS implementations supporting these ciphersuites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.

Therefore, no implementation should define a value smaller than 64 for PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.

#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE (   key_type,
  key_bits,
  alg 
)
Value:
(PSA_KEY_TYPE_IS_RSA(key_type) ? \
PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
0)
#define PSA_KEY_TYPE_IS_RSA(type)
Definition: crypto_values.h:424

Safe output buffer size for psa_asymmetric_decrypt().

This macro returns a safe buffer size for a ciphertext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the ciphertext may be smaller, depending on the algorithm.

Warning
This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
Parameters
key_typeAn asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bitsThe size of the key in bits.
algThe signature algorithm.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_decrypt() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro either shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE (   key_type,
  key_bits,
  alg 
)
Value:
(PSA_KEY_TYPE_IS_RSA(key_type) ? \
((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
0)
#define PSA_KEY_TYPE_IS_RSA(type)
Definition: crypto_values.h:424

Safe output buffer size for psa_asymmetric_encrypt().

This macro returns a safe buffer size for a ciphertext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the ciphertext may be smaller, depending on the algorithm.

Warning
This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
Parameters
key_typeAn asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bitsThe size of the key in bits.
algThe signature algorithm.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_encrypt() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro either shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.
#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE (   key_type,
  key_bits,
  alg 
)
Value:
(PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
((void)alg, 0))
#define PSA_KEY_TYPE_IS_RSA(type)
Definition: crypto_values.h:424
#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits)
ECDSA signature size for a given curve bit size.
Definition: crypto_sizes.h:329
#define PSA_KEY_TYPE_IS_ECC(type)
Definition: crypto_values.h:446

Safe signature buffer size for psa_asymmetric_sign().

This macro returns a safe buffer size for a signature using a key of the specified type and size, with the specified algorithm. Note that the actual size of the signature may be smaller (some algorithms produce a variable-size signature).

Warning
This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.
Parameters
key_typeAn asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bitsThe size of the key in bits.
algThe signature algorithm.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_sign() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro either shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.
#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
Value:
PSA_BITS_TO_BYTES( \
PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \
PSA_VENDOR_RSA_MAX_KEY_BITS : \
PSA_VENDOR_ECC_MAX_CURVE_BITS \
)

Maximum size of an asymmetric signature.

This macro must expand to a compile-time constant integer. This value should be the maximum size of a MAC supported by the implementation, in bytes, and must be no smaller than this maximum.

#define PSA_ECDSA_SIGNATURE_SIZE (   curve_bits)    (PSA_BITS_TO_BYTES(curve_bits) * 2)

ECDSA signature size for a given curve bit size.

Parameters
curve_bitsCurve size in bits.
Returns
Signature size in bytes.
Note
This macro returns a compile-time constant if its argument is one.
#define PSA_HASH_MAX_SIZE   64

Maximum size of a hash.

This macro must expand to a compile-time constant integer. This value should be the maximum size of a hash supported by the implementation, in bytes, and must be no smaller than this maximum.

#define PSA_HASH_SIZE (   alg)
Value:
( \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
0)
#define PSA_ALG_SHA3_256
Definition: crypto_values.h:660
#define PSA_ALG_SHA3_224
Definition: crypto_values.h:658
#define PSA_ALG_SHA3_512
Definition: crypto_values.h:664
#define PSA_ALG_SHA_256
Definition: crypto_values.h:648
#define PSA_ALG_SHA_512
Definition: crypto_values.h:652
#define PSA_ALG_SHA_224
Definition: crypto_values.h:646
#define PSA_ALG_SHA_384
Definition: crypto_values.h:650
#define PSA_ALG_SHA_512_224
Definition: crypto_values.h:654
#define PSA_ALG_SHA_512_256
Definition: crypto_values.h:656
#define PSA_ALG_SHA3_384
Definition: crypto_values.h:662

The size of the output of psa_hash_finish(), in bytes.

This is also the hash size that psa_hash_verify() expects.

Parameters
algA hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true), or an HMAC algorithm (PSA_ALG_HMAC(hash_alg) where hash_alg is a hash algorithm).
Returns
The hash size for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation may return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.
#define PSA_KEY_EXPORT_MAX_SIZE (   key_type,
  key_bits 
)
Value:
(PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
(key_type) == PSA_KEY_TYPE_RSA_KEYPAIR ? PSA_KEY_EXPORT_RSA_KEYPAIR_MAX_SIZE(key_bits) : \
(key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
(key_type) == PSA_KEY_TYPE_DSA_KEYPAIR ? PSA_KEY_EXPORT_DSA_KEYPAIR_MAX_SIZE(key_bits) : \
(key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
PSA_KEY_TYPE_IS_ECC_KEYPAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEYPAIR_MAX_SIZE(key_bits) : \
PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
0)
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY
Definition: crypto_values.h:428
#define PSA_KEY_TYPE_RSA_KEYPAIR
Definition: crypto_values.h:422
#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type)
Definition: crypto_values.h:327
#define PSA_KEY_TYPE_RSA_PUBLIC_KEY
Definition: crypto_values.h:420
#define PSA_KEY_TYPE_DSA_KEYPAIR
Definition: crypto_values.h:430
#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type)
Definition: crypto_values.h:454
#define PSA_KEY_TYPE_IS_ECC_KEYPAIR(type)
Definition: crypto_values.h:450

Safe output buffer size for psa_export_key() or psa_export_public_key().

This macro returns a compile-time constant if its arguments are compile-time constants.

Warning
This function may call its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

The following code illustrates how to allocate enough memory to export a key by querying the key type and size at runtime.

psa_key_type_t key_type;
size_t key_bits;
psa_status_t status;
status = psa_get_key_information(key, &key_type, &key_bits);
if (status != PSA_SUCCESS) handle_error(...);
size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
unsigned char *buffer = malloc(buffer_size);
if (buffer != NULL) handle_error(...);
size_t buffer_length;
status = psa_export_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS) handle_error(...);

For psa_export_public_key(), calculate the buffer size from the public key type. You can use the macro PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR to convert a key pair type to the corresponding public key type.

psa_key_type_t key_type;
size_t key_bits;
psa_status_t status;
status = psa_get_key_information(key, &key_type, &key_bits);
if (status != PSA_SUCCESS) handle_error(...);
size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
unsigned char *buffer = malloc(buffer_size);
if (buffer != NULL) handle_error(...);
size_t buffer_length;
status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
if (status != PSA_SUCCESS) handle_error(...);
Parameters
key_typeA supported key type.
key_bitsThe size of the key in bits.
Returns
If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_asymmetric_sign() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported by the implementation, this macro either shall return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.
#define PSA_MAC_FINAL_SIZE (   key_type,
  key_bits,
  alg 
)
Value:
((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
((void)(key_type), (void)(key_bits), 0))
#define PSA_HASH_SIZE(alg)
Definition: crypto_sizes.h:70
#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg)
Definition: crypto_values.h:823
#define PSA_BLOCK_CIPHER_BLOCK_SIZE(type)
Definition: crypto_values.h:527
#define PSA_MAC_TRUNCATED_LENGTH(alg)
Definition: crypto_values.h:807
#define PSA_ALG_IS_HMAC(alg)
Definition: crypto_values.h:730

The size of the output of psa_mac_sign_finish(), in bytes.

This is also the MAC size that psa_mac_verify_finish() expects.

Parameters
key_typeThe type of the MAC key.
key_bitsThe size of the MAC key in bits.
algA MAC algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
Returns
The MAC size for the specified algorithm with the specified key parameters.
0 if the MAC algorithm is not recognized.
Either 0 or the correct size for a MAC algorithm that the implementation recognizes, but does not support.
Unspecified if the key parameters are not consistent with the algorithm.
#define PSA_MAC_MAX_SIZE   PSA_HASH_MAX_SIZE

Maximum size of a MAC.

This macro must expand to a compile-time constant integer. This value should be the maximum size of a MAC supported by the implementation, in bytes, and must be no smaller than this maximum.

#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE   16

The maximum size of a block cipher supported by the implementation.

#define PSA_RSA_MINIMUM_PADDING_SIZE (   alg)
Value:
(PSA_ALG_IS_RSA_OAEP(alg) ? \
2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
11 /*PKCS#1v1.5*/)