sizes.h File Reference

Key size definitions for the PSA Crypto API. More...

Detailed Description

Key size definitions for the PSA Crypto API.

Author

Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de

Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file sizes.h.

#include "psa/sizes.h"
#include "type.h"

Include dependency graph for sizes.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	CONFIG_PSA_MAX_KEY_SIZE   0
	Maximum key size in bytes, determined by the build system. More...
#define	PSA_KEY_EXPORT_ECC_KEY_MAX_SIZE(key_type, key_bits)
	Maximum size of the export encoding of an ECC keypair. More...
#define	PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits)
	Sufficient output buffer size for psa_export_key(). More...
#define	PSA_ECC_KEY_SIZE_IS_VALID(type, bits)
	Check whether the key size is a valid ECC size for key type. More...
#define	PSA_MAX_PRIV_KEY_SIZE   (PSA_BYTES_TO_BITS(CONFIG_PSA_MAX_KEY_SIZE))
	The maximum size of an asymmetric private key.
#define	PSA_EXPORT_KEY_PAIR_MAX_SIZE   0
	Sufficient buffer size for exporting any asymmetric key pair. More...
#define	PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_type, key_bits)
	Maximum size of the export encoding of an ECC public key. More...
#define	PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits)
	Sufficient output buffer size for psa_export_public_key(). More...
#define	PSA_EXPORT_PUBLIC_KEY_MAX_SIZE   0
	Sufficient buffer size for exporting any asymmetric public key. More...
#define	PSA_MAX_PRIV_KEY_BUFFER_SIZE   (PSA_BITS_TO_BYTES(PSA_MAX_PRIV_KEY_SIZE))
	The maximum size of an asymmetric private key buffer. More...
#define	PSA_MAX_ASYMMETRIC_KEYPAIR_SIZE
	The maximum size of an asymmetric private key pair. More...
#define	PSA_MAX_KEY_DATA_SIZE   (CONFIG_PSA_MAX_KEY_SIZE)
	The maximum size of the used key data.
#define	PSA_MAX_UNSTRUCTURED_KEY_SIZE   (CONFIG_PSA_MAX_KEY_SIZE)
	The maximum size of an unstructured key.

Macro Definition Documentation

CONFIG_PSA_MAX_KEY_SIZE

#define CONFIG_PSA_MAX_KEY_SIZE   0

Maximum key size in bytes, determined by the build system.

The maximum key size is set automatically, depending on the features chosen at compile-time. They should not be changed manually.

Definition at line 56 of file sizes.h.

PSA_ECC_KEY_SIZE_IS_VALID

#define PSA_ECC_KEY_SIZE_IS_VALID	(		type,
			bits
	)

Value:

    (PSA_KEY_TYPE_ECC_GET_FAMILY(type) == PSA_ECC_FAMILY_TWISTED_EDWARDS ?  \
        (bits == 255) :                                                     \
    (PSA_KEY_TYPE_ECC_GET_FAMILY(type) == PSA_ECC_FAMILY_SECP_R1 ?          \
        (bits == 128 || \
         bits == 192 || \
         bits == 224 || \
         bits == 256 || \
         bits == 384) : \
    0))

Check whether the key size is a valid ECC size for key type.

Parameters

type	key type of of type psa_key_type_t
bits	Key size of type psa_key_bits_t

Definition at line 125 of file sizes.h.

PSA_EXPORT_KEY_OUTPUT_SIZE

#define PSA_EXPORT_KEY_OUTPUT_SIZE	(		key_type,
			key_bits
	)

Value:

    (PSA_KEY_TYPE_IS_PUBLIC_KEY(key_type) ? \
     PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits) : \
     (PSA_KEY_TYPE_IS_ECC(key_type) ? \
      PSA_KEY_EXPORT_ECC_KEY_MAX_SIZE(key_type, key_bits) :   \
      0))

Sufficient output buffer size for psa_export_key().

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

@ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;
@ref psa_status_t status;
status = @ref psa_get_key_attributes(key, &attributes);
if (status != @ref PSA_SUCCESS)
    handle_error(...);
@ref psa_key_type_t key_type = @ref psa_get_key_type(&attributes);
size_t key_bits = @ref psa_get_key_bits(&attributes);
size_t buffer_size = @ref PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
@ref psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
if (buffer == NULL)
    handle_error(...);
size_t buffer_length;
status = @ref psa_export_key(key, buffer, buffer_size, &buffer_length);
if (status != @ref PSA_SUCCESS)
    handle_error(...);

See also PSA_EXPORT_KEY_PAIR_MAX_SIZE and PSA_EXPORT_PUBLIC_KEY_MAX_SIZE.

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. 0 if the parameters are a valid combination that is not supported by the implementation. Unspecified if the parameters are not valid.

Definition at line 112 of file sizes.h.

PSA_EXPORT_KEY_PAIR_MAX_SIZE

#define PSA_EXPORT_KEY_PAIR_MAX_SIZE   0

Sufficient buffer size for exporting any asymmetric key pair.

This value must be a sufficient buffer size when calling psa_export_key() to export any asymmetric key pair that is supported by the implementation, regardless of the exact key type and key size.

See also PSA_EXPORT_KEY_OUTPUT_SIZE().

Definition at line 161 of file sizes.h.

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE   0

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

Definition at line 245 of file sizes.h.

PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE

#define PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE	(		key_type,
			key_bits
	)

Value:

    (PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_type, key_bits) : \
     0)

Sufficient output buffer size for psa_export_public_key().

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

Warning

This macro may evaluate 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 public key by querying the key type and size at runtime.

@ref psa_key_attributes_t attributes = @ref PSA_KEY_ATTRIBUTES_INIT;
@ref psa_status_t status;
status = @ref psa_get_key_attributes(key, &attributes);
if (status != @ref PSA_SUCCESS) handle_error(...);
@ref psa_key_type_t key_type = @ref psa_get_key_type(&attributes);
size_t key_bits = @ref psa_get_key_bits(&attributes);
size_t buffer_size = @ref PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits);
@ref psa_reset_key_attributes(&attributes);
uint8_t *buffer = malloc(buffer_size);
if (buffer == NULL) handle_error(...);
size_t buffer_length;
status = @ref psa_export_public_key(key, buffer, buffer_size, &buffer_length);
if (status != @ref PSA_SUCCESS) handle_error(...);

Parameters

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

Returns

A buffer size in bytes that guarantees that psa_export_public_key() will not fail with PSA_ERROR_BUFFER_TOO_SMALL. 0 if the parameters are a valid combination that is not supported. Unspecified if the parameters are not valid, the return value is unspecified. 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).

Definition at line 220 of file sizes.h.

PSA_KEY_EXPORT_ECC_KEY_MAX_SIZE

#define PSA_KEY_EXPORT_ECC_KEY_MAX_SIZE	(		key_type,
			key_bits
	)

Value:

    (size_t)\
    (PSA_KEY_TYPE_ECC_GET_FAMILY(key_type) == PSA_ECC_FAMILY_TWISTED_EDWARDS ? 32 : \
    (PSA_KEY_TYPE_ECC_GET_FAMILY(key_type) == PSA_ECC_FAMILY_SECP_R1 ? \
     PSA_BITS_TO_BYTES(key_bits) : \
     0))

Maximum size of the export encoding of an ECC keypair.

The representation of an ECC keypair follows https://arm-software.github.io/psa-api/crypto/1.1/api/keys/management.html#key-formats and is dependent on the family:

• for twisted Edwards curves: 32B
• for Weierstrass curves: ceiling(m/8)-byte string, big-endian where m is the bit size associated with the curve.

Definition at line 69 of file sizes.h.

PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE

#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE	(		key_type,
			key_bits
	)

Value:

    (PSA_KEY_TYPE_ECC_GET_FAMILY(key_type) == PSA_ECC_FAMILY_TWISTED_EDWARDS ? 32 : \
     ((size_t)(2 * PSA_BITS_TO_BYTES(key_bits) + 1)))

Maximum size of the export encoding of an ECC public key.

The representation of an ECC public key is dependent on the family:

• for twisted Edwards curves: 32B
• for Weierstrass curves:
  • The byte 0x04;
  • x_P as a ceiling(m/8)-byte string, big-endian;
  • y_P as a ceiling(m/8)-byte string, big-endian;
  • where m is the bit size associated with the curve.
  • 1 byte + 2 * point size.

Definition at line 176 of file sizes.h.

PSA_MAX_ASYMMETRIC_KEYPAIR_SIZE

#define PSA_MAX_ASYMMETRIC_KEYPAIR_SIZE

Value:

                                             (PSA_BITS_TO_BYTES(PSA_MAX_PRIV_KEY_SIZE) + \
                                             PSA_EXPORT_PUBLIC_KEY_MAX_SIZE)

The maximum size of an asymmetric private key pair.

Definition at line 258 of file sizes.h.

PSA_MAX_PRIV_KEY_BUFFER_SIZE

#define PSA_MAX_PRIV_KEY_BUFFER_SIZE   (PSA_BITS_TO_BYTES(PSA_MAX_PRIV_KEY_SIZE))

The maximum size of an asymmetric private key buffer.

If only a secure element driver is present, the private key will always be stored in a key slot and PSA Crypto will only allocate memory for an 8 Byte key slot number.

Definition at line 253 of file sizes.h.