1 /*************************************************************************** 2 * 3 * BSD LICENSE 4 * 5 * Copyright(c) 2007-2022 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 } CpaCyCapabilitiesInfo; 246 247 /** 248 ***************************************************************************** 249 * @ingroup cpaCyInstMaint 250 * Returns capabilities of a Cryptographic API instance 251 * 252 * @description 253 * This function is used to query the instance capabilities. 254 * 255 * @context 256 * The function shall not be called in an interrupt context. 257 * @assumptions 258 * None 259 * @sideEffects 260 * None 261 * @blocking 262 * This function is synchronous and blocking. 263 * @reentrant 264 * No 265 * @threadSafe 266 * Yes 267 * 268 * @param[in] instanceHandle Handle to an instance of this API. 269 * @param[out] pCapInfo Pointer to capabilities info structure. 270 * All fields in the structure 271 * are populated by the API instance. 272 * 273 * @retval CPA_STATUS_SUCCESS Function executed successfully. 274 * @retval CPA_STATUS_FAIL Function failed. 275 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 276 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 277 * 278 * @pre 279 * The instance has been initialized via the @ref cpaCyStartInstance 280 * function. 281 * @post 282 * None 283 *****************************************************************************/ 284 CpaStatus 285 cpaCyQueryCapabilities(const CpaInstanceHandle instanceHandle, 286 CpaCyCapabilitiesInfo * pCapInfo); 287 288 /** 289 ***************************************************************************** 290 * @ingroup cpaCyInstMaint 291 * Sets the address translation function 292 * 293 * @description 294 * This function is used to set the virtual to physical address 295 * translation routine for the instance. The specified routine 296 * is used by the instance to perform any required translation of 297 * a virtual address to a physical address. If the application 298 * does not invoke this function, then the instance will use its 299 * default method, such as virt2phys, for address translation. 300 301 * @context 302 * The function shall not be called in an interrupt context. 303 * @assumptions 304 * None 305 * @sideEffects 306 * None 307 * @blocking 308 * This function is synchronous and blocking. 309 * @reentrant 310 * No 311 * @threadSafe 312 * Yes 313 * 314 * @param[in] instanceHandle Handle to an instance of this API. 315 * @param[in] virtual2Physical Routine that performs virtual to 316 * physical address translation. 317 * 318 * @retval CPA_STATUS_SUCCESS Function executed successfully. 319 * @retval CPA_STATUS_FAIL Function failed. 320 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 321 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 322 * 323 * @pre 324 * None 325 * @post 326 * None 327 * @see 328 * None 329 * 330 *****************************************************************************/ 331 CpaStatus 332 cpaCySetAddressTranslation(const CpaInstanceHandle instanceHandle, 333 CpaVirtualToPhysical virtual2Physical); 334 335 #ifdef __cplusplus 336 } /* close the extern "C" { */ 337 #endif 338 339 #endif /*CPA_CY_IM_H_*/ 340