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_dsa.h 12 * 13 * @defgroup cpaCyDsa Digital Signature Algorithm (DSA) API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for Public Key Encryption 19 * (Cryptography) Digital Signature Algorithm (DSA) operations. 20 * 21 * Support is provided for FIPS PUB 186-2 with Change Notice 1 22 * specification, and optionally for FIPS PUB 186-3. If an 23 * implementation does not support FIPS PUB 186-3, then the 24 * corresponding functions may return a status of @ref 25 * CPA_STATUS_FAIL. 26 * 27 * Support for FIPS PUB 186-2 with Change Notice 1 implies supporting 28 * the following choice for the pair L and N: 29 * - L = 1024, N = 160 30 * 31 * Support for FIPS PUB 186-3 implies supporting the following choices 32 * for the pair L and N: 33 * 34 * - L = 1024, N = 160 35 * - L = 2048, N = 224 36 * - L = 2048, N = 256 37 * - L = 3072, N = 256 38 * 39 * Only the modular math aspects of DSA parameter generation and message 40 * signature generation and verification are implemented here. For full 41 * DSA support, this DSA API SHOULD be used in conjunction with other 42 * parts of this overall Cryptographic API. In particular the Symmetric 43 * functions (for hashing), the Random Number Generation functions, and 44 * the Prime Number Test functions will be required. 45 * 46 * @note 47 * Large numbers are represented on the QuickAssist API as described 48 * in the Large Number API (@ref cpaCyLn). 49 *****************************************************************************/ 50 51 #ifndef CPA_CY_DSA_H 52 #define CPA_CY_DSA_H 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 #include "cpa_cy_common.h" 59 60 /** 61 ***************************************************************************** 62 * @ingroup cpaCyDsa 63 * DSA P Parameter Generation Operation Data. 64 * @description 65 * This structure contains the operation data for the cpaCyDsaGenPParam 66 * function. The client MUST allocate the memory for this structure and the 67 * items pointed to by this structure. When the structure is passed into 68 * the function, ownership of the memory passes to the function. Ownership 69 * of the memory returns to the client when this structure is returned in 70 * the callback function. 71 * 72 * For optimal performance all data buffers SHOULD be 8-byte aligned. 73 * 74 * All values in this structure are required to be in Most Significant Byte 75 * first order, e.g. X.pData[0] = MSB. 76 * 77 * @note 78 * If the client modifies or frees the memory referenced in this 79 * structure after it has been submitted to the cpaCyDsaGenPParam 80 * function, and before it has been returned in the callback, undefined 81 * behavior will result. 82 * 83 * @see 84 * cpaCyDsaGenPParam() 85 * 86 *****************************************************************************/ 87 typedef struct _CpaCyDsaPParamGenOpData { 88 CpaFlatBuffer X; 89 /**< 2^(L-1) <= X < 2^L (from FIPS 186-3) */ 90 CpaFlatBuffer Q; 91 /**< DSA group parameter q */ 92 } CpaCyDsaPParamGenOpData; 93 94 /** 95 ***************************************************************************** 96 * @ingroup cpaCyDsa 97 * DSA G Parameter Generation Operation Data. 98 * @description 99 * This structure contains the operation data for the cpaCyDsaGenGParam 100 * function. The client MUST allocate the memory for this structure and the 101 * items pointed to by this structure. When the structure is passed into 102 * the function, ownership of the memory passes to the function. Ownership 103 * of the memory returns to the client when this structure is returned in 104 * the callback function. 105 * 106 * All values in this structure are required to be in Most Significant Byte 107 * first order, e.g. P.pData[0] = MSB. 108 * 109 * All numbers MUST be stored in big-endian order. 110 * 111 * @note 112 * If the client modifies or frees the memory referenced in this 113 * structure after it has been submitted to the cpaCyDsaGenGParam 114 * function, and before it has been returned in the callback, undefined 115 * behavior will result. 116 * 117 * @see 118 * cpaCyDsaGenGParam() 119 * 120 *****************************************************************************/ 121 typedef struct _CpaCyDsaGParamGenOpData { 122 CpaFlatBuffer P; 123 /**< DSA group parameter p */ 124 CpaFlatBuffer Q; 125 /**< DSA group parameter q */ 126 CpaFlatBuffer H; 127 /**< any integer with 1 < h < p - 1 */ 128 } CpaCyDsaGParamGenOpData; 129 130 /** 131 ***************************************************************************** 132 * @ingroup cpaCyDsa 133 * DSA Y Parameter Generation Operation Data. 134 * @description 135 * This structure contains the operation data for the cpaCyDsaGenYParam 136 * function. The client MUST allocate the memory for this structure and the 137 * items pointed to by this structure. When the structure is passed into 138 * the function, ownership of the memory passes to the function. Ownership 139 * of the memory returns to the client when this structure is returned in 140 * the callback function. 141 * 142 * For optimal performance all data SHOULD be 8-byte aligned. 143 * 144 * All values in this structure are required to be in Most Significant Byte 145 * first order, e.g. P.pData[0] = MSB. 146 * 147 * @note 148 * If the client modifies or frees the memory referenced in this 149 * structure after it has been submitted to the cpaCyDsaGenYParam 150 * function, and before it has been returned in the callback, undefined 151 * behavior will result. 152 * 153 * @see 154 * cpaCyDsaGenYParam() 155 * 156 *****************************************************************************/ 157 typedef struct _CpaCyDsaYParamGenOpData { 158 CpaFlatBuffer P; 159 /**< DSA group parameter p */ 160 CpaFlatBuffer G; 161 /**< DSA group parameter g */ 162 CpaFlatBuffer X; 163 /**< DSA private key x */ 164 } CpaCyDsaYParamGenOpData; 165 166 /** 167 ***************************************************************************** 168 * @ingroup cpaCyDsa 169 * DSA R Sign Operation Data. 170 * @description 171 * This structure contains the operation data for the cpaCyDsaSignR 172 * function. The client MUST allocate the memory for this structure and the 173 * items pointed to by this structure. When the structure is passed into 174 * the function, ownership of the memory passes to the function. Ownership 175 * of the memory returns to the client when this structure is returned in 176 * the callback function. 177 * 178 * For optimal performance all data SHOULD be 8-byte aligned. 179 * 180 * All values in this structure are required to be in Most Significant Byte 181 * first order, e.g. P.pData[0] = MSB. 182 * 183 * @note 184 * If the client modifies or frees the memory referenced in this 185 * structure after it has been submitted to the cpaCyDsaSignR 186 * function, and before it has been returned in the callback, undefined 187 * behavior will result. 188 * 189 * @see 190 * cpaCyDsaSignR() 191 * 192 *****************************************************************************/ 193 typedef struct _CpaCyDsaRSignOpData { 194 CpaFlatBuffer P; 195 /**< DSA group parameter p */ 196 CpaFlatBuffer Q; 197 /**< DSA group parameter q */ 198 CpaFlatBuffer G; 199 /**< DSA group parameter g */ 200 CpaFlatBuffer K; 201 /**< DSA secret parameter k for signing */ 202 } CpaCyDsaRSignOpData; 203 204 /** 205 ***************************************************************************** 206 * @ingroup cpaCyDsa 207 * DSA S Sign Operation Data. 208 * @description 209 * This structure contains the operation data for the cpaCyDsaSignS 210 * function. The client MUST allocate the memory for this structure and 211 * the items pointed to by this structure. When the structure is passed 212 * into the function, ownership of the memory passes to the function. 213 * Ownership of the memory returns to the client when this structure is 214 * returned in the callback function. 215 * 216 * For optimal performance all data SHOULD be 8-byte aligned. 217 * 218 * All values in this structure are required to be in Most Significant Byte 219 * first order, e.g. Q.pData[0] = MSB. 220 * 221 * @note 222 * If the client modifies or frees the memory referenced in this 223 * structure after it has been submitted to the cpaCyDsaSignS 224 * function, and before it has been returned in the callback, undefined 225 * behavior will result. 226 * 227 * @see 228 * cpaCyDsaSignS() 229 * 230 *****************************************************************************/ 231 typedef struct _CpaCyDsaSSignOpData { 232 CpaFlatBuffer Q; 233 /**< DSA group parameter q */ 234 CpaFlatBuffer X; 235 /**< DSA private key x */ 236 CpaFlatBuffer K; 237 /**< DSA secret parameter k for signing */ 238 CpaFlatBuffer R; 239 /**< DSA message signature r */ 240 CpaFlatBuffer Z; 241 /**< The leftmost min(N, outlen) bits of Hash(M), where: 242 * - N is the bit length of q 243 * - outlen is the bit length of the hash function output block 244 * - M is the message to be signed 245 */ 246 } CpaCyDsaSSignOpData; 247 248 /** 249 ***************************************************************************** 250 * @ingroup cpaCyDsa 251 * DSA R & S Sign Operation Data. 252 * @description 253 * This structure contains the operation data for the cpaCyDsaSignRS 254 * function. The client MUST allocate the memory for this structure and the 255 * items pointed to by this structure. When the structure is passed into 256 * the function, ownership of the memory passes to the function. Ownership 257 * of the memory returns to the client when this structure is returned in 258 * the callback function. 259 * 260 * For optimal performance all data SHOULD be 8-byte aligned. 261 * 262 * All values in this structure are required to be in Most Significant Byte 263 * first order, e.g. P.pData[0] = MSB. 264 * 265 * @note 266 * If the client modifies or frees the memory referenced in this 267 * structure after it has been submitted to the cpaCyDsaSignRS 268 * function, and before it has been returned in the callback, undefined 269 * behavior will result. 270 * 271 * @see 272 * cpaCyDsaSignRS() 273 * 274 *****************************************************************************/ 275 typedef struct _CpaCyDsaRSSignOpData { 276 CpaFlatBuffer P; 277 /**< DSA group parameter p */ 278 CpaFlatBuffer Q; 279 /**< DSA group parameter q */ 280 CpaFlatBuffer G; 281 /**< DSA group parameter g */ 282 CpaFlatBuffer X; 283 /**< DSA private key x */ 284 CpaFlatBuffer K; 285 /**< DSA secret parameter k for signing */ 286 CpaFlatBuffer Z; 287 /**< The leftmost min(N, outlen) bits of Hash(M), where: 288 * - N is the bit length of q 289 * - outlen is the bit length of the hash function output block 290 * - M is the message to be signed 291 */ 292 } CpaCyDsaRSSignOpData; 293 294 /** 295 ***************************************************************************** 296 * @ingroup cpaCyDsa 297 * DSA Verify Operation Data. 298 * @description 299 * This structure contains the operation data for the cpaCyDsaVerify 300 * function. The client MUST allocate the memory for this structure and the 301 * items pointed to by this structure. When the structure is passed into 302 * the function, ownership of the memory passes to the function. Ownership 303 * of the memory returns to the client when this structure is returned in 304 * the callback function. 305 * 306 * For optimal performance all data SHOULD be 8-byte aligned. 307 * 308 * All values in this structure are required to be in Most Significant Byte 309 * first order, e.g. P.pData[0] = MSB. 310 * 311 * @note 312 * If the client modifies or frees the memory referenced in this 313 * structure after it has been submitted to the cpaCyDsaVerify 314 * function, and before it has been returned in the callback, undefined 315 * behavior will result. 316 * 317 * @see 318 * cpaCyDsaVerify() 319 * 320 *****************************************************************************/ 321 typedef struct _CpaCyDsaVerifyOpData { 322 CpaFlatBuffer P; 323 /**< DSA group parameter p */ 324 CpaFlatBuffer Q; 325 /**< DSA group parameter q */ 326 CpaFlatBuffer G; 327 /**< DSA group parameter g */ 328 CpaFlatBuffer Y; 329 /**< DSA public key y */ 330 CpaFlatBuffer Z; 331 /**< The leftmost min(N, outlen) bits of Hash(M'), where: 332 * - N is the bit length of q 333 * - outlen is the bit length of the hash function output block 334 * - M is the message to be signed 335 */ 336 CpaFlatBuffer R; 337 /**< DSA message signature r */ 338 CpaFlatBuffer S; 339 /**< DSA message signature s */ 340 } CpaCyDsaVerifyOpData; 341 342 /** 343 ***************************************************************************** 344 * @ingroup cpaCyDsa 345 * Cryptographic DSA Statistics. 346 * @deprecated 347 * As of v1.3 of the Crypto API, this structure has been deprecated, 348 * replaced by @ref CpaCyDsaStats64. 349 * @description 350 * This structure contains statistics on the Cryptographic DSA 351 * operations. Statistics are set to zero when the component is 352 * initialized, and are collected per instance. 353 ****************************************************************************/ 354 typedef struct _CpaCyDsaStats { 355 Cpa32U numDsaPParamGenRequests; 356 /**< Total number of successful DSA P parameter generation requests. */ 357 Cpa32U numDsaPParamGenRequestErrors; 358 /**< Total number of DSA P parameter generation requests that had an 359 * error and could not be processed. */ 360 Cpa32U numDsaPParamGenCompleted; 361 /**< Total number of DSA P parameter generation operations that 362 * completed successfully. */ 363 Cpa32U numDsaPParamGenCompletedErrors; 364 /**< Total number of DSA P parameter generation operations that could 365 * not be completed successfully due to errors. */ 366 Cpa32U numDsaGParamGenRequests; 367 /**< Total number of successful DSA G parameter generation requests. */ 368 Cpa32U numDsaGParamGenRequestErrors; 369 /**< Total number of DSA G parameter generation requests that had an 370 * error and could not be processed. */ 371 Cpa32U numDsaGParamGenCompleted; 372 /**< Total number of DSA G parameter generation operations that 373 * completed successfully. */ 374 Cpa32U numDsaGParamGenCompletedErrors; 375 /**< Total number of DSA G parameter generation operations that could 376 * not be completed successfully due to errors. */ 377 Cpa32U numDsaYParamGenRequests; 378 /**< Total number of successful DSA Y parameter generation requests. */ 379 Cpa32U numDsaYParamGenRequestErrors; 380 /**< Total number of DSA Y parameter generation requests that had an 381 * error and could not be processed. */ 382 Cpa32U numDsaYParamGenCompleted; 383 /**< Total number of DSA Y parameter generation operations that 384 * completed successfully. */ 385 Cpa32U numDsaYParamGenCompletedErrors; 386 /**< Total number of DSA Y parameter generation operations that could 387 * not be completed successfully due to errors. */ 388 Cpa32U numDsaRSignRequests; 389 /**< Total number of successful DSA R sign generation requests. */ 390 Cpa32U numDsaRSignRequestErrors; 391 /**< Total number of DSA R sign requests that had an error and could 392 * not be processed. */ 393 Cpa32U numDsaRSignCompleted; 394 /**< Total number of DSA R sign operations that completed 395 * successfully. */ 396 Cpa32U numDsaRSignCompletedErrors; 397 /**< Total number of DSA R sign operations that could not be completed 398 * successfully due to errors. */ 399 Cpa32U numDsaSSignRequests; 400 /**< Total number of successful DSA S sign generation requests. */ 401 Cpa32U numDsaSSignRequestErrors; 402 /**< Total number of DSA S sign requests that had an error and could 403 * not be processed. */ 404 Cpa32U numDsaSSignCompleted; 405 /**< Total number of DSA S sign operations that completed 406 * successfully. */ 407 Cpa32U numDsaSSignCompletedErrors; 408 /**< Total number of DSA S sign operations that could not be completed 409 * successfully due to errors. */ 410 Cpa32U numDsaRSSignRequests; 411 /**< Total number of successful DSA RS sign generation requests. */ 412 Cpa32U numDsaRSSignRequestErrors; 413 /**< Total number of DSA RS sign requests that had an error and could 414 * not be processed. */ 415 Cpa32U numDsaRSSignCompleted; 416 /**< Total number of DSA RS sign operations that completed 417 * successfully. */ 418 Cpa32U numDsaRSSignCompletedErrors; 419 /**< Total number of DSA RS sign operations that could not be completed 420 * successfully due to errors. */ 421 Cpa32U numDsaVerifyRequests; 422 /**< Total number of successful DSA verify generation requests. */ 423 Cpa32U numDsaVerifyRequestErrors; 424 /**< Total number of DSA verify requests that had an error and could 425 * not be processed. */ 426 Cpa32U numDsaVerifyCompleted; 427 /**< Total number of DSA verify operations that completed 428 * successfully. */ 429 Cpa32U numDsaVerifyCompletedErrors; 430 /**< Total number of DSA verify operations that could not be completed 431 * successfully due to errors. */ 432 Cpa32U numDsaVerifyFailures; 433 /**< Total number of DSA verify operations that executed successfully 434 * but the outcome of the test was that the verification failed. 435 * Note that this does not indicate an error. */ 436 } CpaCyDsaStats CPA_DEPRECATED; 437 438 /** 439 ***************************************************************************** 440 * @ingroup cpaCyDsa 441 * Cryptographic DSA Statistics (64-bit version). 442 * @description 443 * This structure contains 64-bit version of the statistics on the 444 * Cryptographic DSA operations. 445 * Statistics are set to zero when the component is 446 * initialized, and are collected per instance. 447 ****************************************************************************/ 448 typedef struct _CpaCyDsaStats64 { 449 Cpa64U numDsaPParamGenRequests; 450 /**< Total number of successful DSA P parameter generation requests. */ 451 Cpa64U numDsaPParamGenRequestErrors; 452 /**< Total number of DSA P parameter generation requests that had an 453 * error and could not be processed. */ 454 Cpa64U numDsaPParamGenCompleted; 455 /**< Total number of DSA P parameter generation operations that 456 * completed successfully. */ 457 Cpa64U numDsaPParamGenCompletedErrors; 458 /**< Total number of DSA P parameter generation operations that could 459 * not be completed successfully due to errors. */ 460 Cpa64U numDsaGParamGenRequests; 461 /**< Total number of successful DSA G parameter generation requests. */ 462 Cpa64U numDsaGParamGenRequestErrors; 463 /**< Total number of DSA G parameter generation requests that had an 464 * error and could not be processed. */ 465 Cpa64U numDsaGParamGenCompleted; 466 /**< Total number of DSA G parameter generation operations that 467 * completed successfully. */ 468 Cpa64U numDsaGParamGenCompletedErrors; 469 /**< Total number of DSA G parameter generation operations that could 470 * not be completed successfully due to errors. */ 471 Cpa64U numDsaYParamGenRequests; 472 /**< Total number of successful DSA Y parameter generation requests. */ 473 Cpa64U numDsaYParamGenRequestErrors; 474 /**< Total number of DSA Y parameter generation requests that had an 475 * error and could not be processed. */ 476 Cpa64U numDsaYParamGenCompleted; 477 /**< Total number of DSA Y parameter generation operations that 478 * completed successfully. */ 479 Cpa64U numDsaYParamGenCompletedErrors; 480 /**< Total number of DSA Y parameter generation operations that could 481 * not be completed successfully due to errors. */ 482 Cpa64U numDsaRSignRequests; 483 /**< Total number of successful DSA R sign generation requests. */ 484 Cpa64U numDsaRSignRequestErrors; 485 /**< Total number of DSA R sign requests that had an error and could 486 * not be processed. */ 487 Cpa64U numDsaRSignCompleted; 488 /**< Total number of DSA R sign operations that completed 489 * successfully. */ 490 Cpa64U numDsaRSignCompletedErrors; 491 /**< Total number of DSA R sign operations that could not be completed 492 * successfully due to errors. */ 493 Cpa64U numDsaSSignRequests; 494 /**< Total number of successful DSA S sign generation requests. */ 495 Cpa64U numDsaSSignRequestErrors; 496 /**< Total number of DSA S sign requests that had an error and could 497 * not be processed. */ 498 Cpa64U numDsaSSignCompleted; 499 /**< Total number of DSA S sign operations that completed 500 * successfully. */ 501 Cpa64U numDsaSSignCompletedErrors; 502 /**< Total number of DSA S sign operations that could not be completed 503 * successfully due to errors. */ 504 Cpa64U numDsaRSSignRequests; 505 /**< Total number of successful DSA RS sign generation requests. */ 506 Cpa64U numDsaRSSignRequestErrors; 507 /**< Total number of DSA RS sign requests that had an error and could 508 * not be processed. */ 509 Cpa64U numDsaRSSignCompleted; 510 /**< Total number of DSA RS sign operations that completed 511 * successfully. */ 512 Cpa64U numDsaRSSignCompletedErrors; 513 /**< Total number of DSA RS sign operations that could not be completed 514 * successfully due to errors. */ 515 Cpa64U numDsaVerifyRequests; 516 /**< Total number of successful DSA verify generation requests. */ 517 Cpa64U numDsaVerifyRequestErrors; 518 /**< Total number of DSA verify requests that had an error and could 519 * not be processed. */ 520 Cpa64U numDsaVerifyCompleted; 521 /**< Total number of DSA verify operations that completed 522 * successfully. */ 523 Cpa64U numDsaVerifyCompletedErrors; 524 /**< Total number of DSA verify operations that could not be completed 525 * successfully due to errors. */ 526 Cpa64U numDsaVerifyFailures; 527 /**< Total number of DSA verify operations that executed successfully 528 * but the outcome of the test was that the verification failed. 529 * Note that this does not indicate an error. */ 530 } CpaCyDsaStats64; 531 532 /** 533 ***************************************************************************** 534 * @ingroup cpaCyDsa 535 * Definition of a generic callback function invoked for a number of the 536 * DSA API functions.. 537 * 538 * @description 539 * This is the prototype for the cpaCyDsaGenCbFunc callback function. 540 * 541 * @context 542 * This callback function can be executed in a context that DOES NOT 543 * permit sleeping to occur. 544 * @assumptions 545 * None 546 * @sideEffects 547 * None 548 * @reentrant 549 * No 550 * @threadSafe 551 * Yes 552 * 553 * @param[in] pCallbackTag User-supplied value to help identify request. 554 * @param[in] status Status of the operation. Valid values are 555 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 556 * CPA_STATUS_UNSUPPORTED. 557 * @param[in] pOpData Opaque pointer to Operation data supplied in 558 * request. 559 * @param[in] protocolStatus The result passes/fails the DSA protocol 560 * related checks. 561 * @param[in] pOut Output data from the request. 562 * 563 * @retval 564 * None 565 * @pre 566 * Component has been initialized. 567 * @post 568 * None 569 * @note 570 * None 571 * @see 572 * cpaCyDsaGenPParam() 573 * cpaCyDsaGenGParam() 574 * cpaCyDsaSignR() 575 * cpaCyDsaSignS() 576 * 577 *****************************************************************************/ 578 typedef void (*CpaCyDsaGenCbFunc)(void *pCallbackTag, 579 CpaStatus status, 580 void *pOpData, 581 CpaBoolean protocolStatus, 582 CpaFlatBuffer *pOut); 583 584 /** 585 ***************************************************************************** 586 * @ingroup cpaCyDsa 587 * Definition of callback function invoked for cpaCyDsaSignRS 588 * requests. 589 * 590 * @description 591 * This is the prototype for the cpaCyDsaSignRS callback function, which 592 * will provide the DSA message signature r and s parameters. 593 * 594 * @context 595 * This callback function can be executed in a context that DOES NOT 596 * permit sleeping to occur. 597 * @assumptions 598 * None 599 * @sideEffects 600 * None 601 * @reentrant 602 * No 603 * @threadSafe 604 * Yes 605 * 606 * @param[in] pCallbackTag User-supplied value to help identify request. 607 * @param[in] status Status of the operation. Valid values are 608 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 609 * CPA_STATUS_UNSUPPORTED. 610 * @param[in] pOpData Operation data pointer supplied in request. 611 * @param[in] protocolStatus The result passes/fails the DSA protocol 612 * related checks. 613 * @param[in] pR DSA message signature r. 614 * @param[in] pS DSA message signature s. 615 * 616 * 617 * @retval 618 * None 619 * @pre 620 * Component has been initialized. 621 * @post 622 * None 623 * @note 624 * None 625 * @see 626 * cpaCyDsaSignRS() 627 * 628 *****************************************************************************/ 629 typedef void (*CpaCyDsaRSSignCbFunc)(void *pCallbackTag, 630 CpaStatus status, 631 void *pOpData, 632 CpaBoolean protocolStatus, 633 CpaFlatBuffer *pR, 634 CpaFlatBuffer *pS); 635 636 /** 637 ***************************************************************************** 638 * @ingroup cpaCyDsa 639 * Definition of callback function invoked for cpaCyDsaVerify 640 * requests. 641 * 642 * @description 643 * This is the prototype for the cpaCyDsaVerify callback function. 644 * 645 * @context 646 * This callback function can be executed in a context that DOES NOT 647 * permit sleeping to occur. 648 * @assumptions 649 * None 650 * @sideEffects 651 * None 652 * @reentrant 653 * No 654 * @threadSafe 655 * Yes 656 * 657 * @param[in] pCallbackTag User-supplied value to help identify request. 658 * @param[in] status Status of the operation. Valid values are 659 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 660 * CPA_STATUS_UNSUPPORTED. 661 * @param[in] pOpData Operation data pointer supplied in request. 662 * @param[in] verifyStatus The verification passed or failed. 663 * 664 * @retval 665 * None 666 * @pre 667 * Component has been initialized. 668 * @post 669 * None 670 * @note 671 * None 672 * @see 673 * cpaCyDsaVerify() 674 * 675 *****************************************************************************/ 676 typedef void (*CpaCyDsaVerifyCbFunc)(void *pCallbackTag, 677 CpaStatus status, 678 void *pOpData, 679 CpaBoolean verifyStatus); 680 681 /** 682 ***************************************************************************** 683 * @ingroup cpaCyDsa 684 * Generate DSA P Parameter. 685 * 686 * @description 687 * 688 * This function performs FIPS 186-3 Appendix A.1.1.2 steps 11.4 and 11.5, 689 * and part of step 11.7: 690 * 691 * 11.4. c = X mod 2q. 692 * 11.5. p = X - (c - 1). 693 * 11.7. Test whether or not p is prime as specified in Appendix C.3. 694 * [Note that a GCD test against ~1400 small primes is performed 695 * on p to eliminate ~94% of composites - this is NOT a "robust" 696 * primality test, as specified in Appendix C.3.] 697 * 698 * The protocol status, returned in the callback function as parameter 699 * protocolStatus (or, in the case of synchronous invocation, in the 700 * parameter *pProtocolStatus) is used to indicate whether the value p is 701 * in the right range and has passed the limited primality test. 702 * 703 * Specifically, (protocolStatus == CPA_TRUE) means p is in the right range 704 * and SHOULD be subjected to a robust primality test as specified in 705 * FIPS 186-3 Appendix C.3 (for example, 40 rounds of Miller-Rabin). 706 * Meanwhile, (protocolStatus == CPA_FALSE) means p is either composite, 707 * or p < 2^(L-1), in which case the value of p gets set to zero. 708 * 709 * @context 710 * When called as an asynchronous function it cannot sleep. It can be 711 * executed in a context that does not permit sleeping. 712 * When called as a synchronous function it may sleep. It MUST NOT be 713 * executed in a context that DOES NOT permit sleeping. 714 * @assumptions 715 * None 716 * @sideEffects 717 * None 718 * @blocking 719 * Yes when configured to operate in synchronous mode. 720 * @reentrant 721 * No 722 * @threadSafe 723 * Yes 724 * 725 * @param[in] instanceHandle Instance handle. 726 * @param[in] pCb Callback function pointer. If this is 727 * set to a NULL value the function will 728 * operate synchronously. 729 * @param[in] pCallbackTag User-supplied value to help identify request. 730 * @param[in] pOpData Structure containing all the data needed to 731 * perform the operation. The client code 732 * allocates the memory for this structure. This 733 * component takes ownership of the memory until 734 * it is returned in the callback. 735 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 736 * related checks. 737 * @param[out] pP Candidate for DSA parameter p, p odd and 738 * 2^(L-1) < p < X 739 * On invocation the callback function will 740 * contain this parameter in the pOut parameter. 741 * 742 * 743 * @retval CPA_STATUS_SUCCESS Function executed successfully. 744 * @retval CPA_STATUS_FAIL Function failed. 745 * @retval CPA_STATUS_RETRY Resubmit the request. 746 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 747 * @retval CPA_STATUS_RESOURCE Error related to system resources. 748 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 749 * the request. 750 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 751 * 752 * @pre 753 * The component has been initialized. 754 * @post 755 * None 756 * @note 757 * When pCb is non-NULL an asynchronous callback of type 758 * CpaCyDsaPParamGenCbFunc is generated in response to this 759 * function call. 760 * For optimal performance, data pointers SHOULD be 8-byte aligned. 761 * 762 * @see 763 * CpaCyDsaPParamGenOpData, 764 * CpaCyDsaGenCbFunc 765 * 766 *****************************************************************************/ 767 CpaStatus 768 cpaCyDsaGenPParam(const CpaInstanceHandle instanceHandle, 769 const CpaCyDsaGenCbFunc pCb, 770 void * pCallbackTag, 771 const CpaCyDsaPParamGenOpData *pOpData, 772 CpaBoolean *pProtocolStatus, 773 CpaFlatBuffer *pP); 774 775 /** 776 ***************************************************************************** 777 * @ingroup cpaCyDsa 778 * Generate DSA G Parameter. 779 * 780 * @description 781 * This function performs FIPS 186-3 Appendix A.2.1, steps 1 and 3, 782 * and part of step 4: 783 * 784 * 1. e = (p - 1)/q. 785 * 3. Set g = h^e mod p. 786 * 4. If (g = 1), then go to step 2. 787 * Here, the implementation will check for g == 1, and return 788 * status accordingly. 789 * 790 * 791 * The protocol status, returned in the callback function as parameter 792 * protocolStatus (or, in the case of synchronous invocation, in the 793 * parameter *pProtocolStatus) is used to indicate whether the value g is 794 * acceptable. 795 * 796 * Specifically, (protocolStatus == CPA_TRUE) means g is acceptable. 797 * Meanwhile, (protocolStatus == CPA_FALSE) means g == 1, so a 798 * different value of h SHOULD be used to generate another value of g. 799 * 800 * @context 801 * When called as an asynchronous function it cannot sleep. It can be 802 * executed in a context that does not permit sleeping. 803 * When called as a synchronous function it may sleep. It MUST NOT be 804 * executed in a context that DOES NOT permit sleeping. 805 * @assumptions 806 * None 807 * @sideEffects 808 * None 809 * @blocking 810 * Yes when configured to operate in synchronous mode. 811 * @reentrant 812 * No 813 * @threadSafe 814 * Yes 815 * 816 * @param[in] instanceHandle Instance handle. 817 * @param[in] pCb Callback function pointer. If this is set to a 818 * NULL value the function will operate 819 * synchronously. 820 * @param[in] pCallbackTag User-supplied value to help identify request. 821 * @param[in] pOpData Structure containing all the data needed to 822 * perform the operation. The client code 823 * allocates the memory for this structure. This 824 * component takes ownership of the memory until 825 * it is returned in the callback. 826 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 827 * related checks. 828 * @param[out] pG g = h^((p-1)/q) mod p. 829 * On invocation the callback function will 830 * contain this parameter in the pOut parameter. 831 * 832 * @retval CPA_STATUS_SUCCESS Function executed successfully. 833 * @retval CPA_STATUS_FAIL Function failed. 834 * @retval CPA_STATUS_RETRY Resubmit the request. 835 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 836 * @retval CPA_STATUS_RESOURCE Error related to system resources. 837 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 838 * the request. 839 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 840 * 841 * @pre 842 * The component has been initialized via cpaCyStartInstance function. 843 * @post 844 * None 845 * @note 846 * When pCb is non-NULL an asynchronous callback of type 847 * CpaCyDsaGParamGenCbFunc is generated in response to this 848 * function call. 849 * For optimal performance, data pointers SHOULD be 8-byte aligned. 850 * 851 * @see 852 * CpaCyDsaGParamGenOpData, 853 * CpaCyDsaGenCbFunc 854 * 855 *****************************************************************************/ 856 CpaStatus 857 cpaCyDsaGenGParam(const CpaInstanceHandle instanceHandle, 858 const CpaCyDsaGenCbFunc pCb, 859 void *pCallbackTag, 860 const CpaCyDsaGParamGenOpData *pOpData, 861 CpaBoolean *pProtocolStatus, 862 CpaFlatBuffer *pG); 863 864 /** 865 ***************************************************************************** 866 * @ingroup cpaCyDsa 867 * Generate DSA Y Parameter. 868 * 869 * @description 870 * 871 * This function performs modular exponentiation to generate y as 872 * described in FIPS 186-3 section 4.1: 873 * y = g^x mod p 874 * 875 * @context 876 * When called as an asynchronous function it cannot sleep. It can be 877 * executed in a context that does not permit sleeping. 878 * When called as a synchronous function it may sleep. It MUST NOT be 879 * executed in a context that DOES NOT permit sleeping. 880 * @assumptions 881 * None 882 * @sideEffects 883 * None 884 * @blocking 885 * Yes when configured to operate in synchronous mode. 886 * @reentrant 887 * No 888 * @threadSafe 889 * Yes 890 * 891 * @param[in] instanceHandle Instance handle. 892 * @param[in] pCb Callback function pointer. If this is set to a 893 * NULL value the function will operate 894 * synchronously. 895 * @param[in] pCallbackTag User-supplied value to help identify request. 896 * @param[in] pOpData Structure containing all the data needed to 897 * perform the operation. The client code 898 * allocates the memory for this structure. This 899 * component takes ownership of the memory until 900 * it is returned in the callback. 901 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 902 * related checks. 903 * @param[out] pY y = g^x mod p* 904 * On invocation the callback function will 905 * contain this parameter in the pOut parameter. 906 * 907 * @retval CPA_STATUS_SUCCESS Function executed successfully. 908 * @retval CPA_STATUS_FAIL Function failed. 909 * @retval CPA_STATUS_RETRY Resubmit the request. 910 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 911 * @retval CPA_STATUS_RESOURCE Error related to system resources. 912 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 913 * the request. 914 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 915 * 916 * @pre 917 * The component has been initialized via cpaCyStartInstance function. 918 * @post 919 * None 920 * @note 921 * When pCb is non-NULL an asynchronous callback of type 922 * CpaCyDsaYParamGenCbFunc is generated in response to this 923 * function call. 924 * For optimal performance, data pointers SHOULD be 8-byte aligned. 925 * 926 * @see 927 * CpaCyDsaYParamGenOpData, 928 * CpaCyDsaGenCbFunc 929 * 930 *****************************************************************************/ 931 CpaStatus 932 cpaCyDsaGenYParam(const CpaInstanceHandle instanceHandle, 933 const CpaCyDsaGenCbFunc pCb, 934 void *pCallbackTag, 935 const CpaCyDsaYParamGenOpData *pOpData, 936 CpaBoolean *pProtocolStatus, 937 CpaFlatBuffer *pY); 938 939 /** 940 ***************************************************************************** 941 * @ingroup cpaCyDsa 942 * Generate DSA R Signature. 943 * 944 * @description 945 * This function generates the DSA R signature as described in FIPS 186-3 946 * Section 4.6: 947 * r = (g^k mod p) mod q 948 * 949 * The protocol status, returned in the callback function as parameter 950 * protocolStatus (or, in the case of synchronous invocation, in the 951 * parameter *pProtocolStatus) is used to indicate whether the value r == 0. 952 * 953 * Specifically, (protocolStatus == CPA_TRUE) means r != 0, while 954 * (protocolStatus == CPA_FALSE) means r == 0. 955 * 956 * Generation of signature r does not depend on the content of the message 957 * being signed, so this operation can be done in advance for different 958 * values of k. Then once each message becomes available only the 959 * signature s needs to be generated. 960 * 961 * @context 962 * When called as an asynchronous function it cannot sleep. It can be 963 * executed in a context that does not permit sleeping. 964 * When called as a synchronous function it may sleep. It MUST NOT be 965 * executed in a context that DOES NOT permit sleeping. 966 * @assumptions 967 * None 968 * @sideEffects 969 * None 970 * @blocking 971 * Yes when configured to operate in synchronous mode. 972 * @reentrant 973 * No 974 * @threadSafe 975 * Yes 976 * 977 * @param[in] instanceHandle Instance handle. 978 * @param[in] pCb Callback function pointer. If this is set to a 979 * NULL value the function will operate 980 * synchronously. 981 * @param[in] pCallbackTag User-supplied value to help identify request. 982 * @param[in] pOpData Structure containing all the data needed to 983 * perform the operation. The client code 984 * allocates the memory for this structure. This 985 * component takes ownership of the memory until 986 * it is returned in the callback. 987 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 988 * related checks. 989 * @param[out] pR DSA message signature r. 990 * On invocation the callback function will 991 * contain this parameter in the pOut parameter. 992 * 993 * 994 * @retval CPA_STATUS_SUCCESS Function executed successfully. 995 * @retval CPA_STATUS_FAIL Function failed. 996 * @retval CPA_STATUS_RETRY Resubmit the request. 997 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 998 * @retval CPA_STATUS_RESOURCE Error related to system resources. 999 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1000 * the request. 1001 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1002 * 1003 * @pre 1004 * The component has been initialized via cpaCyStartInstance function. 1005 * @post 1006 * None 1007 * @note 1008 * When pCb is non-NULL an asynchronous callback of type 1009 * CpaCyDsaRSignCbFunc is generated in response to this function 1010 * call. 1011 * For optimal performance, data pointers SHOULD be 8-byte aligned. 1012 * 1013 * @see 1014 * CpaCyDsaRSignOpData, 1015 * CpaCyDsaGenCbFunc, 1016 * cpaCyDsaSignS(), 1017 * cpaCyDsaSignRS() 1018 * 1019 *****************************************************************************/ 1020 CpaStatus 1021 cpaCyDsaSignR(const CpaInstanceHandle instanceHandle, 1022 const CpaCyDsaGenCbFunc pCb, 1023 void *pCallbackTag, 1024 const CpaCyDsaRSignOpData *pOpData, 1025 CpaBoolean *pProtocolStatus, 1026 CpaFlatBuffer *pR); 1027 1028 /** 1029 ***************************************************************************** 1030 * @ingroup cpaCyDsa 1031 * Generate DSA S Signature. 1032 * 1033 * @description 1034 * This function generates the DSA S signature as described in FIPS 186-3 1035 * Section 4.6: 1036 * s = (k^-1(z + xr)) mod q 1037 * 1038 * Here, z = the leftmost min(N, outlen) bits of Hash(M). This function 1039 * does not perform the SHA digest; z is computed by the caller and 1040 * passed as a parameter in the pOpData field. 1041 * 1042 * The protocol status, returned in the callback function as parameter 1043 * protocolStatus (or, in the case of synchronous invocation, in the 1044 * parameter *pProtocolStatus) is used to indicate whether the value s == 0. 1045 * 1046 * Specifically, (protocolStatus == CPA_TRUE) means s != 0, while 1047 * (protocolStatus == CPA_FALSE) means s == 0. 1048 * 1049 * If signature r has been generated in advance, then this function can be 1050 * used to generate the signature s once the message becomes available. 1051 * 1052 * @context 1053 * When called as an asynchronous function it cannot sleep. It can be 1054 * executed in a context that does not permit sleeping. 1055 * When called as a synchronous function it may sleep. It MUST NOT be 1056 * executed in a context that DOES NOT permit sleeping. 1057 * @assumptions 1058 * None 1059 * @sideEffects 1060 * None 1061 * @blocking 1062 * Yes when configured to operate in synchronous mode. 1063 * @reentrant 1064 * No 1065 * @threadSafe 1066 * Yes 1067 * 1068 * @param[in] instanceHandle Instance handle. 1069 * @param[in] pCb Callback function pointer. If this is set to a 1070 * NULL value the function will operate 1071 * synchronously. 1072 * @param[in] pCallbackTag User-supplied value to help identify request. 1073 * @param[in] pOpData Structure containing all the data needed to 1074 * perform the operation. The client code 1075 * allocates the memory for this structure. This 1076 * component takes ownership of the memory until 1077 * it is returned in the callback. 1078 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 1079 * related checks. 1080 * @param[out] pS DSA message signature s. 1081 * On invocation the callback function will 1082 * contain this parameter in the pOut parameter. 1083 * 1084 * 1085 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1086 * @retval CPA_STATUS_FAIL Function failed. 1087 * @retval CPA_STATUS_RETRY Resubmit the request. 1088 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1089 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1090 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1091 * the request. 1092 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1093 * 1094 * @pre 1095 * The component has been initialized via cpaCyStartInstance function. 1096 * @post 1097 * None 1098 * @note 1099 * When pCb is non-NULL an asynchronous callback of type 1100 * CpaCyDsaSSignCbFunc is generated in response to this function 1101 * call. 1102 * For optimal performance, data pointers SHOULD be 8-byte aligned. 1103 * 1104 * @see 1105 * CpaCyDsaSSignOpData, 1106 * CpaCyDsaGenCbFunc, 1107 * cpaCyDsaSignR(), 1108 * cpaCyDsaSignRS() 1109 * 1110 *****************************************************************************/ 1111 CpaStatus 1112 cpaCyDsaSignS(const CpaInstanceHandle instanceHandle, 1113 const CpaCyDsaGenCbFunc pCb, 1114 void *pCallbackTag, 1115 const CpaCyDsaSSignOpData *pOpData, 1116 CpaBoolean *pProtocolStatus, 1117 CpaFlatBuffer *pS); 1118 1119 /** 1120 ***************************************************************************** 1121 * @ingroup cpaCyDsa 1122 * Generate DSA R and S Signatures. 1123 * 1124 * @description 1125 * This function generates the DSA R and S signatures as described in 1126 * FIPS 186-3 Section 4.6: 1127 * 1128 * r = (g^k mod p) mod q 1129 * s = (k^-1(z + xr)) mod q 1130 * 1131 * Here, z = the leftmost min(N, outlen) bits of Hash(M). This function 1132 * does not perform the SHA digest; z is computed by the caller and 1133 * passed as a parameter in the pOpData field. 1134 * 1135 * The protocol status, returned in the callback function as parameter 1136 * protocolStatus (or, in the case of synchronous invocation, in the 1137 * parameter *pProtocolStatus) is used to indicate whether either of 1138 * the values r or s are zero. 1139 * 1140 * Specifically, (protocolStatus == CPA_TRUE) means neither is zero (i.e. 1141 * (r != 0) && (s != 0)), while (protocolStatus == CPA_FALSE) means that at 1142 * least one of r or s is zero (i.e. (r == 0) || (s == 0)). 1143 * 1144 * @context 1145 * When called as an asynchronous function it cannot sleep. It can be 1146 * executed in a context that does not permit sleeping. 1147 * When called as a synchronous function it may sleep. It MUST NOT be 1148 * executed in a context that DOES NOT permit sleeping. 1149 * @assumptions 1150 * None 1151 * @sideEffects 1152 * None 1153 * @blocking 1154 * Yes when configured to operate in synchronous mode. 1155 * @reentrant 1156 * No 1157 * @threadSafe 1158 * Yes 1159 * 1160 * @param[in] instanceHandle Instance handle. 1161 * @param[in] pCb Callback function pointer. If this is set to 1162 * a NULL value the function will operate 1163 * synchronously. 1164 * @param[in] pCallbackTag User-supplied value to help identify request. 1165 * @param[in] pOpData Structure containing all the data needed to 1166 * perform the operation. The client code 1167 * allocates the memory for this structure. This 1168 * component takes ownership of the memory until 1169 * it is returned in the callback. 1170 * @param[out] pProtocolStatus The result passes/fails the DSA protocol 1171 * related checks. 1172 * @param[out] pR DSA message signature r. 1173 * @param[out] pS DSA message signature s. 1174 * 1175 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1176 * @retval CPA_STATUS_FAIL Function failed. 1177 * @retval CPA_STATUS_RETRY Resubmit the request. 1178 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1179 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1180 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1181 * the request. 1182 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1183 * 1184 * @pre 1185 * The component has been initialized via cpaCyStartInstance function. 1186 * @post 1187 * None 1188 * @note 1189 * When pCb is non-NULL an asynchronous callback of type 1190 * CpaCyDsaRSSignCbFunc is generated in response to this function 1191 * call. 1192 * For optimal performance, data pointers SHOULD be 8-byte aligned. 1193 * 1194 * @see 1195 * CpaCyDsaRSSignOpData, 1196 * CpaCyDsaRSSignCbFunc, 1197 * cpaCyDsaSignR(), 1198 * cpaCyDsaSignS() 1199 * 1200 *****************************************************************************/ 1201 CpaStatus 1202 cpaCyDsaSignRS(const CpaInstanceHandle instanceHandle, 1203 const CpaCyDsaRSSignCbFunc pCb, 1204 void *pCallbackTag, 1205 const CpaCyDsaRSSignOpData *pOpData, 1206 CpaBoolean *pProtocolStatus, 1207 CpaFlatBuffer *pR, 1208 CpaFlatBuffer *pS); 1209 1210 /** 1211 ***************************************************************************** 1212 * @ingroup cpaCyDsa 1213 * Verify DSA R and S signatures. 1214 * 1215 * @description 1216 * This function performs FIPS 186-3 Section 4.7: 1217 * w = (s')^-1 mod q 1218 * u1 = (zw) mod q 1219 * u2 = ((r')w) mod q 1220 * v = (((g)^u1 (y)^u2) mod p) mod q 1221 * 1222 * Here, z = the leftmost min(N, outlen) bits of Hash(M'). This function 1223 * does not perform the SHA digest; z is computed by the caller and 1224 * passed as a parameter in the pOpData field. 1225 * 1226 * A response status of ok (verifyStatus == CPA_TRUE) means v = r'. 1227 * A response status of not ok (verifyStatus == CPA_FALSE) means v != r'. 1228 * 1229 * @context 1230 * When called as an asynchronous function it cannot sleep. It can be 1231 * executed in a context that does not permit sleeping. 1232 * When called as a synchronous function it may sleep. It MUST NOT be 1233 * executed in a context that DOES NOT permit sleeping. 1234 * @assumptions 1235 * None 1236 * @sideEffects 1237 * None 1238 * @blocking 1239 * Yes when configured to operate in synchronous mode. 1240 * @reentrant 1241 * No 1242 * @threadSafe 1243 * Yes 1244 * 1245 * @param[in] instanceHandle Instance handle. 1246 * @param[in] pCb Callback function pointer. If this is set to 1247 * a NULL value the function will operate 1248 * synchronously. 1249 * @param[in] pCallbackTag User-supplied value to help identify request. 1250 * @param[in] pOpData Structure containing all the data needed to 1251 * perform the operation. The client code 1252 * allocates the memory for this structure. This 1253 * component takes ownership of the memory until 1254 * it is returned in the callback. 1255 * @param[out] pVerifyStatus The verification passed or failed. 1256 * 1257 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1258 * @retval CPA_STATUS_FAIL Function failed. 1259 * @retval CPA_STATUS_RETRY Resubmit the request. 1260 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1261 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1262 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1263 * the request. 1264 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1265 * 1266 * @pre 1267 * The component has been initialized via cpaCyStartInstance function. 1268 * @post 1269 * None 1270 * @note 1271 * When pCb is non-NULL an asynchronous callback of type 1272 * CpaCyDsaVerifyCbFunc is generated in response to this function 1273 * call. 1274 * For optimal performance, data pointers SHOULD be 8-byte aligned. 1275 * 1276 * @see 1277 * CpaCyDsaVerifyOpData, 1278 * CpaCyDsaVerifyCbFunc 1279 * 1280 *****************************************************************************/ 1281 CpaStatus 1282 cpaCyDsaVerify(const CpaInstanceHandle instanceHandle, 1283 const CpaCyDsaVerifyCbFunc pCb, 1284 void *pCallbackTag, 1285 const CpaCyDsaVerifyOpData *pOpData, 1286 CpaBoolean *pVerifyStatus); 1287 1288 /** 1289 ***************************************************************************** 1290 * @ingroup cpaCyDsa 1291 * Query statistics for a specific DSA instance. 1292 * 1293 * @deprecated 1294 * As of v1.3 of the Crypto API, this function has been deprecated, 1295 * replaced by @ref cpaCyDsaQueryStats64(). 1296 * 1297 * @description 1298 * This function will query a specific instance of the DSA implementation 1299 * for statistics. The user MUST allocate the CpaCyDsaStats structure 1300 * and pass the reference to that structure into this function call. This 1301 * function writes the statistic results into the passed in 1302 * CpaCyDsaStats structure. 1303 * 1304 * Note: statistics returned by this function do not interrupt current data 1305 * processing and as such can be slightly out of sync with operations that 1306 * are in progress during the statistics retrieval process. 1307 * 1308 * @context 1309 * This is a synchronous function and it can sleep. It MUST NOT be 1310 * executed in a context that DOES NOT permit sleeping. 1311 * @assumptions 1312 * None 1313 * @sideEffects 1314 * None 1315 * @blocking 1316 * This function is synchronous and blocking. 1317 * @reentrant 1318 * No 1319 * @threadSafe 1320 * Yes 1321 * 1322 * @param[in] instanceHandle Instance handle. 1323 * @param[out] pDsaStats Pointer to memory into which the statistics 1324 * will be written. 1325 * 1326 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1327 * @retval CPA_STATUS_FAIL Function failed. 1328 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1329 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1330 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1331 * the request. 1332 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1333 * 1334 * @pre 1335 * Component has been initialized. 1336 * @post 1337 * None 1338 * @note 1339 * This function operates in a synchronous manner and no asynchronous 1340 * callback will be generated. 1341 * @see 1342 * CpaCyDsaStats 1343 *****************************************************************************/ 1344 CpaStatus CPA_DEPRECATED 1345 cpaCyDsaQueryStats(const CpaInstanceHandle instanceHandle, 1346 struct _CpaCyDsaStats *pDsaStats); 1347 1348 /** 1349 ***************************************************************************** 1350 * @ingroup cpaCyDsa 1351 * Query 64-bit statistics for a specific DSA instance. 1352 * 1353 * @description 1354 * This function will query a specific instance of the DSA implementation 1355 * for 64-bit statistics. The user MUST allocate the CpaCyDsaStats64 1356 * structure and pass the reference to that structure into this function. 1357 * This function writes the statistic results into the passed in 1358 * CpaCyDsaStats64 structure. 1359 * 1360 * Note: statistics returned by this function do not interrupt current data 1361 * processing and as such can be slightly out of sync with operations that 1362 * are in progress during the statistics retrieval process. 1363 * 1364 * @context 1365 * This is a synchronous function and it can sleep. It MUST NOT be 1366 * executed in a context that DOES NOT permit sleeping. 1367 * @assumptions 1368 * None 1369 * @sideEffects 1370 * None 1371 * @blocking 1372 * This function is synchronous and blocking. 1373 * @reentrant 1374 * No 1375 * @threadSafe 1376 * Yes 1377 * 1378 * @param[in] instanceHandle Instance handle. 1379 * @param[out] pDsaStats Pointer to memory into which the statistics 1380 * will be written. 1381 * 1382 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1383 * @retval CPA_STATUS_FAIL Function failed. 1384 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1385 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1386 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1387 * the request. 1388 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1389 * 1390 * @pre 1391 * Component has been initialized. 1392 * @post 1393 * None 1394 * @note 1395 * This function operates in a synchronous manner and no asynchronous 1396 * callback will be generated. 1397 * @see 1398 * CpaCyDsaStats 1399 *****************************************************************************/ 1400 CpaStatus 1401 cpaCyDsaQueryStats64(const CpaInstanceHandle instanceHandle, 1402 CpaCyDsaStats64 *pDsaStats); 1403 1404 /*****************************************************************************/ 1405 1406 #ifdef __cplusplus 1407 } /* close the extern "C" { */ 1408 #endif 1409 1410 #endif /* CPA_CY_DSA_H */ 1411