|
|
CryptoKeyKeyStore driver header.
The CryptoKeyKeyStore driver provides API to initialize keys and get plaintext keys from KeyStore. This file provides definitions that are only available to the the secure side, in both TF-M disabled and TF-M enabled environments.
#include <stddef.h>#include <stdint.h>#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyKeyStore_PSA.h>#include <ti/drivers/dpl/SemaphoreP.h>#include <ti/devices/DeviceFamily.h>#include <third_party/mbedtls/library/psa_crypto_core.h>#include <third_party/mbedtls/library/psa_crypto_slot_management.h>#include <third_party/mbedtls/library/psa_crypto_storage.h>
Go to the source code of this file.
Data Structures | |
| struct | KeyStore_accessSemaphoreObject |
Macros | |
| #define | FLETCHER_CHECKSUM_ALGORITHM 32 /* FLETCHER-32 */ |
Functions | |
| int_fast16_t | KeyStore_PSA_getKey (KeyStore_PSA_KeyFileId key, uint8_t *data, size_t dataSize, size_t *dataLength, KeyStore_PSA_Algorithm alg, KeyStore_PSA_KeyUsage usage) |
| Get the plaintext key in binary format. More... | |
| bool | KeyStore_acquireLock (void) |
| Attempt to acquire lock to access KeyStore. This function is used to synchronize drivers and the application when both are attempting to use KeyStore. For example, if a driver is retrieving key material from a key slot to perform an operation, it must be protected from the application making a call to psa_destroy_key() on that same slot. More... | |
| void | KeyStore_releaseLock (void) |
| Release lock to access KeyStore. More... | |
| int_fast16_t | KeyStore_PSA_retrieveFromKeyStore (const CryptoKey *key, uint8_t *keyBuffer, size_t keyBufferSize, uint32_t *keyAssetID, KeyStore_PSA_Algorithm targetAlg, KeyStore_PSA_KeyUsage targetUsage) |
| Retrieve the key in either plaintext format or as an Asset ID. More... | |
| int_fast16_t | KeyStore_PSA_getKeyAssetId (KeyStore_PSA_KeyFileId key, uint32_t *const pAssetId, KeyStore_PSA_Algorithm targetAlg, KeyStore_PSA_KeyUsage targetUsage) |
| Get the asset ID for a given key ID. More... | |
| int_fast16_t | KeyStore_PSA_init (void) |
| Initialize the Key Store. More... | |
Variables | |
| KeyStore_accessSemaphoreObject | KeyStore_semaphoreObject |
| #define FLETCHER_CHECKSUM_ALGORITHM 32 /* FLETCHER-32 */ |
| int_fast16_t KeyStore_PSA_getKey | ( | KeyStore_PSA_KeyFileId | key, |
| uint8_t * | data, | ||
| size_t | dataSize, | ||
| size_t * | dataLength, | ||
| KeyStore_PSA_Algorithm | alg, | ||
| KeyStore_PSA_KeyUsage | usage | ||
| ) |
Get the plaintext key in binary format.
This function can only be called on secure side of SPM. It is used by SL crypto drivers to obtain plaintext keys, using keyIDs provided by non-secure application, which will be loaded onto crypto engine
Implementations must reject an attempt to import a certificate of size 0.
| [in] | key | The key ID for the key in keystore. |
| [out] | data | On success, the buffer contains the plaintext key |
| [in] | dataSize | Size of the data buffer in bytes. It must be greater than or equal to the plaintext key material |
| [out] | dataLength | Size of the returned key material in bytes. |
| [in] | alg | Algorithm the key will be used for, it should match the orignal alg used to import the key. |
| [in] | usage | Key usage, it must match the original usage used to import the key. |
| KEYSTORE_PSA_STATUS_SUCCESS | Success. If the key ID exists, matches the alg and usage , and the dataSize is sufficient the key is returned in data |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | If the KeyStore lock cannot be acquired, the KeyStore module is in use elsewhere. |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | The key identifier does not exist. |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The key does not have matching alg and usage |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| bool KeyStore_acquireLock | ( | void | ) |
Attempt to acquire lock to access KeyStore. This function is used to synchronize drivers and the application when both are attempting to use KeyStore. For example, if a driver is retrieving key material from a key slot to perform an operation, it must be protected from the application making a call to psa_destroy_key() on that same slot.
| true | Successfully acquired lock |
| false | Failed to acquire lock |
| void KeyStore_releaseLock | ( | void | ) |
Release lock to access KeyStore.
Once done accessing KeyStore, either the CryptoKeyKeyStore_PSA_helpers APIs or the PSA Crypto APIs should release this lock so that other entities can use KeyStore.
| int_fast16_t KeyStore_PSA_retrieveFromKeyStore | ( | const CryptoKey * | key, |
| uint8_t * | keyBuffer, | ||
| size_t | keyBufferSize, | ||
| uint32_t * | keyAssetID, | ||
| KeyStore_PSA_Algorithm | targetAlg, | ||
| KeyStore_PSA_KeyUsage | targetUsage | ||
| ) |
Retrieve the key in either plaintext format or as an Asset ID.
This function handles the logic of retrieving a key from CC27XX/CC35XX KeyStore, which depends both on the CryptoKey encoding and the key lifetime/location. If the key location is KEYSTORE_PSA_KEY_LOCATION_HSM_ASSET_STORE, then the key will be returned via asset ID. If the requested key was not already in the asset store upon request, it will be loaded before the asset ID is returned.
| [in] | key | Pointer to the CryptoKey object containing the encoding and keyID |
| [out] | keyBuffer | Buffer in which to place the key if it is retrievable in plaintext |
| [in] | keyBufferSize | Size of the provided buffer |
| [out] | keyAssetID | Pointer to keyAssetID output, if the key location is HSM_ASSET_STORE |
| [in] | targetAlg | Desired algorithm to use the key for. Before retrieving the key material, it must be verified that it is allowed to be used for a given algorithm. |
| [in] | targetUsage | Desired usage of the resulting key - only necessary for symmetric keys that will be returned as HSM assets. Must be one of KEYSTORE_PSA_KEY_USAGE_ENCRYPT or KEYSTORE_PSA_KEY_USAGE_DECRYPT. |
| KEYSTORE_PSA_STATUS_SUCCESS | |
| KEYSTORE_PSA_STATUS_GENERIC_ERROR | The key length retrieved from KeyStore doesn't match the expected length. Or, other generic error. |
| KEYSTORE_PSA_STATUS_NOT_SUPPORTED | The CryptoKey encoding has an unexpected/unsupported value. |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | The key identifier does not exist. |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The key does not have matching alg and usage |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_getKeyAssetId | ( | KeyStore_PSA_KeyFileId | key, |
| uint32_t *const | pAssetId, | ||
| KeyStore_PSA_Algorithm | targetAlg, | ||
| KeyStore_PSA_KeyUsage | targetUsage | ||
| ) |
Get the asset ID for a given key ID.
This function can only be called on secure side of SPM. It is used by SL crypto drivers to obtain assetIDs to refer to keys in the HSM, using keyIDs provided by non-secure application. The asset ID can then be used directly with the HSM for a crypto operation.
If the key is not already stored in the HSM's Asset Store, this function will perform that allocation and load before returning the new asset ID.
| [in] | key | The key ID for the key in keystore. |
| [out] | pAssetId | On success, the asset ID for the corresponding key ID |
| [in] | targetAlg | Desired algorithm to use the key for. Before retrieving the key asset, it must be verified that it is allowed to be used for a given algorithm. |
| [in] | targetUsage | Desired usage of the resulting asset - only used for symmetric keys. Must be one of KEYSTORE_PSA_KEY_USAGE_ENCRYPT or KEYSTORE_PSA_KEY_USAGE_DECRYPT. |
| KEYSTORE_PSA_STATUS_SUCCESS | Success. If the key ID exists, the asset ID is returned in pAssetId |
| KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE | If the KeyStore lock cannot be acquired, the KeyStore module is in use elsewhere. |
| KEYSTORE_PSA_STATUS_INVALID_KEY_ID | The key identifier does not exist. |
| KEYSTORE_PSA_STATUS_NOT_PERMITTED | The provided pAssetId is NULL |
| KEYSTORE_PSA_STATUS_BAD_STATE | The library has not been previously initialized by KeyStore_PSA_init(). It is implementation-dependent whether a failure to initialize results in this error code. |
| int_fast16_t KeyStore_PSA_init | ( | void | ) |
Initialize the Key Store.
Applications must call this function before calling any other function in this module. This function will initialize key slot memory and load the key IDs of any preprovisioned keys.
| KEYSTORE_PSA_STATUS_SUCCESS | Success. |
| KEYSTORE_PSA_STATUS_GENERIC_ERROR | tfm_its_init() failed |
| KEYSTORE_PSA_STATUS_DOES_NOT_EXIST | KeyStore_PSA_getPreProvisionedKeyIDs() failed |
| KeyStore_accessSemaphoreObject KeyStore_semaphoreObject |