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