1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /* 5 ***************************************************************************** 6 * Doxygen group definitions 7 ****************************************************************************/ 8 9 /** 10 ***************************************************************************** 11 * @file cpa_cy_im.h 12 * 13 * @defgroup cpaCyInstMaint Cryptographic Instance Management API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the Instance Management API for available 19 * Cryptographic Instances. It is expected that these functions will only be 20 * called via a single system maintenance entity, rather than individual 21 * clients. 22 * 23 *****************************************************************************/ 24 25 #ifndef CPA_CY_IM_H_ 26 #define CPA_CY_IM_H_ 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #include "cpa_cy_common.h" 33 34 /** 35 ***************************************************************************** 36 * @ingroup cpaCyInstMaint 37 * Cryptographic Component Initialization and Start function. 38 * 39 * @description 40 * This function will initialize and start the Cryptographic component. 41 * It MUST be called before any other crypto function is called. This 42 * function SHOULD be called only once (either for the very first time, 43 * or after an cpaCyStopInstance call which succeeded) per instance. 44 * Subsequent calls will have no effect. 45 * 46 * @context 47 * This function may sleep, and MUST NOT be called in interrupt context. 48 * @assumptions 49 * None 50 * @sideEffects 51 * None 52 * @blocking 53 * This function is synchronous and blocking. 54 * @reentrant 55 * No 56 * @threadSafe 57 * Yes 58 * @param[out] instanceHandle Handle to an instance of this API to be 59 * initialized. 60 * 61 * @retval CPA_STATUS_SUCCESS Function executed successfully. 62 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 63 * is to shutdown and restart. 64 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 65 * 66 * @pre 67 * None. 68 * @post 69 * None 70 * @note 71 * Note that this is a synchronous function and has no completion callback 72 * associated with it. 73 * 74 * @see 75 * cpaCyStopInstance() 76 * 77 *****************************************************************************/ 78 CpaStatus 79 cpaCyStartInstance(CpaInstanceHandle instanceHandle); 80 81 /** 82 ***************************************************************************** 83 * @ingroup cpaCyInstMaint 84 * Cryptographic Component Stop function. 85 * 86 * @description 87 * This function will stop the Cryptographic component and free 88 * all system resources associated with it. The client MUST ensure that 89 * all outstanding operations have completed before calling this function. 90 * The recommended approach to ensure this is to deregister all session or 91 * callback handles before calling this function. If outstanding 92 * operations still exist when this function is invoked, the callback 93 * function for each of those operations will NOT be invoked and the 94 * shutdown will continue. If the component is to be restarted, then a 95 * call to cpaCyStartInstance is required. 96 * 97 * @context 98 * This function may sleep, and so MUST NOT be called in interrupt 99 * context. 100 * @assumptions 101 * None 102 * @sideEffects 103 * None 104 * @blocking 105 * This function is synchronous and blocking. 106 * @reentrant 107 * No 108 * @threadSafe 109 * Yes 110 * @param[in] instanceHandle Handle to an instance of this API to be 111 * shutdown. 112 * 113 * @retval CPA_STATUS_SUCCESS Function executed successfully. 114 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 115 * is to ensure requests are not still being 116 * submitted and that all sessions are 117 * deregistered. If this does not help, then 118 * forcefully remove the component from the 119 * system. 120 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 121 * 122 * @pre 123 * The component has been initialized via cpaCyStartInstance. 124 * @post 125 * None 126 * @note 127 * Note that this is a synchronous function and has no completion callback 128 * associated with it. 129 * 130 * @see 131 * cpaCyStartInstance() 132 * 133 *****************************************************************************/ 134 CpaStatus 135 cpaCyStopInstance(CpaInstanceHandle instanceHandle); 136 137 /** 138 ***************************************************************************** 139 * @ingroup cpaCyInstMaint 140 * Cryptographic Capabilities Info 141 * 142 * @description 143 * This structure contains the capabilities that vary across API 144 * implementations. This structure is used in conjunction with 145 * @ref cpaCyQueryCapabilities() to determine the capabilities supported 146 * by a particular API implementation. 147 * 148 * The client MUST allocate memory for this structure and any members 149 * that require memory. When the structure is passed into the function 150 * ownership of the memory passes to the function. Ownership of the 151 * memory returns to the client when the function returns. 152 *****************************************************************************/ 153 typedef struct _CpaCyCapabilitiesInfo 154 { 155 CpaBoolean symSupported; 156 /**< CPA_TRUE if instance supports the symmetric cryptography API. 157 * See @ref cpaCySym. */ 158 CpaBoolean symDpSupported; 159 /**< CPA_TRUE if instance supports the symmetric cryptography 160 * data plane API. 161 * See @ref cpaCySymDp. */ 162 CpaBoolean dhSupported; 163 /**< CPA_TRUE if instance supports the Diffie Hellman API. 164 * See @ref cpaCyDh. */ 165 CpaBoolean dsaSupported; 166 /**< CPA_TRUE if instance supports the DSA API. 167 * See @ref cpaCyDsa. */ 168 CpaBoolean rsaSupported; 169 /**< CPA_TRUE if instance supports the RSA API. 170 * See @ref cpaCyRsa. */ 171 CpaBoolean ecSupported; 172 /**< CPA_TRUE if instance supports the Elliptic Curve API. 173 * See @ref cpaCyEc. */ 174 CpaBoolean ecdhSupported; 175 /**< CPA_TRUE if instance supports the Elliptic Curve Diffie Hellman API. 176 * See @ref cpaCyEcdh. */ 177 CpaBoolean ecdsaSupported; 178 /**< CPA_TRUE if instance supports the Elliptic Curve DSA API. 179 * See @ref cpaCyEcdsa. */ 180 CpaBoolean keySupported; 181 /**< CPA_TRUE if instance supports the Key Generation API. 182 * See @ref cpaCyKeyGen. */ 183 CpaBoolean lnSupported; 184 /**< CPA_TRUE if instance supports the Large Number API. 185 * See @ref cpaCyLn. */ 186 CpaBoolean primeSupported; 187 /**< CPA_TRUE if instance supports the prime number testing API. 188 * See @ref cpaCyPrime. */ 189 CpaBoolean drbgSupported; 190 /**< CPA_TRUE if instance supports the DRBG API. 191 * See @ref cpaCyDrbg. */ 192 CpaBoolean nrbgSupported; 193 /**< CPA_TRUE if instance supports the NRBG API. 194 * See @ref cpaCyNrbg. */ 195 CpaBoolean randSupported; 196 /**< CPA_TRUE if instance supports the random bit/number generation API. 197 * See @ref cpaCyRand. */ 198 CpaBoolean kptSupported; 199 /**< CPA_TRUE if instance supports the Intel(R) KPT Cryptographic API. 200 * See @ref cpaCyKpt. */ 201 CpaBoolean hkdfSupported; 202 /**< CPA_TRUE if instance supports the HKDF components of the KeyGen API. 203 * See @ref cpaCyKeyGen. */ 204 CpaBoolean extAlgchainSupported; 205 /**< CPA_TRUE if instance supports algorithm chaining for certain 206 * wireless algorithms. Please refer to implementation for details. 207 * See @ref cpaCySym. */ 208 CpaBoolean ecEdMontSupported; 209 /**< CPA_TRUE if instance supports the Edwards and Montgomery elliptic 210 * curves of the EC API. 211 * See @ref cpaCyEc */ 212 CpaBoolean ecSm2Supported; 213 /**< CPA_TRUE if instance supports the EcSM2 API. 214 * See @ref cpaCyEcsm2. */ 215 } CpaCyCapabilitiesInfo; 216 217 /** 218 ***************************************************************************** 219 * @ingroup cpaCyInstMaint 220 * Returns capabilities of a Cryptographic API instance 221 * 222 * @description 223 * This function is used to query the instance capabilities. 224 * 225 * @context 226 * The function shall not be called in an interrupt context. 227 * @assumptions 228 * None 229 * @sideEffects 230 * None 231 * @blocking 232 * This function is synchronous and blocking. 233 * @reentrant 234 * No 235 * @threadSafe 236 * Yes 237 * 238 * @param[in] instanceHandle Handle to an instance of this API. 239 * @param[out] pCapInfo Pointer to capabilities info structure. 240 * All fields in the structure 241 * are populated by the API instance. 242 * 243 * @retval CPA_STATUS_SUCCESS Function executed successfully. 244 * @retval CPA_STATUS_FAIL Function failed. 245 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 246 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 247 * 248 * @pre 249 * The instance has been initialized via the @ref cpaCyStartInstance 250 * function. 251 * @post 252 * None 253 *****************************************************************************/ 254 CpaStatus 255 cpaCyQueryCapabilities(const CpaInstanceHandle instanceHandle, 256 CpaCyCapabilitiesInfo * pCapInfo); 257 258 /** 259 ***************************************************************************** 260 * @ingroup cpaCyInstMaint 261 * Sets the address translation function 262 * 263 * @description 264 * This function is used to set the virtual to physical address 265 * translation routine for the instance. The specified routine 266 * is used by the instance to perform any required translation of 267 * a virtual address to a physical address. If the application 268 * does not invoke this function, then the instance will use its 269 * default method, such as virt2phys, for address translation. 270 271 * @context 272 * The function shall not be called in an interrupt context. 273 * @assumptions 274 * None 275 * @sideEffects 276 * None 277 * @blocking 278 * This function is synchronous and blocking. 279 * @reentrant 280 * No 281 * @threadSafe 282 * Yes 283 * 284 * @param[in] instanceHandle Handle to an instance of this API. 285 * @param[in] virtual2Physical Routine that performs virtual to 286 * physical address translation. 287 * 288 * @retval CPA_STATUS_SUCCESS Function executed successfully. 289 * @retval CPA_STATUS_FAIL Function failed. 290 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 291 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 292 * 293 * @pre 294 * None 295 * @post 296 * None 297 * @see 298 * None 299 * 300 *****************************************************************************/ 301 CpaStatus 302 cpaCySetAddressTranslation(const CpaInstanceHandle instanceHandle, 303 CpaVirtualToPhysical virtual2Physical); 304 305 #ifdef __cplusplus 306 } /* close the extern "C" { */ 307 #endif 308 309 #endif /*CPA_CY_IM_H_*/ 310