1 /* 2 * Copyright (c) 2022-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*!***************************************************************************** 34 * @file CryptoKeyKeyStore_PSA_helpers.h 35 * @brief CryptoKeyKeyStore driver header 36 * 37 * @anchor ti_drivers_cryptoutils_cryptokey_CryptoKeyKeyStore_PSA_helpers_Overview 38 * # Overview 39 * The CryptoKeyKeyStore driver provides API to initialize keys and get plaintext 40 * keys from KeyStore. This file provides definitions that are only available to the 41 * the secure side, in both TF-M disabled and TF-M enabled environments. 42 * 43 ******************************************************************************* 44 */ 45 46 #ifndef ti_drivers_cryptoutils_cryptokey_CryptoKeyKeyStore_PSA_helpers__include 47 #define ti_drivers_cryptoutils_cryptokey_CryptoKeyKeyStore_PSA_helpers__include 48 49 #include <stddef.h> 50 #include <stdint.h> 51 52 #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyKeyStore_PSA.h> 53 54 #include <ti/drivers/dpl/SemaphoreP.h> 55 56 #include <third_party/mbedtls/library/psa_crypto_core.h> 57 #include <third_party/mbedtls/library/psa_crypto_slot_management.h> 58 #include <third_party/mbedtls/library/psa_crypto_storage.h> 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 /** KeyStore driver semaphore used to synchronize accesses to the keyStore 65 * 66 * isAcquired: used by openKey() and purgeKey() to check if the KeyStore semaphore is acquired by 67 * other KeyStore functions before opening and closing key handles passed to mbedTLS functions. 68 */ 69 typedef struct 70 { 71 SemaphoreP_Struct KeyStore_accessSemaphore; 72 bool isInitialized; 73 bool isAcquired; 74 } KeyStore_accessSemaphoreObject; 75 76 extern KeyStore_accessSemaphoreObject KeyStore_semaphoreObject; 77 78 #define FLETCHER_CHECKSUM_ALGORITHM 32 /* FLETCHER-32 */ 79 80 /** 81 * @brief Get the plaintext key in binary format. 82 * 83 * This function can only be called on secure side of SPM. It is used by SL crypto drivers 84 * to obtain plaintext keys, using keyIDs provided by non-secure application, which will be loaded onto crypto engine 85 * 86 * Implementations must reject an attempt to import a certificate of size 0. 87 * 88 * @param [in] key The key ID for the key in keystore. 89 * @param [out] data On success, the buffer contains the plaintext key 90 * @param [in] dataSize Size of the @p data buffer in bytes. It must be 91 * greater than or equal to the plaintext key material 92 * @param [out] dataLength Size of the returned key material in bytes. 93 * @param [in] alg Algorithm the key will be used for, it should match the orignal @p alg used to import the key. 94 * @param [in] usage Key usage, it must match the original @p usage used to import the key. 95 * 96 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 97 * Success. 98 * If the key ID exists, matches the @p alg and @p usage , and the @p dataSize is sufficient 99 * the key is returned in @p data 100 * @retval KEYSTORE_PSA_STATUS_RESOURCE_UNAVAILABLE 101 * @retval #KEYSTORE_PSA_STATUS_INVALID_KEY_ID 102 * The key identifier does not exist. 103 * @retval #KEYSTORE_PSA_STATUS_NOT_PERMITTED 104 * The key does not have matching @p alg and @p usage 105 * @retval #KEYSTORE_PSA_STATUS_BAD_STATE 106 * The library has not been previously initialized by 107 * KeyStore_PSA_init(). It is implementation-dependent whether a failure to 108 * initialize results in this error code. 109 */ 110 int_fast16_t KeyStore_PSA_getKey(KeyStore_PSA_KeyFileId key, 111 uint8_t *data, 112 size_t dataSize, 113 size_t *dataLength, 114 KeyStore_PSA_Algorithm alg, 115 KeyStore_PSA_KeyUsage usage); 116 117 /** 118 * @brief Initialize the Key Store. 119 * 120 * Applications must call this function before calling any other 121 * function in this module. This function will initialize key 122 * slot memory and load the key IDs of any preprovisioned keys. 123 * 124 * @retval #KEYSTORE_PSA_STATUS_SUCCESS 125 * Success. 126 * @retval #KEYSTORE_PSA_STATUS_GENERIC_ERROR 127 * tfm_its_init() failed 128 * @retval #KEYSTORE_PSA_STATUS_DOES_NOT_EXIST 129 * KeyStore_PSA_getPreProvisionedKeyIDs() failed 130 * 131 */ 132 int_fast16_t KeyStore_PSA_init(void); 133 134 #ifdef __cplusplus 135 } 136 #endif 137 138 #endif /* ti_drivers_cryptoutils_cryptokey_CryptoKeyKeyStore_PSA_helpers__include */ 139
