1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 /** 17 * @defgroup crypt_eal_provider 18 * @ingroup crypt 19 * @brief introduced when then provider is used 20 */ 21 22 #ifndef CRYPT_EAL_PROVIDER_H 23 #define CRYPT_EAL_PROVIDER_H 24 25 #include <stdint.h> 26 #include "crypt_types.h" 27 #include "bsl_sal.h" 28 #include "bsl_params.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif // __cplusplus 33 34 typedef struct { 35 int32_t id; 36 void *func; 37 } CRYPT_EAL_Func; 38 39 /* The hitls framework generates context for each provider */ 40 typedef struct EAL_ProviderMgrCtx CRYPT_EAL_ProvMgrCtx; 41 42 /** 43 * @ingroup crypt_eal_provider 44 * @brief create Library context 45 * 46 * @retval return Library context 47 */ 48 CRYPT_EAL_LibCtx *CRYPT_EAL_LibCtxNew(void); 49 50 /** 51 * @ingroup crypt_eal_provider 52 * @brief free Library context 53 * @param libCtx [IN] Library context 54 * 55 */ 56 void CRYPT_EAL_LibCtxFree(CRYPT_EAL_LibCtx *libCtx); 57 58 /** 59 * @ingroup crypt_eal_provider 60 * @brief Provider load interface 61 * 62 * @param libCtx [IN] Library context 63 * @param providerName [IN] provider name 64 * @param param [IN] parameter is transparently passed to the initialization function of the underlying provider 65 * @param cmd [IN] Command specifying the conversion format for the provider library name. 66 * This parameter is used to determine how the provider library name should be 67 * converted or formatted. Possible values are: 68 * - BSL_SAL_LIB_FMT_SO: Convert to .so format 69 * - BSL_SAL_LIB_FMT_LIBSO: Convert to lib*.so format 70 * - BSL_SAL_LIB_FMT_LIBDLL: Convert to lib*.dll format 71 * - BSL_SAL_LIB_FMT_DLL: Convert to .dll format 72 * The specific conversion is handled by the BSL_SAL_LibNameFormat function. 73 * @param mgrCtx [OUT] Provider context 74 * 75 * @retval #CRYPT_SUCCESS, if success. 76 * Other error codes see the crypt_errno.h 77 */ 78 int32_t CRYPT_EAL_ProviderLoad(CRYPT_EAL_LibCtx *libCtx, BSL_SAL_LibFmtCmd cmd, 79 const char *providerName, BSL_Param *param, CRYPT_EAL_ProvMgrCtx **mgrCtx); 80 81 /** 82 * @ingroup crypt_eal_provider 83 * @brief Control provider interface 84 * 85 * @param ctx [IN] Provider context 86 * @param cmd [IN] Control command 87 * @param val [IN/OUT] Value associated with the command 88 * @param valLen [IN] Length of the value 89 * 90 * @retval #CRYPT_SUCCESS, if success. 91 * Other error codes see the crypt_errno.h 92 */ 93 int32_t CRYPT_EAL_ProviderCtrl(CRYPT_EAL_ProvMgrCtx *ctx, int32_t cmd, void *val, uint32_t valLen); 94 95 /** 96 * @brief Callback function type for processing provider capabilities 97 * 98 * @param params [IN] Parameters containing capability information 99 * @param args [IN] User-provided arguments for capability processing 100 * 101 * @retval #CRYPT_SUCCESS if processing succeeds 102 * Other error codes see the crypt_errno.h 103 */ 104 typedef int32_t (*CRYPT_EAL_ProcessFuncCb)(const BSL_Param *params, void *args); 105 106 /** 107 * @ingroup crypt_eal_provider 108 * @brief Get and process provider capabilities 109 * 110 * @param ctx [IN] Provider context 111 * @param cmd [IN] Command to specify which capabilities to retrieve 112 * @param cb [IN] Callback function to process the retrieved capabilities 113 * @param args [IN] Arguments to be passed to the callback function 114 * 115 * @retval #CRYPT_SUCCESS if capability retrieval and processing succeeds 116 * Other error codes see the crypt_errno.h 117 */ 118 int32_t CRYPT_EAL_ProviderGetCaps(CRYPT_EAL_ProvMgrCtx *ctx, int32_t cmd, CRYPT_EAL_ProcessFuncCb cb, void *args); 119 120 /** 121 * @ingroup crypt_eal_provider 122 * @brief Provider unload interface 123 * 124 * @param libCtx [IN] Library context 125 * @param cmd [IN] Command specifying the conversion format for the provider library name. 126 * This parameter is used to determine how the provider library name should be 127 * converted or formatted. Possible values are: 128 * - BSL_SAL_LIB_FMT_SO: Convert to .so format 129 * - BSL_SAL_LIB_FMT_LIBSO: Convert to lib*.so format 130 * - BSL_SAL_LIB_FMT_LIBDLL: Convert to lib*.dll format 131 * - BSL_SAL_LIB_FMT_DLL: Convert to .dll format 132 * The specific conversion is handled by the BSL_SAL_LibNameFormat function. 133 * @param providerName [IN] provider name 134 * 135 * @retval #CRYPT_SUCCESS, if success. 136 * Other error codes see the crypt_errno.h 137 */ 138 int32_t CRYPT_EAL_ProviderUnload(CRYPT_EAL_LibCtx *libCtx, BSL_SAL_LibFmtCmd cmd, const char *providerName); 139 140 141 /** 142 * @ingroup crypt_eal_provider 143 * @brief Set the path to load the provider and support duplicate settings. 144 * Repeating settings will release the previous path. 145 * 146 * @param libCtx [IN] Library context 147 * @param serchPath [IN] the path to load the provider 148 * 149 * @retval #CRYPT_SUCCESS, if success. 150 * Other error codes see the crypt_errno.h 151 */ 152 int32_t CRYPT_EAL_ProviderSetLoadPath(CRYPT_EAL_LibCtx *libCtx, const char *searchPath); 153 154 /** 155 * @ingroup crypt_eal_provider 156 * @brief Get function implementations from provider based on operation ID, algorithm ID and attributes 157 * 158 * @param libCtx [IN] Library context 159 * @param operaId [IN] Operation ID 160 * @param algId [IN] Algorithm ID 161 * @param attribute [IN] Attribute string for matching provider capabilities 162 * @param funcs [OUT] Retrieved function implementations 163 * @param provCtx [OUT] Provider context associated with the functions 164 * 165 * @retval #CRYPT_SUCCESS, if success. 166 * Other error codes see the crypt_errno.h 167 */ 168 int32_t CRYPT_EAL_ProviderGetFuncs(CRYPT_EAL_LibCtx *libCtx, int32_t operaId, int32_t algId, 169 const char *attribute, const CRYPT_EAL_Func **funcs, void **provCtx); 170 171 /** 172 * @brief Callback function type for processing a single provider 173 * 174 * @param ctx [IN] Provider context for the current provider being processed 175 * @param args [IN] User-provided arguments for provider processing 176 * 177 * @retval #CRYPT_SUCCESS if processing succeeds 178 * Other error codes see the crypt_errno.h 179 */ 180 typedef int32_t (*CRYPT_EAL_ProviderProcessCb)(CRYPT_EAL_ProvMgrCtx *ctx, void *args); 181 182 /** 183 * @ingroup crypt_eal_provider 184 * @brief Process all loaded providers with the specified callback function 185 * 186 * This function iterates through all providers loaded in the given library context 187 * and applies the specified callback function to each provider. It allows performing 188 * a common operation across all loaded providers. 189 * 190 * @param ctx [IN] Library context containing the providers to process 191 * @param cb [IN] Callback function to be applied to each provider 192 * @param args [IN] Arguments to be passed to the callback function 193 * 194 * @retval #CRYPT_SUCCESS if all providers were processed successfully 195 * The first error code encountered if any provider processing fails 196 * Other error codes see the crypt_errno.h 197 */ 198 int32_t CRYPT_EAL_ProviderProcessAll(CRYPT_EAL_LibCtx *ctx, CRYPT_EAL_ProviderProcessCb cb, void *args); 199 200 #ifdef __cplusplus 201 } 202 #endif // __cplusplus 203 204 #endif // CRYPT_EAL_PROVIDER_H 205