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_common.h 12 * 13 * @defgroup cpaCy Cryptographic API 14 * 15 * @ingroup cpa 16 * 17 * @description 18 * These functions specify the Cryptographic API. 19 * 20 *****************************************************************************/ 21 22 /** 23 ***************************************************************************** 24 * @file cpa_cy_common.h 25 * @defgroup cpaCyCommon Cryptographic Common API 26 * 27 * @ingroup cpaCy 28 * 29 * @description 30 * This file specifies items which are common for both the asymmetric 31 * (public key cryptography) and the symmetric operations for the 32 * Cryptographic API. 33 * 34 *****************************************************************************/ 35 #ifndef CPA_CY_COMMON_H 36 #define CPA_CY_COMMON_H 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 #include "cpa.h" 43 44 /** 45 ***************************************************************************** 46 * @ingroup cpa_cyCommon 47 * CPA CY Major Version Number 48 * @description 49 * The CPA_CY API major version number. This number will be incremented 50 * when significant churn to the API has occurred. The combination of the 51 * major and minor number definitions represent the complete version number 52 * for this interface. 53 * 54 *****************************************************************************/ 55 #define CPA_CY_API_VERSION_NUM_MAJOR (3) 56 57 /** 58 ***************************************************************************** 59 * @ingroup cpa_cyCommon 60 * CPA CY Minor Version Number 61 * @description 62 * The CPA_CY API minor version number. This number will be incremented 63 * when minor changes to the API has occurred. The combination of the major 64 * and minor number definitions represent the complete version number for 65 * this interface. 66 * 67 *****************************************************************************/ 68 #define CPA_CY_API_VERSION_NUM_MINOR (0) 69 70 /** 71 ***************************************************************************** 72 * @file cpa_cy_common.h 73 * @ingroup cpa_cyCommon 74 * CPA CY API version at least 75 * @description 76 * The minimal supported CPA_CY API version. Allow to check if the API 77 * version is equal or above some version to avoid compilation issues 78 * with an older API version. 79 * 80 *****************************************************************************/ 81 #define CPA_CY_API_VERSION_AT_LEAST(major, minor) \ 82 (CPA_CY_API_VERSION_NUM_MAJOR > major || \ 83 (CPA_CY_API_VERSION_NUM_MAJOR == major && \ 84 CPA_CY_API_VERSION_NUM_MINOR >= minor)) 85 86 /** 87 ***************************************************************************** 88 * @file cpa_cy_common.h 89 * @ingroup cpa_cyCommon 90 * CPA CY API version less than 91 * @description 92 * The maximum supported CPA_CY API version. Allow to check if the API 93 * version is below some version to avoid compilation issues with a newer 94 * API version. 95 * 96 *****************************************************************************/ 97 #define CPA_CY_API_VERSION_LESS_THAN(major, minor) \ 98 (CPA_CY_API_VERSION_NUM_MAJOR < major || \ 99 (CPA_CY_API_VERSION_NUM_MAJOR == major && \ 100 CPA_CY_API_VERSION_NUM_MINOR < minor)) 101 102 /** 103 ***************************************************************************** 104 * @file cpa_cy_common.h 105 * @ingroup cpaCyCommon 106 * Request priority 107 * @description 108 * Enumeration of priority of the request to be given to the API. 109 * Currently two levels - HIGH and NORMAL are supported. HIGH priority 110 * requests will be prioritized on a "best-effort" basis over requests 111 * that are marked with a NORMAL priority. 112 * 113 *****************************************************************************/ 114 typedef enum _CpaCyPriority 115 { 116 CPA_CY_PRIORITY_NORMAL = 1, /**< Normal priority */ 117 CPA_CY_PRIORITY_HIGH /**< High priority */ 118 } CpaCyPriority; 119 120 /*****************************************************************************/ 121 /* Callback Definitions */ 122 /*****************************************************************************/ 123 /** 124 ***************************************************************************** 125 * @ingroup cpaCyCommon 126 * Definition of the crypto generic callback function 127 * 128 * @description 129 * This data structure specifies the prototype for a generic callback 130 * function 131 * 132 * @context 133 * This callback function can be executed in a context that DOES NOT 134 * permit sleeping to occur. 135 * 136 * @assumptions 137 * None 138 * @sideEffects 139 * None 140 * @reentrant 141 * No 142 * @threadSafe 143 * Yes 144 * 145 * @param[in] pCallbackTag Opaque value provided by user while making individual 146 * function call. 147 * @param[in] status Status of the operation. Valid values are 148 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 149 * CPA_STATUS_UNSUPPORTED. 150 * @param[in] pOpData Opaque Pointer to the operation data that was 151 * submitted in the request 152 * 153 * @retval 154 * None 155 * @pre 156 * Component has been initialized. 157 * @post 158 * None 159 * @note 160 * None 161 * @see 162 * cpaCyKeyGenSsl() 163 * 164 *****************************************************************************/ 165 typedef void (*CpaCyGenericCbFunc)(void *pCallbackTag, 166 CpaStatus status, 167 void *pOpData); 168 169 /** 170 ***************************************************************************** 171 * @ingroup cpaCyCommon 172 * Definition of generic callback function with an additional output 173 * CpaFlatBuffer parameter. 174 * 175 * @description 176 * This data structure specifies the prototype for a generic callback 177 * function which provides an output buffer (of type CpaFlatBuffer). 178 * 179 * @context 180 * This callback function can be executed in a context that DOES NOT 181 * permit sleeping to occur. 182 * 183 * @assumptions 184 * None 185 * @sideEffects 186 * None 187 * @reentrant 188 * No 189 * @threadSafe 190 * Yes 191 * 192 * @param[in] pCallbackTag Opaque value provided by user while making individual 193 * function call. 194 * @param[in] status Status of the operation. Valid values are 195 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 196 * CPA_STATUS_UNSUPPORTED. 197 * @param[in] pOpData Opaque Pointer to the operation data that was 198 * submitted in the request 199 * @param[in] pOut Pointer to the output buffer provided in the request 200 * invoking this callback. 201 * 202 * @retval 203 * None 204 * @pre 205 * Component has been initialized. 206 * @post 207 * None 208 * @note 209 * None 210 * @see 211 * None 212 * 213 *****************************************************************************/ 214 typedef void (*CpaCyGenFlatBufCbFunc)(void *pCallbackTag, 215 CpaStatus status, 216 void *pOpdata, 217 CpaFlatBuffer *pOut); 218 219 /** 220 ***************************************************************************** 221 * @ingroup cpaCyCommon 222 * Function to return the size of the memory which must be allocated for 223 * the pPrivateMetaData member of CpaBufferList. 224 * 225 * @description 226 * This function is used obtain the size (in bytes) required to allocate 227 * a buffer descriptor for the pPrivateMetaData member in the 228 * CpaBufferList the structure. 229 * Should the function return zero then no meta data is required for the 230 * buffer list. 231 * 232 * @context 233 * This function may be called from any context. 234 * @assumptions 235 * None 236 * @sideEffects 237 * None 238 * @blocking 239 * No 240 * @reentrant 241 * No 242 * @threadSafe 243 * Yes 244 * 245 * @param[in] instanceHandle Handle to an instance of this API. 246 * @param[in] numBuffers The number of pointers in the CpaBufferList. 247 * this is the maximum number of CpaFlatBuffers 248 * which may be contained in this CpaBufferList. 249 * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be 250 * allocated when the client wishes to allocate 251 * a cpaFlatBuffer 252 * 253 * @retval CPA_STATUS_SUCCESS Function executed successfully. 254 * @retval CPA_STATUS_FAIL Function failed. 255 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 256 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 257 * 258 * @pre 259 * None. 260 * @post 261 * None 262 * @note 263 * None 264 * @see 265 * cpaCyGetInstances() 266 * 267 *****************************************************************************/ 268 CpaStatus 269 cpaCyBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, 270 Cpa32U numBuffers, 271 Cpa32U *pSizeInBytes); 272 273 /** 274 ***************************************************************************** 275 * @ingroup cpaCyCommon 276 * Function to return a string indicating the specific error that occurred 277 * for a particular instance. 278 * 279 * @description 280 * When a function invocation on a particular instance returns an error, 281 * the client can invoke this function to query the instance for a null 282 * terminated string which describes the general error condition, and if 283 * available additional text on the specific error. 284 * The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for 285 * the buffer string. 286 * 287 * @context 288 * This function may be called from any context. 289 * @assumptions 290 * None 291 * @sideEffects 292 * None 293 * @blocking 294 * No 295 * @reentrant 296 * No 297 * @threadSafe 298 * Yes 299 * 300 * @param[in] instanceHandle Handle to an instance of this API. 301 * @param[in] errStatus The error condition that occurred 302 * @param[out] pStatusText Pointer to the string buffer that will be 303 * updated with a null terminated status text 304 * string. 305 * The invoking application MUST allocate this 306 * buffer to be CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. 307 * 308 * @retval CPA_STATUS_SUCCESS Function executed successfully. 309 * @retval CPA_STATUS_FAIL Function failed. Note, In this scenario it 310 * is INVALID to call this function a further 311 * time. 312 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 313 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 314 * 315 * @pre 316 * None. 317 * @post 318 * None 319 * @note 320 * None 321 * @see 322 * CpaStatus 323 * 324 *****************************************************************************/ 325 CpaStatus 326 cpaCyGetStatusText(const CpaInstanceHandle instanceHandle, 327 CpaStatus errStatus, 328 Cpa8S *pStatusText); 329 330 /*****************************************************************************/ 331 /* Instance Discovery Functions */ 332 /*****************************************************************************/ 333 /** 334 ***************************************************************************** 335 * @ingroup cpaCyCommon 336 * Get the number of instances that are supported by the API 337 * implementation. 338 * 339 * @description 340 * This function will get the number of instances that are supported 341 * by an implementation of the Cryptographic API. This number is then 342 * used to determine the size of the array that must be passed to 343 * @ref cpaCyGetInstances(). 344 * 345 * @context 346 * This function MUST NOT be called from an interrupt context as it MAY 347 * sleep. 348 * @assumptions 349 * None 350 * @sideEffects 351 * None 352 * @blocking 353 * This function is synchronous and blocking. 354 * @reentrant 355 * No 356 * @threadSafe 357 * Yes 358 * 359 * @param[out] pNumInstances Pointer to where the number of 360 * instances will be written. 361 * 362 * @retval CPA_STATUS_SUCCESS Function executed successfully. 363 * @retval CPA_STATUS_FAIL Function failed. 364 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 365 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 366 * 367 * @pre 368 * None 369 * @post 370 * None 371 * @note 372 * This function operates in a synchronous manner and no asynchronous 373 * callback will be generated 374 * 375 * @see 376 * cpaCyGetInstances 377 * 378 *****************************************************************************/ 379 CpaStatus 380 cpaCyGetNumInstances(Cpa16U *pNumInstances); 381 382 /** 383 ***************************************************************************** 384 * @ingroup cpaCyCommon 385 * Get the handles to the instances that are supported by the 386 * API implementation. 387 * 388 * @description 389 * This function will return handles to the instances that are 390 * supported by an implementation of the Cryptographic API. These 391 * instance handles can then be used as input parameters with other 392 * Cryptographic API functions. 393 * 394 * This function will populate an array that has been allocated by the 395 * caller. The size of this API will have been determined by the 396 * cpaCyGetNumInstances() function. 397 * 398 * @context 399 * This function MUST NOT be called from an interrupt context as it MAY 400 * sleep. 401 * @assumptions 402 * None 403 * @sideEffects 404 * None 405 * @blocking 406 * This function is synchronous and blocking. 407 * @reentrant 408 * No 409 * @threadSafe 410 * Yes 411 * 412 * @param[in] numInstances Size of the array. If the value is not 413 * the same as the number of instances 414 * supported, then an error (@ref 415 * CPA_STATUS_INVALID_PARAM) is returned. 416 * @param[in,out] cyInstances Pointer to where the instance 417 * handles will be written. 418 * 419 * @retval CPA_STATUS_SUCCESS Function executed successfully. 420 * @retval CPA_STATUS_FAIL Function failed. 421 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 422 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 423 * 424 * @pre 425 * None 426 * @post 427 * None 428 * @note 429 * This function operates in a synchronous manner and no asynchronous 430 * callback will be generated 431 * 432 * @see 433 * cpaCyGetNumInstances 434 * 435 *****************************************************************************/ 436 CpaStatus 437 cpaCyGetInstances(Cpa16U numInstances, 438 CpaInstanceHandle *cyInstances); 439 440 /** 441 ***************************************************************************** 442 * @ingroup cpaCyCommon 443 * Function to get information on a particular instance. 444 * 445 * @deprecated 446 * As of v1.3 of the Crypto API, this function has been deprecated, 447 * replaced by @ref cpaCyInstanceGetInfo2. 448 * 449 * @description 450 * This function will provide instance specific information through a 451 * @ref CpaInstanceInfo structure. 452 * 453 * @context 454 * This function may be called from any context. 455 * @assumptions 456 * None 457 * @sideEffects 458 * None 459 * @blocking 460 * No 461 * @reentrant 462 * No 463 * @threadSafe 464 * Yes 465 * 466 * @param[in] instanceHandle Handle to an instance of this API to be 467 * initialized. 468 * @param[out] pInstanceInfo Pointer to the memory location allocated by 469 * the client into which the CpaInstanceInfo 470 * structure will be written. 471 * 472 * @retval CPA_STATUS_SUCCESS Function executed successfully. 473 * @retval CPA_STATUS_FAIL Function failed. 474 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 475 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 476 * 477 * @pre 478 * The client has retrieved an instanceHandle from successive calls to 479 * @ref cpaCyGetNumInstances and @ref cpaCyGetInstances. 480 * @post 481 * None 482 * @note 483 * None 484 * @see 485 * cpaCyGetNumInstances, 486 * cpaCyGetInstances, 487 * CpaInstanceInfo 488 * 489 *****************************************************************************/ 490 CpaStatus CPA_DEPRECATED 491 cpaCyInstanceGetInfo(const CpaInstanceHandle instanceHandle, 492 struct _CpaInstanceInfo * pInstanceInfo); 493 494 /** 495 ***************************************************************************** 496 * @ingroup cpaCyCommon 497 * Function to get information on a particular instance. 498 * 499 * @description 500 * This function will provide instance specific information through a 501 * @ref CpaInstanceInfo2 structure. 502 * Supersedes @ref cpaCyInstanceGetInfo. 503 * 504 * @context 505 * This function may be called from any context. 506 * @assumptions 507 * None 508 * @sideEffects 509 * None 510 * @blocking 511 * No 512 * @reentrant 513 * No 514 * @threadSafe 515 * Yes 516 * 517 * @param[in] instanceHandle Handle to an instance of this API to be 518 * initialized. 519 * @param[out] pInstanceInfo2 Pointer to the memory location allocated by 520 * the client into which the CpaInstanceInfo2 521 * structure will be written. 522 * 523 * @retval CPA_STATUS_SUCCESS Function executed successfully. 524 * @retval CPA_STATUS_FAIL Function failed. 525 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 526 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 527 * 528 * @pre 529 * The client has retrieved an instanceHandle from successive calls to 530 * @ref cpaCyGetNumInstances and @ref cpaCyGetInstances. 531 * @post 532 * None 533 * @note 534 * None 535 * @see 536 * cpaCyGetNumInstances, 537 * cpaCyGetInstances, 538 * CpaInstanceInfo 539 * 540 *****************************************************************************/ 541 CpaStatus 542 cpaCyInstanceGetInfo2(const CpaInstanceHandle instanceHandle, 543 CpaInstanceInfo2 * pInstanceInfo2); 544 545 /*****************************************************************************/ 546 /* Instance Notification Functions */ 547 /*****************************************************************************/ 548 /** 549 ***************************************************************************** 550 * @ingroup cpaCyCommon 551 * Callback function for instance notification support. 552 * 553 * @description 554 * This is the prototype for the instance notification callback function. 555 * The callback function is passed in as a parameter to the 556 * @ref cpaCyInstanceSetNotificationCb function. 557 * 558 * @context 559 * This function will be executed in a context that requires that sleeping 560 * MUST NOT be permitted. 561 * @assumptions 562 * None 563 * @sideEffects 564 * None 565 * @blocking 566 * No 567 * @reentrant 568 * No 569 * @threadSafe 570 * Yes 571 * 572 * @param[in] instanceHandle Instance handle. 573 * @param[in] pCallbackTag Opaque value provided by user while making 574 * individual function calls. 575 * @param[in] instanceEvent The event that will trigger this function to 576 * get invoked. 577 * 578 * @retval 579 * None 580 * @pre 581 * Component has been initialized and the notification function has been 582 * set via the cpaCyInstanceSetNotificationCb function. 583 * @post 584 * None 585 * @note 586 * None 587 * @see 588 * cpaCyInstanceSetNotificationCb(), 589 * 590 *****************************************************************************/ 591 typedef void (*CpaCyInstanceNotificationCbFunc)( 592 const CpaInstanceHandle instanceHandle, 593 void * pCallbackTag, 594 const CpaInstanceEvent instanceEvent); 595 596 /** 597 ***************************************************************************** 598 * @ingroup cpaCyCommon 599 * Subscribe for instance notifications. 600 * 601 * @description 602 * Clients of the CpaCy interface can subscribe for instance notifications 603 * by registering a @ref CpaCyInstanceNotificationCbFunc function. 604 * 605 * @context 606 * This function may be called from any context. 607 * @assumptions 608 * None 609 * @sideEffects 610 * None 611 * @blocking 612 * No 613 * @reentrant 614 * No 615 * @threadSafe 616 * Yes 617 * 618 * @param[in] instanceHandle Instance handle. 619 * @param[in] pInstanceNotificationCb Instance notification callback 620 * function pointer. 621 * @param[in] pCallbackTag Opaque value provided by user while 622 * making individual function calls. 623 * 624 * @retval CPA_STATUS_SUCCESS Function executed successfully. 625 * @retval CPA_STATUS_FAIL Function failed. 626 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 627 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 628 * 629 * @pre 630 * Instance has been initialized. 631 * @post 632 * None 633 * @note 634 * None 635 * @see 636 * CpaCyInstanceNotificationCbFunc 637 * 638 *****************************************************************************/ 639 CpaStatus 640 cpaCyInstanceSetNotificationCb( 641 const CpaInstanceHandle instanceHandle, 642 const CpaCyInstanceNotificationCbFunc pInstanceNotificationCb, 643 void *pCallbackTag); 644 645 #ifdef __cplusplus 646 } /* close the extern "C" { */ 647 #endif 648 649 #endif /* CPA_CY_COMMON_H */ 650