File crypto_sizes.h

PSA cryptography module: Mbed TLS buffer size macros.

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.

Note

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

Defines

PSA_BITS_TO_BYTES(bits)

PSA_BYTES_TO_BITS(bytes)

PSA_MAX_OF_THREE(a, b, c)

PSA_ROUND_UP_TO_MULTIPLE(block_size, length)

PSA_HASH_LENGTH(alg)

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

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

Parameters

alg – A 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.

PSA_HASH_BLOCK_LENGTH(alg)

The input block size of a hash algorithm, in bytes.

Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they have enough input to fill the block or until the operation is finished. This affects the output from psa_hash_suspend().

Parameters

alg – A hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).

Returns

The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

PSA_HMAC_MAX_HASH_BLOCK_SIZE

PSA_HASH_MAX_SIZE

Maximum size of a hash.

This macro expands to a compile-time constant integer. This value is the maximum size of a hash in bytes.

PSA_MAC_MAX_SIZE

Maximum size of a MAC.

This macro expands to a compile-time constant integer. This value is the maximum size of a MAC in bytes.

PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg)

The length of a tag for an AEAD algorithm, in bytes.

This macro can be used to allocate a buffer of sufficient size to store the tag output from psa_aead_finish().

See also PSA_AEAD_NONCE_MAX_SIZE.

Note

This is not the maximum size of nonce supported as input to psa_aead_set_nonce(), psa_aead_encrypt() or psa_aead_decrypt(), just the default size that is generated by psa_aead_generate_nonce().

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A symmetric key type that is compatible with algorithm alg.
alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

The default nonce size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return 0.

PSA_AEAD_NONCE_MAX_SIZE

The maximum default nonce size among all supported pairs of key types and AEAD algorithms, in bytes.

This is equal to or greater than any value that PSA_AEAD_NONCE_LENGTH() may return.

Note

This is not the maximum size of nonce supported as input to psa_aead_set_nonce(), psa_aead_encrypt() or psa_aead_decrypt(), just the largest size that may be generated by psa_aead_generate_nonce().

PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length)

A sufficient output buffer size for psa_aead_update().

If the size of the output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size. The actual size of the output may be smaller in any given call.

See also PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length).

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A symmetric key type that is compatible with algorithm alg.
alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
input_length – Size of the input in bytes.

Returns

A sufficient output buffer size for the specified algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return 0.

PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length)

A sufficient output buffer size for psa_aead_update(), for any of the supported key types and AEAD algorithms.

If the size of the output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size.

See also PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length).

Parameters

input_length – Size of the input in bytes.

PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg)

A sufficient ciphertext buffer size for psa_aead_finish().

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 ciphertext buffer size. The actual size of the output may be smaller in any given call.

Parameters

key_type – A symmetric key type that is compatible with algorithm alg.
alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

A sufficient ciphertext buffer size for the specified algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return 0.

PSA_AEAD_FINISH_OUTPUT_MAX_SIZE

A sufficient ciphertext buffer size for psa_aead_finish(), for any of the supported key types and AEAD algorithms.

See also PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg).

PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg)

A sufficient plaintext buffer size for psa_aead_verify().

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_verify() will not fail due to an insufficient plaintext buffer size. The actual size of the output may be smaller in any given call.

Parameters

key_type – A symmetric key type that is compatible with algorithm alg.
alg – An AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).

Returns

A sufficient plaintext buffer size for the specified algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return 0.

PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE

A sufficient plaintext buffer size for psa_aead_verify(), for any of the supported key types and AEAD algorithms.

See also PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg).

PSA_RSA_MINIMUM_PADDING_SIZE(alg)

PSA_ECDSA_SIGNATURE_SIZE(curve_bits)

ECDSA signature size for a given curve bit size.

Note

This macro returns a compile-time constant if its argument is one.

Parameters

curve_bits – Curve size in bits.

Returns

Signature size in bytes.

PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)

Sufficient signature buffer size for psa_sign_hash().

This macro returns a sufficient 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_type – An asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bits – The size of the key in bits.
alg – The signature algorithm.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_sign_hash() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE

PSA_SIGNATURE_MAX_SIZE

Maximum size of an asymmetric signature.

This macro expands to a compile-time constant integer. This value is the maximum size of a signature in bytes.

PSA_SIGNATURE_MAX_SIZE

Maximum size of an asymmetric signature.

This macro expands to a compile-time constant integer. This value is the maximum size of a signature in bytes.

PSA_SIGNATURE_MAX_SIZE

Maximum size of an asymmetric signature.

This macro expands to a compile-time constant integer. This value is the maximum size of a signature in bytes.

PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg)

Sufficient output buffer size for psa_asymmetric_encrypt().

This macro returns a sufficient 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_type – An asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bits – The size of the key in bits.
alg – The asymmetric encryption 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, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE

A sufficient output buffer size for psa_asymmetric_encrypt(), for any supported asymmetric encryption.

See also PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg).

PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg)

Sufficient output buffer size for psa_asymmetric_decrypt().

This macro returns a sufficient buffer size for a plaintext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the plaintext 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_type – An asymmetric key type (this may indifferently be a key pair type or a public key type).
key_bits – The size of the key in bits.
alg – The asymmetric encryption 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, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE

A sufficient output buffer size for psa_asymmetric_decrypt(), for any supported asymmetric decryption.

This macro assumes that RSA is the only supported asymmetric encryption.

See also PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg).

PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(bits)

PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_FFDH_KEY_PAIR_MAX_SIZE(key_bits)

PSA_KEY_EXPORT_FFDH_PUBLIC_KEY_MAX_SIZE(key_bits)

PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits)

Sufficient 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.

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

psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS) handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *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(...);

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A supported key type.
key_bits – The size of the key in bits.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_export_key() or psa_export_public_key() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits)

Sufficient output buffer size for psa_export_public_key().

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

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

psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_status_t status;
status = psa_get_key_attributes(key, &attributes);
if (status != PSA_SUCCESS) handle_error(...);
psa_key_type_t key_type = psa_get_key_type(&attributes);
size_t key_bits = psa_get_key_bits(&attributes);
size_t buffer_size = PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits);
psa_reset_key_attributes(&attributes);
uint8_t *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(...);

If the parameters are valid and supported, return the same result as PSA_EXPORT_KEY_OUTPUT_SIZE( PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type), key_bits).

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A public key or key pair key type.
key_bits – The size of the key in bits.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_export_public_key() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_EXPORT_KEY_PAIR_MAX_SIZE

Sufficient buffer size for exporting any asymmetric key pair.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair, regardless of the exact key type and key size.

See also PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_KEY_PAIR_MAX_SIZE

Sufficient buffer size for exporting any asymmetric key pair.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair, regardless of the exact key type and key size.

See also PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_KEY_PAIR_MAX_SIZE

Sufficient buffer size for exporting any asymmetric key pair.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair, regardless of the exact key type and key size.

See also PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

Sufficient buffer size for exporting any asymmetric public key.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to export any asymmetric public key, regardless of the exact key type and key size.

See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

Sufficient buffer size for exporting any asymmetric public key.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to export any asymmetric public key, regardless of the exact key type and key size.

See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

Sufficient buffer size for exporting any asymmetric public key.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to export any asymmetric public key, regardless of the exact key type and key size.

See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

Sufficient buffer size for exporting any asymmetric public key.

This macro expands to a compile-time constant integer. This value is a sufficient buffer size when calling psa_export_key() or psa_export_public_key() to export any asymmetric public key, regardless of the exact key type and key size.

See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits).

PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits)

Sufficient output buffer size for psa_raw_key_agreement().

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

See also PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE.

Warning

This macro may evaluate its arguments multiple times or zero times, so you should not pass arguments that contain side effects.

Parameters

key_type – A supported key type.
key_bits – The size of the key in bits.

Returns

If the parameters are valid and supported, return a buffer size in bytes that guarantees that psa_raw_key_agreement() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are a valid combination that is not supported, return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE

Maximum size of the output from psa_raw_key_agreement().

This macro expands to a compile-time constant integer. This value is the maximum size of the output any raw key agreement algorithm, in bytes.

See also PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits).

PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE

Maximum size of the output from psa_raw_key_agreement().

This macro expands to a compile-time constant integer. This value is the maximum size of the output any raw key agreement algorithm, in bytes.

See also PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits).

PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE

Maximum size of the output from psa_raw_key_agreement().

This macro expands to a compile-time constant integer. This value is the maximum size of the output any raw key agreement algorithm, in bytes.

See also PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(key_type, key_bits).

PSA_CIPHER_IV_LENGTH(key_type, alg)

The default IV size for a cipher algorithm, in bytes.

The IV that is generated as part of a call to psa_cipher_encrypt() is always the default IV length for the algorithm.

This macro can be used to allocate a buffer of sufficient size to store the IV output from psa_cipher_generate_iv() when using a multi-part cipher operation.