9.6. Key management functions

9.6.1. Key creation

New keys can be created in the following ways:

psa_import_key() creates a key from a data buffer provided by the application.
psa_generate_key() creates a key from randomly generated data.
psa_key_derivation_output_key() creates a key from data generated by a pseudorandom derivation process. See Key derivation.
psa_copy_key() duplicates an existing key with a different lifetime or with a more restrictive usage policy.

When creating a key, the attributes for the new key are specified in a psa_key_attributes_t object. Each key creation function defines how it uses the attributes.

Note

The attributes for a key are immutable after the key has been created.

The application must set the key algorithm policy and the appropriate key usage flags in the attributes in order for the key to be used in any cryptographic operations.

`psa_import_key` (function)

Import a key in binary format.

psa_status_t psa_import_key(const psa_key_attributes_t * attributes,
                            const uint8_t * data,
                            size_t data_length,
                            psa_key_id_t * key);

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required, and determines how the data buffer is interpreted.
The key size is always determined from the data buffer. If the key size in attributes is nonzero, it must be equal to the size determined from data.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.

Note

This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

data

Buffer containing the key data. The content of this buffer is interpreted according to the type declared in attributes. All implementations must support at least the format described in the documentation of psa_export_key() or psa_export_public_key() for the chosen type. Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.

data_length

Size of the data buffer in bytes.

key

On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns: psa_status_t

PSA_SUCCESS: Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS: This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTED: The key type or key size is not supported, either by the implementation in general or in this particular persistent location.
PSA_ERROR_INVALID_ARGUMENT: The key attributes, as a whole, are invalid.
PSA_ERROR_INVALID_ARGUMENT: The key data is not correctly formatted.
PSA_ERROR_INVALID_ARGUMENT: The size in attributes is nonzero and does not match the size of the key data.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types.

The key data determines the key size. The attributes can optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in attributes indicates that the key size is solely determined by the key data.

Implementations must reject an attempt to import a key of size 0.

This specification defines a single format for each key type. Implementations can optionally support other formats in addition to the standard format. It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.

Note

The PSA Crypto API does not support asymmetric private key objects outside of a key pair. To import a private key, the attributes must specify the corresponding key pair type. Depending on the key type, either the import format contains the public key data or the implementation will reconstruct the public key from the private key as needed.

`psa_generate_key` (function)

Generate a key or key pair.

psa_status_t psa_generate_key(const psa_key_attributes_t * attributes,
                              psa_key_id_t * key);

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required. It cannot be an asymmetric public key.
The key size is required. It must be a valid size for the key type.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.

Note

This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

key

On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns: psa_status_t

PSA_SUCCESS: Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_ALREADY_EXISTS: This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_NOT_SUPPORTED: The key type or key size is not supported, either by the implementation in general or in this particular persistent location.
PSA_ERROR_INVALID_ARGUMENT: The key attributes, as a whole, are invalid.
PSA_ERROR_INVALID_ARGUMENT: The key type is an asymmetric public key type.
PSA_ERROR_INVALID_ARGUMENT: The key size is not a valid size for the key type.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

The key is generated randomly. Its location, policy, type and size are taken from attributes.

Implementations must reject an attempt to generate a key of size 0.

The following type-specific considerations apply:

For RSA keys (PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

`psa_copy_key` (function)

Make a copy of a key.

psa_status_t psa_copy_key(psa_key_id_t source_key,
                          const psa_key_attributes_t * attributes,
                          psa_key_id_t * target_key);

Parameters

source_key

The key to copy. It must allow the usage PSA_KEY_USAGE_COPY. If a private or secret key is being copied outside of a secure element it must also allow PSA_KEY_USAGE_EXPORT.

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type and size can be 0. If either is nonzero, it must match the corresponding attribute of the source key.
The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
The key policy (usage flags and permitted algorithm) are combined from the source key and attributes so that both sets of restrictions apply, as described in the documentation of this function.

Note

This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

target_key

On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns: psa_status_t

PSA_SUCCESS: Success. If the new key is persistent, the key material and the key’s metadata have been saved to persistent storage.
PSA_ERROR_INVALID_HANDLE: source_key is invalid.
PSA_ERROR_ALREADY_EXISTS: This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT: The lifetime or identifier in attributes are invalid.
PSA_ERROR_INVALID_ARGUMENT: The key policies from source_key and specified in attributes are incompatible.
PSA_ERROR_INVALID_ARGUMENT: attributes specifies a key type or key size which does not match the attributes of source key.
PSA_ERROR_NOT_PERMITTED: source_key does not have the PSA_KEY_USAGE_COPY usage flag.
PSA_ERROR_NOT_PERMITTED: source_key does not have the PSA_KEY_USAGE_EXPORT usage flag and its lifetime does not allow copying it to the target’s lifetime.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

Copy key material from one location to another.

This function is primarily useful to copy a key from one location to another, as it populates a key using the material from another key which can have a different lifetime.

This function can be used to share a key with a different party, subject to implementation-defined restrictions on key sharing.

The policy on the source key must have the usage flag PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags PSA_KEY_USAGE_COPY and PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element.

The resulting key can only be used in a way that conforms to both the policy of the original key and the policy specified in the attributes parameter:

The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in attributes.
If both permit the same algorithm or wildcard-based algorithm, the resulting key has the same permitted algorithm.
If either of the policies permits an algorithm and the other policy allows a wildcard-based permitted algorithm that includes this algorithm, the resulting key uses this permitted algorithm.
If the policies do not permit any algorithm in common, this function fails with the status PSA_ERROR_INVALID_ARGUMENT.

The effect of this function on implementation-defined attributes is implementation-defined.

9.6.2. Key destruction

`psa_destroy_key` (function)

Destroy a key.

psa_status_t psa_destroy_key(psa_key_id_t key);

Parameters

key: Identifier of the key to erase. If this is PSA_KEY_ID_NULL, do nothing and return PSA_SUCCESS.

Returns: psa_status_t

PSA_SUCCESS: key was a valid key identifier and the key material that it referred to has been erased. Alternatively, key is PSA_KEY_ID_NULL.
PSA_ERROR_NOT_PERMITTED: The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
PSA_ERROR_INVALID_HANDLE: key is not a valid handle nor PSA_KEY_ID_NULL.
PSA_ERROR_COMMUNICATION_FAILURE: There was an failure in communication with the cryptoprocessor. The key material might still be present in the cryptoprocessor.
PSA_ERROR_STORAGE_FAILURE: The storage operation failed. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_DATA_CORRUPT: The storage is corrupted. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_DATA_INVALID
PSA_ERROR_CORRUPTION_DETECTED: An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor might have been compromised.
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations must make a best effort to ensure that that the key material cannot be recovered.

This function also erases any metadata such as policies and frees resources associated with the key.

Destroying the key makes the key identifier invalid, and the key identifier must not be used again by the application.

If a key is currently in use in a multi-part operation, then destroying the key will cause the multi-part operation to fail.

`psa_purge_key` (function)

Remove non-essential copies of key material from memory.

psa_status_t psa_purge_key(psa_key_id_t key);

Parameters

key: Identifier of the key to purge.

Returns: psa_status_t

PSA_SUCCESS: The key material will have been removed from memory if it is not currently required.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

For keys that have been created with the PSA_KEY_USAGE_CACHE usage flag, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations.

This function will remove these extra copies of the key material from memory.

This function is not required to remove key material from memory in any of the following situations:

The key is currently in use in a cryptographic operation.
The key is volatile.

9.6.3. Key export

`psa_export_key` (function)

Export a key in binary format.

psa_status_t psa_export_key(psa_key_id_t key,
                            uint8_t * data,
                            size_t data_size,
                            size_t * data_length);

Parameters

key

Identifier of the key to export. It must allow the usage PSA_KEY_USAGE_EXPORT, unless it is a public key.

data

Buffer where the key data is to be written.

data_size

Size of the data buffer in bytes. This must be appropriate for the key:

The required output size is PSA_EXPORT_KEY_OUTPUT_SIZE(type, bits) where type is the key type and bits is the key size in bits.
PSA_EXPORT_KEY_PAIR_MAX_SIZE evaluates to the maximum output size of any supported key pair.
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum output size of any supported public key.
This API defines no maximum size for symmetric keys. Arbitrarily large data items can be stored in the key store, for example certificates that correspond to a stored private key or input material for key derivation.

data_length

On success, the number of bytes that make up the key data.

Returns: psa_status_t

PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED: The key does not have the PSA_KEY_USAGE_EXPORT flag.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_BUFFER_TOO_SMALL: The size of the data buffer is too small. PSA_EXPORT_KEY_OUTPUT_SIZE() or PSA_EXPORT_KEY_PAIR_MAX_SIZE can be used to determine the required buffer size.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

The output of this function can be passed to psa_import_key() to create an equivalent object.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

For symmetric keys, excluding HMAC keys, the format is the raw bytes of the key.
For HMAC keys that are shorter than, or equal in size to, the underlying hash algorithm block size, the format is the raw bytes of the key.

For HMAC keys that are longer than the underlying hash algorithm block size, the format is an implementation defined choice between the following formats:
1. The raw bytes of the key.
2. The raw bytes of the hash of the key, using the underlying hash algorithm.
See also PSA_KEY_TYPE_HMAC.
For DES, the key data consists of 8 bytes. The parity bits must be correct.
For Triple-DES, the format is the concatenation of the two or three DES keys.

For RSA key pairs, with key type PSA_KEY_TYPE_RSA_KEY_PAIR, the format is the non-encrypted DER encoding of the representation defined by in PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] as RSAPrivateKey, version 0.

RSAPrivateKey ::= SEQUENCE {
    version             INTEGER,  -- must be 0
    modulus             INTEGER,  -- n
    publicExponent      INTEGER,  -- e
    privateExponent     INTEGER,  -- d
    prime1              INTEGER,  -- p
    prime2              INTEGER,  -- q
    exponent1           INTEGER,  -- d mod (p-1)
    exponent2           INTEGER,  -- d mod (q-1)
    coefficient         INTEGER,  -- (inverse of q) mod p
}

Note

Although it is possible to define an RSA key pair or private key using a subset of these elements, the output from psa_export_key() for an RSA key pair must include all of these elements.

For elliptic curve key pairs, with key types for which PSA_KEY_TYPE_IS_ECC_KEY_PAIR() is true, the format is a representation of the private value.
- For Weierstrass curve families PSA_ECC_FAMILY_SECT_XX, PSA_ECC_FAMILY_SECP_XX, PSA_ECC_FAMILY_FRP and PSA_ECC_FAMILY_BRAINPOOL_P_R1, the content of the privateKey field of the ECPrivateKey format defined by Elliptic Curve Private Key Structure [RFC5915].
  
  This is a ceiling(m/8)-byte string in big-endian order where m is the key size in bits.
- For curve family PSA_ECC_FAMILY_MONTGOMERY, the scalar value of the ‘private key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. The value must have the forced bits set to zero or one as specified by decodeScalar25519() and decodeScalar448() in [RFC7748] §5.
  
  This is a ceiling(m/8)-byte string where m is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.
For Diffie-Hellman key exchange key pairs, with key types for which PSA_KEY_TYPE_IS_DH_KEY_PAIR() is true, the format is the representation of the private key x as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
For public keys, with key types for which PSA_KEY_TYPE_IS_PUBLIC_KEY() is true, the format is the same as for psa_export_public_key().

The policy on the key must have the usage flag PSA_KEY_USAGE_EXPORT set.

`psa_export_public_key` (function)

Export a public key or the public part of a key pair in binary format.

psa_status_t psa_export_public_key(psa_key_id_t key,
                                   uint8_t * data,
                                   size_t data_size,
                                   size_t * data_length);

Parameters

key

Identifier of the key to export.

data

Buffer where the key data is to be written.

data_size

Size of the data buffer in bytes. This must be appropriate for the key:

The required output size is PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(type, bits) where type is the key type and bits is the key size in bits.
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum output size of any supported public key or public part of a key pair.

data_length

On success, the number of bytes that make up the key data.

Returns: psa_status_t

PSA_SUCCESS
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_INVALID_ARGUMENT: The key is neither a public key nor a key pair.
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_BUFFER_TOO_SMALL: The size of the data buffer is too small. PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE() or PSA_EXPORT_PUBLIC_KEY_MAX_SIZE can be used to determine the required buffer size.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_BAD_STATE: The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Description

The output of this function can be passed to psa_import_key() to create an object that is equivalent to the public key.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_public_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

For RSA public keys, with key type PSA_KEY_TYPE_RSA_PUBLIC_KEY, the DER encoding of the representation defined by Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [RFC3279] §2.3.1 as RSAPublicKey.
```
RSAPublicKey ::= SEQUENCE {
   modulus            INTEGER,    -- n
   publicExponent     INTEGER  }  -- e
```
For elliptic curve key pairs, with key types for which PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY() is true, the format depends on the key family:
- For Weierstrass curve families PSA_ECC_FAMILY_SECT_XX, PSA_ECC_FAMILY_SECP_XX, PSA_ECC_FAMILY_FRP and PSA_ECC_FAMILY_BRAINPOOL_P_R1, the uncompressed representation of an elliptic curve point as an octet string defined in SEC 1: Elliptic Curve Cryptography [SEC1] §2.3.3. If m is the bit size associated with the curve, i.e. the bit size of q for a curve over F_q. The representation consists of:
  - 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.
- For curve family PSA_ECC_FAMILY_MONTGOMERY, the scalar value of the ‘public key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. This is a ceiling(m/8)-byte string where m is the key size in bits.
  - This is 32 bytes for Curve25519, computed as X25519(private_key, 9).
  - This is 56 bytes for Curve448, computed as X448(private_key, 5).
For Diffie-Hellman key exchange public keys, with key types for which PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true, the format is the representation of the public key y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes.

Exporting a public key object or the public part of a key pair is always permitted, regardless of the key’s usage flags.

`PSA_EXPORT_KEY_OUTPUT_SIZE` (macro)

Sufficient output buffer size for psa_export_key().

#define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \
    /* implementation-defined value */

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 by the implementation, this macro must return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

Description

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

Warning

This function can evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.

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

`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE` (macro)

Sufficient output buffer size for psa_export_public_key().

#define PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(key_type, key_bits) \
    /* implementation-defined value */

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 by the implementation, this macro must return either a sensible size or 0. If the parameters are not valid, the return value is unspecified.

If the parameters are valid and supported, it is recommended that this macro returns the same result as PSA_EXPORT_KEY_OUTPUT_SIZE(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type), key_bits).

Description

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

Warning

This function can evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.

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

`PSA_EXPORT_KEY_PAIR_MAX_SIZE` (macro)

Sufficient buffer size for exporting any asymmetric key pair.

#define PSA_EXPORT_KEY_PAIR_MAX_SIZE /* implementation-defined value */

This macro must expand to a compile-time constant integer. 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.

`PSA_EXPORT_PUBLIC_KEY_MAX_SIZE` (macro)

Sufficient buffer size for exporting any asymmetric public key.

#define PSA_EXPORT_PUBLIC_KEY_MAX_SIZE /* implementation-defined value */

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

9.6. Key management functions

9.6.1. Key creation

psa_import_key (function)

psa_generate_key (function)

psa_copy_key (function)

9.6.2. Key destruction

psa_destroy_key (function)

psa_purge_key (function)

9.6.3. Key export

psa_export_key (function)

psa_export_public_key (function)

PSA_EXPORT_KEY_OUTPUT_SIZE (macro)

PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE (macro)

PSA_EXPORT_KEY_PAIR_MAX_SIZE (macro)

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE (macro)

`psa_import_key` (function)

`psa_generate_key` (function)

`psa_copy_key` (function)

`psa_destroy_key` (function)

`psa_purge_key` (function)

`psa_export_key` (function)

`psa_export_public_key` (function)

`PSA_EXPORT_KEY_OUTPUT_SIZE` (macro)

`PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE` (macro)

`PSA_EXPORT_KEY_PAIR_MAX_SIZE` (macro)

`PSA_EXPORT_PUBLIC_KEY_MAX_SIZE` (macro)