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