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