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
databuffer is interpreted. - The key size is always determined from the
databuffer. If the key size inattributesis nonzero, it must be equal to the size determined fromdata. - 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.- The key type is required, and determines how the
-
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 ofpsa_export_key()orpsa_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
databuffer in bytes. -
key - On success, an identifier for the newly created key.
PSA_KEY_ID_NULLon 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
attributesis 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_NULLon 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 allowPSA_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
attributesso 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.- The key type and size can be
-
target_key - On success, an identifier for the newly created key.
PSA_KEY_ID_NULLon 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_keyis 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
attributesare invalid. -
PSA_ERROR_INVALID_ARGUMENT - The key policies from
source_keyand specified inattributesare incompatible. -
PSA_ERROR_INVALID_ARGUMENT attributesspecifies a key type or key size which does not match the attributes ofsource key.-
PSA_ERROR_NOT_PERMITTED source_keydoes not have thePSA_KEY_USAGE_COPYusage flag.-
PSA_ERROR_NOT_PERMITTED source_keydoes not have thePSA_KEY_USAGE_EXPORTusage 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 returnPSA_SUCCESS.
Returns: psa_status_t
-
PSA_SUCCESS keywas a valid key identifier and the key material that it referred to has been erased. Alternatively,keyisPSA_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 keyis not a valid handle norPSA_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.
See also Managing key material.
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
databuffer in bytes. This must be appropriate for the key:- The required output size is
PSA_EXPORT_KEY_OUTPUT_SIZE(type,bits)wheretypeis the key type andbitsis the key size in bits. PSA_EXPORT_KEY_PAIR_MAX_SIZEevaluates to the maximum output size of any supported key pair.PSA_EXPORT_PUBLIC_KEY_MAX_SIZEevaluates 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.
- The required output size is
-
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_EXPORTflag. -
PSA_ERROR_NOT_SUPPORTED -
PSA_ERROR_BUFFER_TOO_SMALL - The size of the
databuffer is too small.PSA_EXPORT_KEY_OUTPUT_SIZE()orPSA_EXPORT_KEY_PAIR_MAX_SIZEcan 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:
- The raw bytes of the key.
- 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] asRSAPrivateKey, version0.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_FRPandPSA_ECC_FAMILY_BRAINPOOL_P_R1, the content of theprivateKeyfield of theECPrivateKeyformat defined by Elliptic Curve Private Key Structure [RFC5915].This is a
ceiling(m/8)-byte string in big-endian order wheremis 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 bydecodeScalar25519()anddecodeScalar448()in [RFC7748] §5.This is a
ceiling(m/8)-byte string wheremis 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 keyxas 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 forpsa_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
databuffer in bytes. This must be appropriate for the key:- The required output size is
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(type,bits)wheretypeis the key type andbitsis the key size in bits. PSA_EXPORT_PUBLIC_KEY_MAX_SIZEevaluates to the maximum output size of any supported public key or public part of a key pair.
- The required output size is
-
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
databuffer is too small.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()orPSA_EXPORT_PUBLIC_KEY_MAX_SIZEcan 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 asRSAPublicKey.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_FRPandPSA_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. Ifmis the bit size associated with the curve, i.e. the bit size ofqfor a curve overF_q. The representation consists of:- The byte
0x04; x_Pas aceiling(m/8)-byte string, big-endian;y_Pas aceiling(m/8)-byte string, big-endian.
- The byte
- 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 aceiling(m/8)-byte string wheremis 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).
- This is 32 bytes for Curve25519, computed as
- For Weierstrass curve families
For Diffie-Hellman key exchange public keys, with key types for which
PSA_KEY_TYPE_IS_DH_PUBLIC_KEYis true, the format is the representation of the public keyy = g^x mod pas a big-endian byte string. The length of the byte string is the length of the base primepin 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(...);
See also PSA_EXPORT_KEY_PAIR_MAX_SIZE and PSA_EXPORT_PUBLIC_KEY_MAX_SIZE.
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(...);
See also PSA_EXPORT_PUBLIC_KEY_MAX_SIZE.
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.
See also PSA_EXPORT_KEY_OUTPUT_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.
See also PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE().