1 /* 2 * Copyright (c) 2022-2023, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 /** 9 * @file crypto_library.h 10 * 11 * @brief This file contains some abstractions required to interface the 12 * TF-M Crypto service to an underlying cryptographic library that 13 * implements the PSA Crypto API. The TF-M Crypto service uses this 14 * library to provide a PSA Crypto core layer implementation and 15 * a software or hardware based implementation of crypto algorithms. 16 */ 17 18 #ifndef CRYPTO_LIBRARY_H 19 #define CRYPTO_LIBRARY_H 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #include "psa/crypto.h" 26 27 /** 28 * @brief Some integration might decide to enforce the same ABI on client and 29 * service interfaces to PSA Crypto defining the \a CRYPTO_LIBRARY_ABI_COMPAT 30 * In this case the size of the structure describing the key attributes 31 * is the same both in client and server views. The semantics remain 32 * unchanged 33 */ 34 #if defined(CRYPTO_LIBRARY_ABI_COMPAT) && (CRYPTO_LIBRARY_ABI_COMPAT == 1) 35 #define TFM_CRYPTO_KEY_ATTR_OFFSET_CLIENT_SERVER (0) 36 #else 37 #define TFM_CRYPTO_KEY_ATTR_OFFSET_CLIENT_SERVER (sizeof(mbedtls_key_owner_id_t)) 38 #endif /* CRYPTO_LIBRARY_ABI_COMPAT */ 39 40 /** 41 * @brief This macro extracts the key ID from the library encoded key passed as parameter 42 * 43 */ 44 #define CRYPTO_LIBRARY_GET_KEY_ID(encoded_key_library) MBEDTLS_SVC_KEY_ID_GET_KEY_ID(encoded_key_library) 45 46 /** 47 * @brief This macro extracts the owner from the library encoded key passed as parameter 48 * 49 */ 50 #define CRYPTO_LIBRARY_GET_OWNER(encoded_key_library) MBEDTLS_SVC_KEY_ID_GET_OWNER_ID(encoded_key_library) 51 52 /** 53 * @brief The following typedef must be defined to the type associated to the key_id in the underlying library 54 * 55 */ 56 typedef mbedtls_svc_key_id_t tfm_crypto_library_key_id_t; 57 58 /** 59 * @brief Function used to initialise an object of \ref tfm_crypto_library_key_id_t to a (owner, key_id) pair 60 * 61 * @param[in] owner Owner of the key 62 * @param[in] key_id key ID associated to the key of type \ref psa_key_id_t 63 * 64 * @return An object of type \ref tfm_crypto_library_key_id_t 65 * 66 */ 67 tfm_crypto_library_key_id_t tfm_crypto_library_key_id_init(int32_t owner, psa_key_id_t key_id); 68 69 /** 70 * @brief This function is used to retrieve a string describing the library used in the backend 71 * to provide information to the crypto service and the user 72 * 73 * @return A NULL terminated string describing the backend library 74 */ 75 char *tfm_crypto_library_get_info(void); 76 77 /** 78 * @brief This function initialises a \ref tfm_crypto_library_key_id_t with default values 79 * 80 */ tfm_crypto_library_key_id_init_default(void)81static inline tfm_crypto_library_key_id_t tfm_crypto_library_key_id_init_default(void) 82 { 83 return tfm_crypto_library_key_id_init(0, 0); 84 } 85 86 /** 87 * @brief Allows to set the owner of a library key embedded into the key attributes structure 88 * 89 * @param[in] owner The owner value to be written into the key attributes structure 90 * @param[out] attr Pointer to the key attributes into which we want to e 91 * 92 */ 93 void tfm_crypto_library_get_library_key_id_set_owner(int32_t owner, psa_key_attributes_t *attr); 94 95 /*! 96 * @brief This function is used to perform the necessary steps to initialise the underlying 97 * library that provides the implementation of the PSA Crypto core to the TF-M Crypto 98 * service 99 * 100 * @return PSA_SUCCESS on successful initialisation 101 */ 102 psa_status_t tfm_crypto_core_library_init(void); 103 104 #ifdef __cplusplus 105 } 106 #endif 107 108 #endif /* CRYPTO_LIBRARY_H */ 109