Platform Security Architecture — cryptography and keystore interface  Working draft
Functions
Key management

Functions

psa_status_t psa_import_key (psa_key_slot_t key, psa_key_type_t type, const uint8_t *data, size_t data_length)
 Import a key in binary format. More...
 
psa_status_t psa_destroy_key (psa_key_slot_t key)
 Destroy a key and restore the slot to its default state. More...
 
psa_status_t psa_get_key_information (psa_key_slot_t key, psa_key_type_t *type, size_t *bits)
 Get basic metadata about a key. More...
 
psa_status_t psa_export_key (psa_key_slot_t key, uint8_t *data, size_t data_size, size_t *data_length)
 Export a key in binary format. More...
 
psa_status_t psa_export_public_key (psa_key_slot_t key, uint8_t *data, size_t data_size, size_t *data_length)
 Export a public key or the public part of a key pair in binary format. More...
 

Detailed Description

Function Documentation

◆ psa_destroy_key()

psa_status_t psa_destroy_key ( psa_key_slot_t  key)

Destroy a key and restore the slot to its default state.

This function destroys the content of the key slot from both volatile memory and, if applicable, non-volatile storage. Implementations shall make a best effort to ensure that any previous content of the slot is unrecoverable.

This function also erases any metadata such as policies. It returns the specified slot to its default state.

Parameters
keyThe key slot to erase.
Return values
PSA_SUCCESSThe slot's content, if any, has been erased.
PSA_ERROR_NOT_PERMITTEDThe slot holds content and cannot be erased because it is read-only, either due to a policy or due to physical restrictions.
PSA_ERROR_INVALID_ARGUMENTThe specified slot number does not designate a valid slot.
PSA_ERROR_COMMUNICATION_FAILUREThere was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor.
PSA_ERROR_STORAGE_FAILUREThe storage is corrupted. Implementations shall make a best effort to erase key material even in this stage, however applications should be aware that it may be impossible to guarantee that the key material is not recoverable in such cases.
PSA_ERROR_TAMPERING_DETECTEDAn unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised.

◆ psa_export_key()

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

Export a key in binary format.

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

If a key is created with psa_import_key() and then exported with this function, it is not guaranteed that the resulting data is identical: the implementation may choose a different representation of the same key if the format permits it.

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

  • For symmetric keys (including MAC keys), the format is the raw bytes of the key.
  • 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 (PSA_KEY_TYPE_RSA_KEYPAIR), the format is the non-encrypted DER representation defined by PKCS#1 (RFC 8017) as RSAPrivateKey.
  • For RSA public keys (PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
Parameters
keySlot whose content is to be exported. This must be an occupied key slot.
[out]dataBuffer where the key data is to be written.
data_sizeSize of the data buffer in bytes.
[out]data_lengthOn success, the number of bytes that make up the key data.
Return values
PSA_SUCCESS
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_NOT_SUPPORTED
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_export_public_key()

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

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

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

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

Parameters
keySlot whose content is to be exported. This must be an occupied key slot.
[out]dataBuffer where the key data is to be written.
data_sizeSize of the data buffer in bytes.
[out]data_lengthOn success, the number of bytes that make up the key data.
Return values
PSA_SUCCESS
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_INVALID_ARGUMENT
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_get_key_information()

psa_status_t psa_get_key_information ( psa_key_slot_t  key,
psa_key_type_t type,
size_t *  bits 
)

Get basic metadata about a key.

Parameters
keySlot whose content is queried. This must be an occupied key slot.
[out]typeOn success, the key type (a PSA_KEY_TYPE_XXX value). This may be a null pointer, in which case the key type is not written.
[out]bitsOn success, the key size in bits. This may be a null pointer, in which case the key size is not written.
Return values
PSA_SUCCESS
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_import_key()

psa_status_t psa_import_key ( psa_key_slot_t  key,
psa_key_type_t  type,
const uint8_t *  data,
size_t  data_length 
)

Import a key in binary format.

This function supports any output from psa_export_key(). Refer to the documentation of psa_export_key() for the format for each key type.

Parameters
keySlot where the key will be stored. This must be a valid slot for a key of the chosen type. It must be unoccupied.
typeKey type (a PSA_KEY_TYPE_XXX value).
[in]dataBuffer containing the key data.
data_lengthSize of the data buffer in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_NOT_SUPPORTEDThe key type or key size is not supported, either by the implementation in general or in this particular slot.
PSA_ERROR_INVALID_ARGUMENTThe key slot is invalid, or the key data is not correctly formatted.
PSA_ERROR_OCCUPIED_SLOTThere is already a key in the specified slot.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED