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 Key formats 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_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED

The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

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 following conditions can result in this error:

The key type is invalid.
The key size is nonzero, and is incompatible with the key data in data.
The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.
The key data is not correctly formatted for the key type.

PSA_ERROR_NOT_SUPPORTED

The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function supports any output from psa_export_key(). Refer to Key formats for the format of keys.

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 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_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED

The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

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 following conditions can result in this error:

The key type is invalid, or is an asymmetric public key type.
The key size is not valid for the key type.
The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.

PSA_ERROR_NOT_SUPPORTED

The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_ENTROPY

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

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 permit the usage PSA_KEY_USAGE_COPY. If a private or secret key is being copied outside of a secure element it must also permit 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_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

source_key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The following conditions can result in this error:

source_key does not have the PSA_KEY_USAGE_COPY usage flag.
source_key does not have the PSA_KEY_USAGE_EXPORT usage flag, and the location of target_key is outside the security boundary of the source_key storage location.
The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

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 following conditions can result in this error:

attributes specifies a key type or key size which does not match the attributes of source key.
The lifetime or identifier in attributes are invalid.
The key policies from source_key and those specified in attributes are incompatible.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

The source key storage location does not support copying to the target key’s storage location.
The key attributes, as a whole, are not supported in the target key’s storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

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 permits 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: Success. If key was a valid key identifier, then the key material that it referred to has been erased. Alternatively, key was PSA_KEY_ID_NULL.
PSA_ERROR_BAD_STATE: The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE: key is neither a valid key identifier, nor 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_COMMUNICATION_FAILURE: There was an failure in communication with the cryptoprocessor. The key material might still be present in the cryptoprocessor.
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_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

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: Success. The key material has been removed from memory, if the key material is not currently required.
PSA_ERROR_BAD_STATE: The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE: key is not a valid key identifier.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID

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 permit 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

Success. The first (*data_length) bytes of data contain the exported key.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_EXPORT flag.

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 a sufficient buffer size.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

The key’s storage location does not support export of the key.
The implementation does not support export of keys with this key type.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

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 in Key formats, not the originally imported representation.

For standard key types, the output format is defined in Key formats.

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

Success. The first (*data_length) bytes of data contain the exported public key.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

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 a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT

The key is neither a public key nor a key pair.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

The key’s storage location does not support export of the key.
The implementation does not support export of keys with this key type.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

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 in Key formats, not the originally imported representation.

For standard key types, the output format is defined in Key formats.

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

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

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 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 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.4. Key formats¶

This section defines the format of the key data that an implementation is required to support when importing and exporting keys. Keys can be imported using psa_import_key(), and exported using psa_export_key() or psa_export_public_key().

Table 7 Standard key formats¶
Key type	Key type details and format
DES	`PSA_KEY_TYPE_DES`, 64 bits. The key data consists of 8 bytes. The parity bits must be correct.
2-key 3DES 3-key 3DES	`PSA_KEY_TYPE_DES`, 128 bits. `PSA_KEY_TYPE_DES`, 192 bits. The key data is the concatenation of the two or three DES keys.
HMAC	`PSA_KEY_TYPE_HMAC(hash_alg)` For HMAC keys that are shorter than, or equal in size to, the block size of `hash_alg`, the format is the raw bytes of the key. HMAC keys that are longer than the block size of `hash_alg`, are permitted in a call to `psa_import_key()`. For such a key, the output of `psa_export_key()` is an implementation defined choice between the following: The raw bytes of the key. The raw bytes of the hash of the key, using `hash_alg`.
Other symmetric keys AES ARC4 ARIA CAMELLIA ChaCha20 SM4 Secrets for derivation Password hashes	`PSA_KEY_TYPE_AES` `PSA_KEY_TYPE_ARC4` `PSA_KEY_TYPE_ARIA` `PSA_KEY_TYPE_CAMELLIA` `PSA_KEY_TYPE_CHACHA20` `PSA_KEY_TYPE_SM4` `PSA_KEY_TYPE_DERIVE` `PSA_KEY_TYPE_PASSWORD_HASH` The key data is the raw bytes of the key.
RSA key pair	`PSA_KEY_TYPE_RSA_KEY_PAIR` The key data 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.
RSA public key	`PSA_KEY_TYPE_RSA_PUBLIC_KEY` The key data is 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
Weierstrass Elliptic curve key pair	`PSA_KEY_TYPE_ECC_KEY_PAIR(ecc_family)`, where `ecc_family` designates a Weierstrass curve family. The key data is 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.
Weierstrass Elliptic curve public key	`PSA_KEY_TYPE_ECC_PUBLIC_KEY(ecc_family)`, where `ecc_family` designates a Weierstrass curve family. The key data is 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`, then 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.
Montgomery Elliptic curve key pair	`PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)` The key data is 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.
Montgomery Elliptic curve public key	`PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_MONTGOMERY)` The key data is 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)`.
Twisted Edwards Elliptic curve key pair	`PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)` The key data is the private key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
Twisted Edwards Elliptic curve public key	`PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS)` The key data is the public key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
Finite-field Diffie-Hellman key pair	`PSA_KEY_TYPE_DH_KEY_PAIR(dh_family)` where `dh_family` designates any Diffie-Hellman family. The key data 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.
Finite-field Diffie-Hellman public key	`PSA_KEY_TYPE_DH_PUBLIC_KEY(dh_family)` where `dh_family` designates any Diffie-Hellman family. The key data 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.

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

9.6.4. Key formats¶

`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)¶