|
Platform Security Architecture — cryptography and keystore interface
Working draft
|
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... | |
| 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.
| key | The key slot to erase. |
| PSA_SUCCESS | The slot's content, if any, has been erased. |
| PSA_ERROR_NOT_PERMITTED | The 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_ARGUMENT | The specified slot number does not designate a valid slot. |
| PSA_ERROR_COMMUNICATION_FAILURE | There was an failure in communication with the cryptoprocessor. The key material may still be present in the cryptoprocessor. |
| PSA_ERROR_STORAGE_FAILURE | The 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_DETECTED | An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor may have been compromised. |
| 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:
| key | Slot whose content is to be exported. This must be an occupied key slot. | |
| [out] | data | Buffer where the key data is to be written. |
| data_size | Size of the data buffer in bytes. | |
| [out] | data_length | On success, the number of bytes that make up the key data. |
| 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:
| key | Slot whose content is to be exported. This must be an occupied key slot. | |
| [out] | data | Buffer where the key data is to be written. |
| data_size | Size of the data buffer in bytes. | |
| [out] | data_length | On success, the number of bytes that make up the key data. |
| 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.
| key | Slot whose content is queried. This must be an occupied key slot. | |
| [out] | type | On 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] | bits | On success, the key size in bits. This may be a null pointer, in which case the key size is not written. |
| 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.
| key | Slot where the key will be stored. This must be a valid slot for a key of the chosen type. It must be unoccupied. | |
| type | Key type (a PSA_KEY_TYPE_XXX value). | |
| [in] | data | Buffer containing the key data. |
| data_length | Size of the data buffer in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_NOT_SUPPORTED | The key type or key size is not supported, either by the implementation in general or in this particular slot. |
| PSA_ERROR_INVALID_ARGUMENT | The key slot is invalid, or the key data is not correctly formatted. |
| PSA_ERROR_OCCUPIED_SLOT | There 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 |
1.8.13