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_ecdsa.h 12 * 13 * @defgroup cpaCyEcdsa Elliptic Curve Digital Signature Algorithm (ECDSA) API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for Public Key Encryption 19 * (Cryptography) Elliptic Curve Digital Signature Algorithm (ECDSA) 20 * operations. 21 * 22 * @note 23 * Large numbers are represented on the QuickAssist API as described 24 * in the Large Number API (@ref cpaCyLn). 25 * 26 * In addition, the bit length of large numbers passed to the API 27 * MUST NOT exceed 576 bits for Elliptic Curve operations. 28 *****************************************************************************/ 29 30 #ifndef CPA_CY_ECDSA_H_ 31 #define CPA_CY_ECDSA_H_ 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 #include "cpa_cy_common.h" 38 #include "cpa_cy_ec.h" 39 40 /** 41 ***************************************************************************** 42 * @ingroup cpaCyEcdsa 43 * ECDSA Sign R Operation Data. 44 * @description 45 * This structure contains the operation data for the cpaCyEcdsaSignR 46 * function. The client MUST allocate the memory for this structure and the 47 * items pointed to by this structure. When the structure is passed into 48 * the function, ownership of the memory passes to the function. Ownership 49 * of the memory returns to the client when this structure is returned in 50 * the callback function. 51 * 52 * For optimal performance all data buffers SHOULD be 8-byte aligned. 53 * 54 * All values in this structure are required to be in Most Significant Byte 55 * first order, e.g. a.pData[0] = MSB. 56 * 57 * @note 58 * If the client modifies or frees the memory referenced in this 59 * structure after it has been submitted to the cpaCyEcdsaSignR 60 * function, and before it has been returned in the callback, undefined 61 * behavior will result. 62 * 63 * @see 64 * cpaCyEcdsaSignR() 65 * 66 *****************************************************************************/ 67 typedef struct _CpaCyEcdsaSignROpData { 68 CpaFlatBuffer xg; 69 /**< x coordinate of base point G */ 70 CpaFlatBuffer yg; 71 /**< y coordinate of base point G */ 72 CpaFlatBuffer n; 73 /**< order of the base point G, which shall be prime */ 74 CpaFlatBuffer q; 75 /**< prime modulus or irreducible polynomial over GF(2^r) */ 76 CpaFlatBuffer a; 77 /**< a elliptic curve coefficient */ 78 CpaFlatBuffer b; 79 /**< b elliptic curve coefficient */ 80 CpaFlatBuffer k; 81 /**< random value (k > 0 and k < n) */ 82 83 CpaCyEcFieldType fieldType; 84 /**< field type for the operation */ 85 } CpaCyEcdsaSignROpData; 86 87 88 /** 89 ***************************************************************************** 90 * @ingroup cpaCyEcdsa 91 * ECDSA Sign S Operation Data. 92 * @description 93 * This structure contains the operation data for the cpaCyEcdsaSignS 94 * function. The client MUST allocate the memory for this structure and the 95 * items pointed to by this structure. When the structure is passed into 96 * the function, ownership of the memory passes to the function. Ownership 97 * of the memory returns to the client when this structure is returned in 98 * the callback function. 99 * 100 * For optimal performance all data buffers SHOULD be 8-byte aligned. 101 * 102 * All values in this structure are required to be in Most Significant Byte 103 * first order, e.g. a.pData[0] = MSB. 104 * 105 * @note 106 * If the client modifies or frees the memory referenced in this 107 * structure after it has been submitted to the cpaCyEcdsaSignS 108 * function, and before it has been returned in the callback, undefined 109 * behavior will result. 110 * 111 * @see 112 * cpaCyEcdsaSignS() 113 * 114 *****************************************************************************/ 115 typedef struct _CpaCyEcdsaSignSOpData { 116 CpaFlatBuffer m; 117 /**< digest of the message to be signed */ 118 CpaFlatBuffer d; 119 /**< private key */ 120 CpaFlatBuffer r; 121 /**< Ecdsa r signature value */ 122 CpaFlatBuffer k; 123 /**< random value (k > 0 and k < n) */ 124 CpaFlatBuffer n; 125 /**< order of the base point G, which shall be prime */ 126 CpaCyEcFieldType fieldType; 127 /**< field type for the operation */ 128 } CpaCyEcdsaSignSOpData; 129 130 131 /** 132 ***************************************************************************** 133 * @ingroup cpaCyEcdsa 134 * ECDSA Sign R & S Operation Data. 135 * @description 136 * This structure contains the operation data for the cpaCyEcdsaSignRS 137 * function. The client MUST allocate the memory for this structure and the 138 * items pointed to by this structure. When the structure is passed into 139 * the function, ownership of the memory passes to the function. Ownership 140 * of the memory returns to the client when this structure is returned in 141 * the callback function. 142 * 143 * For optimal performance all data buffers SHOULD be 8-byte aligned. 144 * 145 * All values in this structure are required to be in Most Significant Byte 146 * first order, e.g. a.pData[0] = MSB. 147 * 148 * @note 149 * If the client modifies or frees the memory referenced in this 150 * structure after it has been submitted to the cpaCyEcdsaSignRS 151 * function, and before it has been returned in the callback, undefined 152 * behavior will result. 153 * 154 * @see 155 * cpaCyEcdsaSignRS() 156 * 157 *****************************************************************************/ 158 typedef struct _CpaCyEcdsaSignRSOpData { 159 CpaFlatBuffer xg; 160 /**< x coordinate of base point G */ 161 CpaFlatBuffer yg; 162 /**< y coordinate of base point G */ 163 CpaFlatBuffer n; 164 /**< order of the base point G, which shall be prime */ 165 CpaFlatBuffer q; 166 /**< prime modulus or irreducible polynomial over GF(2^r) */ 167 CpaFlatBuffer a; 168 /**< a elliptic curve coefficient */ 169 CpaFlatBuffer b; 170 /**< b elliptic curve coefficient */ 171 CpaFlatBuffer k; 172 /**< random value (k > 0 and k < n) */ 173 CpaFlatBuffer m; 174 /**< digest of the message to be signed */ 175 CpaFlatBuffer d; 176 /**< private key */ 177 CpaCyEcFieldType fieldType; 178 /**< field type for the operation */ 179 } CpaCyEcdsaSignRSOpData; 180 181 182 /** 183 ***************************************************************************** 184 * @ingroup cpaCyEcdsa 185 * ECDSA Verify Operation Data, for Public Key. 186 187 * @description 188 * This structure contains the operation data for the CpaCyEcdsaVerify 189 * function. The client MUST allocate the memory for this structure and the 190 * items pointed to by this structure. When the structure is passed into 191 * the function, ownership of the memory passes to the function. Ownership 192 * of the memory returns to the client when this structure is returned in 193 * the callback function. 194 * 195 * For optimal performance all data buffers SHOULD be 8-byte aligned. 196 * 197 * All values in this structure are required to be in Most Significant Byte 198 * first order, e.g. a.pData[0] = MSB. 199 * 200 * @note 201 * If the client modifies or frees the memory referenced in this 202 * structure after it has been submitted to the cpaCyEcdsaVerify 203 * function, and before it has been returned in the callback, undefined 204 * behavior will result. 205 * 206 * @see 207 * CpaCyEcdsaVerify() 208 * 209 *****************************************************************************/ 210 typedef struct _CpaCyEcdsaVerifyOpData { 211 CpaFlatBuffer xg; 212 /**< x coordinate of base point G */ 213 CpaFlatBuffer yg; 214 /**< y coordinate of base point G */ 215 CpaFlatBuffer n; 216 /**< order of the base point G, which shall be prime */ 217 CpaFlatBuffer q; 218 /**< prime modulus or irreducible polynomial over GF(2^r) */ 219 CpaFlatBuffer a; 220 /**< a elliptic curve coefficient */ 221 CpaFlatBuffer b; 222 /**< b elliptic curve coefficient */ 223 CpaFlatBuffer m; 224 /**< digest of the message to be signed */ 225 CpaFlatBuffer r; 226 /**< ECDSA r signature value (r > 0 and r < n) */ 227 CpaFlatBuffer s; 228 /**< ECDSA s signature value (s > 0 and s < n) */ 229 CpaFlatBuffer xp; 230 /**< x coordinate of point P (public key) */ 231 CpaFlatBuffer yp; 232 /**< y coordinate of point P (public key) */ 233 CpaCyEcFieldType fieldType; 234 /**< field type for the operation */ 235 } CpaCyEcdsaVerifyOpData; 236 237 /** 238 ***************************************************************************** 239 * @ingroup cpaCyEcdsa 240 * Cryptographic ECDSA Statistics. 241 * @description 242 * This structure contains statistics on the Cryptographic ECDSA 243 * operations. Statistics are set to zero when the component is 244 * initialized, and are collected per instance. 245 * 246 ****************************************************************************/ 247 typedef struct _CpaCyEcdsaStats64 { 248 Cpa64U numEcdsaSignRRequests; 249 /**< Total number of ECDSA Sign R operation requests. */ 250 Cpa64U numEcdsaSignRRequestErrors; 251 /**< Total number of ECDSA Sign R operation requests that had an error and 252 * could not be processed. */ 253 Cpa64U numEcdsaSignRCompleted; 254 /**< Total number of ECDSA Sign R operation requests that completed 255 * successfully. */ 256 Cpa64U numEcdsaSignRCompletedErrors; 257 /**< Total number of ECDSA Sign R operation requests that could 258 * not be completed successfully due to errors. */ 259 Cpa64U numEcdsaSignRCompletedOutputInvalid; 260 /**< Total number of ECDSA Sign R operation requests could not be completed 261 * successfully due to an invalid output. 262 * Note that this does not indicate an error. */ 263 Cpa64U numEcdsaSignSRequests; 264 /**< Total number of ECDSA Sign S operation requests. */ 265 Cpa64U numEcdsaSignSRequestErrors; 266 /**< Total number of ECDSA Sign S operation requests that had an error and 267 * could not be processed. */ 268 Cpa64U numEcdsaSignSCompleted; 269 /**< Total number of ECDSA Sign S operation requests that completed 270 * successfully. */ 271 Cpa64U numEcdsaSignSCompletedErrors; 272 /**< Total number of ECDSA Sign S operation requests that could 273 * not be completed successfully due to errors. */ 274 Cpa64U numEcdsaSignSCompletedOutputInvalid; 275 /**< Total number of ECDSA Sign S operation requests could not be completed 276 * successfully due to an invalid output. 277 * Note that this does not indicate an error. */ 278 Cpa64U numEcdsaSignRSRequests; 279 /**< Total number of ECDSA Sign R & S operation requests. */ 280 Cpa64U numEcdsaSignRSRequestErrors; 281 /**< Total number of ECDSA Sign R & S operation requests that had an 282 * error and could not be processed. */ 283 Cpa64U numEcdsaSignRSCompleted; 284 /**< Total number of ECDSA Sign R & S operation requests that completed 285 * successfully. */ 286 Cpa64U numEcdsaSignRSCompletedErrors; 287 /**< Total number of ECDSA Sign R & S operation requests that could 288 * not be completed successfully due to errors. */ 289 Cpa64U numEcdsaSignRSCompletedOutputInvalid; 290 /**< Total number of ECDSA Sign R & S operation requests could not be 291 * completed successfully due to an invalid output. 292 * Note that this does not indicate an error. */ 293 Cpa64U numEcdsaVerifyRequests; 294 /**< Total number of ECDSA Verification operation requests. */ 295 Cpa64U numEcdsaVerifyRequestErrors; 296 /**< Total number of ECDSA Verification operation requests that had an 297 * error and could not be processed. */ 298 Cpa64U numEcdsaVerifyCompleted; 299 /**< Total number of ECDSA Verification operation requests that completed 300 * successfully. */ 301 Cpa64U numEcdsaVerifyCompletedErrors; 302 /**< Total number of ECDSA Verification operation requests that could 303 * not be completed successfully due to errors. */ 304 Cpa64U numEcdsaVerifyCompletedOutputInvalid; 305 /**< Total number of ECDSA Verification operation requests that resulted 306 * in an invalid output. 307 * Note that this does not indicate an error. */ 308 Cpa64U numKptEcdsaSignRSCompletedOutputInvalid; 309 /**< Total number of KPT ECDSA Sign R & S operation requests could not be 310 * completed successfully due to an invalid output. 311 * Note that this does not indicate an error. */ 312 Cpa64U numKptEcdsaSignRSCompleted; 313 /**< Total number of KPT ECDSA Sign R & S operation requests that completed 314 * successfully. */ 315 Cpa64U numKptEcdsaSignRSRequests; 316 /**< Total number of KPT ECDSA Sign R & S operation requests. */ 317 Cpa64U numKptEcdsaSignRSRequestErrors; 318 /**< Total number of KPT ECDSA Sign R & S operation requests that had an 319 * error and could not be processed. */ 320 Cpa64U numKptEcdsaSignRSCompletedErrors; 321 /**< Total number of KPT ECDSA Sign R & S operation requests that could 322 * not be completed successfully due to errors. */ 323 } CpaCyEcdsaStats64; 324 325 326 /** 327 ***************************************************************************** 328 * @ingroup cpaCyEcdsa 329 * Definition of a generic callback function invoked for a number of the 330 * ECDSA Sign API functions. 331 * 332 * @description 333 * This is the prototype for the CpaCyEcdsaGenSignCbFunc callback function. 334 * 335 * @context 336 * This callback function can be executed in a context that DOES NOT 337 * permit sleeping to occur. 338 * @assumptions 339 * None 340 * @sideEffects 341 * None 342 * @reentrant 343 * No 344 * @threadSafe 345 * Yes 346 * 347 * @param[in] pCallbackTag User-supplied value to help identify request. 348 * @param[in] status Status of the operation. Valid values are 349 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 350 * CPA_STATUS_UNSUPPORTED. 351 * @param[in] pOpData Opaque pointer to Operation data supplied in 352 * request. 353 * @param[in] multiplyStatus Status of the point multiplication. 354 * @param[in] pOut Output data from the request. 355 * 356 * @retval 357 * None 358 * @pre 359 * Component has been initialized. 360 * @post 361 * None 362 * @note 363 * None 364 * @see 365 * cpaCyEcdsaSignR() 366 * cpaCyEcdsaSignS() 367 * 368 *****************************************************************************/ 369 typedef void (*CpaCyEcdsaGenSignCbFunc)(void *pCallbackTag, 370 CpaStatus status, 371 void *pOpData, 372 CpaBoolean multiplyStatus, 373 CpaFlatBuffer *pOut); 374 375 376 /** 377 ***************************************************************************** 378 * @ingroup cpaCyEcdsa 379 * Definition of callback function invoked for cpaCyEcdsaSignRS 380 * requests. 381 * 382 * @description 383 * This is the prototype for the CpaCyEcdsaSignRSCbFunc callback function, 384 * which will provide the ECDSA message signature r and s parameters. 385 * 386 * @context 387 * This callback function can be executed in a context that DOES NOT 388 * permit sleeping to occur. 389 * @assumptions 390 * None 391 * @sideEffects 392 * None 393 * @reentrant 394 * No 395 * @threadSafe 396 * Yes 397 * 398 * @param[in] pCallbackTag User-supplied value to help identify request. 399 * @param[in] status Status of the operation. Valid values are 400 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 401 * CPA_STATUS_UNSUPPORTED. 402 * @param[in] pOpData Operation data pointer supplied in request. 403 * @param[in] multiplyStatus Status of the point multiplication. 404 * @param[in] pR Ecdsa message signature r. 405 * @param[in] pS Ecdsa message signature s. 406 * 407 * 408 * @retval 409 * None 410 * @pre 411 * Component has been initialized. 412 * @post 413 * None 414 * @note 415 * None 416 * @see 417 * cpaCyEcdsaSignRS() 418 * 419 *****************************************************************************/ 420 typedef void (*CpaCyEcdsaSignRSCbFunc)(void *pCallbackTag, 421 CpaStatus status, 422 void *pOpData, 423 CpaBoolean multiplyStatus, 424 CpaFlatBuffer *pR, 425 CpaFlatBuffer *pS); 426 427 428 /** 429 ***************************************************************************** 430 * @ingroup cpaCyEcdsa 431 * Definition of callback function invoked for cpaCyEcdsaVerify requests. 432 * 433 * @description 434 * This is the prototype for the CpaCyEcdsaVerifyCbFunc callback function. 435 * 436 * @context 437 * This callback function can be executed in a context that DOES NOT 438 * permit sleeping to occur. 439 * @assumptions 440 * None 441 * @sideEffects 442 * None 443 * @reentrant 444 * No 445 * @threadSafe 446 * Yes 447 * 448 * @param[in] pCallbackTag User-supplied value to help identify request. 449 * @param[in] status Status of the operation. Valid values are 450 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 451 * CPA_STATUS_UNSUPPORTED. 452 * @param[in] pOpData Operation data pointer supplied in request. 453 * @param[in] verifyStatus The verification status. 454 * 455 * @retval 456 * None 457 * @pre 458 * Component has been initialized. 459 * @post 460 * None 461 * @note 462 * None 463 * @see 464 * cpaCyEcdsaVerify() 465 * 466 *****************************************************************************/ 467 typedef void (*CpaCyEcdsaVerifyCbFunc)(void *pCallbackTag, 468 CpaStatus status, 469 void *pOpData, 470 CpaBoolean verifyStatus); 471 472 473 /** 474 ***************************************************************************** 475 * @ingroup cpaCyEcdsa 476 * Generate ECDSA Signature R. 477 * 478 * @description 479 * This function generates ECDSA Signature R as per ANSI X9.62 2005 480 * section 7.3. 481 * 482 * @context 483 * When called as an asynchronous function it cannot sleep. It can be 484 * executed in a context that does not permit sleeping. 485 * When called as a synchronous function it may sleep. It MUST NOT be 486 * executed in a context that DOES NOT permit sleeping. 487 * @assumptions 488 * None 489 * @sideEffects 490 * None 491 * @blocking 492 * Yes when configured to operate in synchronous mode. 493 * @reentrant 494 * No 495 * @threadSafe 496 * Yes 497 * 498 * @param[in] instanceHandle Instance handle. 499 * @param[in] pCb Callback function pointer. If this is set to a 500 * NULL value the function will operate 501 * synchronously. 502 * @param[in] pCallbackTag User-supplied value to help identify request. 503 * @param[in] pOpData Structure containing all the data needed to 504 * perform the operation. The client code 505 * allocates the memory for this structure. This 506 * component takes ownership of the memory until 507 * it is returned in the callback. 508 * @param[out] pSignStatus In synchronous mode, the multiply output is 509 * valid (CPA_TRUE) or the output is invalid 510 * (CPA_FALSE). 511 * @param[out] pR ECDSA message signature r. 512 * 513 * 514 * @retval CPA_STATUS_SUCCESS Function executed successfully. 515 * @retval CPA_STATUS_FAIL Function failed. 516 * @retval CPA_STATUS_RETRY Resubmit the request. 517 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 518 * @retval CPA_STATUS_RESOURCE Error related to system resources. 519 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 520 * the request. 521 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 522 * 523 * @pre 524 * The component has been initialized via cpaCyStartInstance function. 525 * @post 526 * None 527 * @note 528 * When pCb is non-NULL an asynchronous callback is generated in response 529 * to this function call. 530 * For optimal performance, data pointers SHOULD be 8-byte aligned. 531 * 532 * @see 533 * None 534 *****************************************************************************/ 535 CpaStatus 536 cpaCyEcdsaSignR(const CpaInstanceHandle instanceHandle, 537 const CpaCyEcdsaGenSignCbFunc pCb, 538 void *pCallbackTag, 539 const CpaCyEcdsaSignROpData *pOpData, 540 CpaBoolean *pSignStatus, 541 CpaFlatBuffer *pR); 542 543 544 /** 545 ***************************************************************************** 546 * @ingroup cpaCyEcdsa 547 * Generate ECDSA Signature S. 548 * 549 * @description 550 * This function generates ECDSA Signature S as per ANSI X9.62 2005 551 * section 7.3. 552 * 553 * @context 554 * When called as an asynchronous function it cannot sleep. It can be 555 * executed in a context that does not permit sleeping. 556 * When called as a synchronous function it may sleep. It MUST NOT be 557 * executed in a context that DOES NOT permit sleeping. 558 * @assumptions 559 * None 560 * @sideEffects 561 * None 562 * @blocking 563 * Yes when configured to operate in synchronous mode. 564 * @reentrant 565 * No 566 * @threadSafe 567 * Yes 568 * 569 * @param[in] instanceHandle Instance handle. 570 * @param[in] pCb Callback function pointer. If this is set to a 571 * NULL value the function will operate 572 * synchronously. 573 * @param[in] pCallbackTag User-supplied value to help identify request. 574 * @param[in] pOpData Structure containing all the data needed to 575 * perform the operation. The client code 576 * allocates the memory for this structure. This 577 * component takes ownership of the memory until 578 * it is returned in the callback. 579 * @param[out] pSignStatus In synchronous mode, the multiply output is 580 * valid (CPA_TRUE) or the output is invalid 581 * (CPA_FALSE). 582 * @param[out] pS ECDSA message signature s. 583 * 584 * 585 * @retval CPA_STATUS_SUCCESS Function executed successfully. 586 * @retval CPA_STATUS_FAIL Function failed. 587 * @retval CPA_STATUS_RETRY Resubmit the request. 588 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 589 * @retval CPA_STATUS_RESOURCE Error related to system resources. 590 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 591 * the request. 592 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 593 * 594 * @pre 595 * The component has been initialized via cpaCyStartInstance function. 596 * @post 597 * None 598 * @note 599 * When pCb is non-NULL an asynchronous callback is generated in response 600 * to this function call. 601 * For optimal performance, data pointers SHOULD be 8-byte aligned. 602 * 603 * @see 604 * None 605 *****************************************************************************/ 606 CpaStatus 607 cpaCyEcdsaSignS(const CpaInstanceHandle instanceHandle, 608 const CpaCyEcdsaGenSignCbFunc pCb, 609 void *pCallbackTag, 610 const CpaCyEcdsaSignSOpData *pOpData, 611 CpaBoolean *pSignStatus, 612 CpaFlatBuffer *pS); 613 614 615 /** 616 ***************************************************************************** 617 * @ingroup cpaCyEcdsa 618 * Generate ECDSA Signature R & S. 619 * 620 * @description 621 * This function generates ECDSA Signature R & S as per ANSI X9.62 2005 622 * section 7.3. 623 * 624 * @context 625 * When called as an asynchronous function it cannot sleep. It can be 626 * executed in a context that does not permit sleeping. 627 * When called as a synchronous function it may sleep. It MUST NOT be 628 * executed in a context that DOES NOT permit sleeping. 629 * @assumptions 630 * None 631 * @sideEffects 632 * None 633 * @blocking 634 * Yes when configured to operate in synchronous mode. 635 * @reentrant 636 * No 637 * @threadSafe 638 * Yes 639 * 640 * @param[in] instanceHandle Instance handle. 641 * @param[in] pCb Callback function pointer. If this is set to a 642 * NULL value the function will operate 643 * synchronously. 644 * @param[in] pCallbackTag User-supplied value to help identify request. 645 * @param[in] pOpData Structure containing all the data needed to 646 * perform the operation. The client code 647 * allocates the memory for this structure. This 648 * component takes ownership of the memory until 649 * it is returned in the callback. 650 * @param[out] pSignStatus In synchronous mode, the multiply output is 651 * valid (CPA_TRUE) or the output is invalid 652 * (CPA_FALSE). 653 * @param[out] pR ECDSA message signature r. 654 * @param[out] pS ECDSA message signature s. 655 * 656 * @retval CPA_STATUS_SUCCESS Function executed successfully. 657 * @retval CPA_STATUS_FAIL Function failed. 658 * @retval CPA_STATUS_RETRY Resubmit the request. 659 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 660 * @retval CPA_STATUS_RESOURCE Error related to system resources. 661 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 662 * the request. 663 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 664 * 665 * @pre 666 * The component has been initialized via cpaCyStartInstance function. 667 * @post 668 * None 669 * @note 670 * When pCb is non-NULL an asynchronous callback is generated in response 671 * to this function call. 672 * For optimal performance, data pointers SHOULD be 8-byte aligned. 673 * 674 * @see 675 * None 676 *****************************************************************************/ 677 CpaStatus 678 cpaCyEcdsaSignRS(const CpaInstanceHandle instanceHandle, 679 const CpaCyEcdsaSignRSCbFunc pCb, 680 void *pCallbackTag, 681 const CpaCyEcdsaSignRSOpData *pOpData, 682 CpaBoolean *pSignStatus, 683 CpaFlatBuffer *pR, 684 CpaFlatBuffer *pS); 685 686 687 /** 688 ***************************************************************************** 689 * @ingroup cpaCyEcdsa 690 * Verify ECDSA Public Key. 691 * 692 * @description 693 * This function performs ECDSA Verify as per ANSI X9.62 2005 section 7.4. 694 * 695 * A response status of ok (verifyStatus == CPA_TRUE) means that the 696 * signature was verified 697 * 698 * @context 699 * When called as an asynchronous function it cannot sleep. It can be 700 * executed in a context that does not permit sleeping. 701 * When called as a synchronous function it may sleep. It MUST NOT be 702 * executed in a context that DOES NOT permit sleeping. 703 * @assumptions 704 * None 705 * @sideEffects 706 * None 707 * @blocking 708 * Yes when configured to operate in synchronous mode. 709 * @reentrant 710 * No 711 * @threadSafe 712 * Yes 713 * 714 * @param[in] instanceHandle Instance handle. 715 * @param[in] pCb Callback function pointer. If this is set to 716 * a NULL value the function will operate 717 * synchronously. 718 * @param[in] pCallbackTag User-supplied value to help identify request. 719 * @param[in] pOpData Structure containing all the data needed to 720 * perform the operation. The client code 721 * allocates the memory for this structure. This 722 * component takes ownership of the memory until 723 * it is returned in the callback. 724 * @param[out] pVerifyStatus In synchronous mode, set to CPA_FALSE if the 725 * point is NOT on the curve or at infinity. Set 726 * to CPA_TRUE if the point is on the curve. 727 * 728 * @retval CPA_STATUS_SUCCESS Function executed successfully. 729 * @retval CPA_STATUS_FAIL Function failed. 730 * @retval CPA_STATUS_RETRY Resubmit the request. 731 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 732 * @retval CPA_STATUS_RESOURCE Error related to system resources. 733 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 734 * the request. 735 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 736 * 737 * @pre 738 * The component has been initialized via cpaCyStartInstance function. 739 * @post 740 * None 741 * @note 742 * When pCb is non-NULL an asynchronous callback of type 743 * CpaCyEcdsaVerifyCbFunc is generated in response to this function 744 * call. 745 * For optimal performance, data pointers SHOULD be 8-byte aligned. 746 * 747 * @see 748 * CpaCyEcdsaVerifyOpData, 749 * CpaCyEcdsaVerifyCbFunc 750 * 751 *****************************************************************************/ 752 CpaStatus 753 cpaCyEcdsaVerify(const CpaInstanceHandle instanceHandle, 754 const CpaCyEcdsaVerifyCbFunc pCb, 755 void *pCallbackTag, 756 const CpaCyEcdsaVerifyOpData *pOpData, 757 CpaBoolean *pVerifyStatus); 758 759 /** 760 ***************************************************************************** 761 * @ingroup cpaCyEcdsa 762 * Query statistics for a specific ECDSA instance. 763 * 764 * @description 765 * This function will query a specific instance of the ECDSA implementation 766 * for statistics. The user MUST allocate the CpaCyEcdsaStats64 structure 767 * and pass the reference to that structure into this function call. This 768 * function writes the statistic results into the passed in 769 * CpaCyEcdsaStats64 structure. 770 * 771 * Note: statistics returned by this function do not interrupt current data 772 * processing and as such can be slightly out of sync with operations that 773 * are in progress during the statistics retrieval process. 774 * 775 * @context 776 * This is a synchronous function and it can sleep. It MUST NOT be 777 * executed in a context that DOES NOT permit sleeping. 778 * @assumptions 779 * None 780 * @sideEffects 781 * None 782 * @blocking 783 * This function is synchronous and blocking. 784 * @reentrant 785 * No 786 * @threadSafe 787 * Yes 788 * 789 * @param[in] instanceHandle Instance handle. 790 * @param[out] pEcdsaStats Pointer to memory into which the statistics 791 * will be written. 792 * 793 * @retval CPA_STATUS_SUCCESS Function executed successfully. 794 * @retval CPA_STATUS_FAIL Function failed. 795 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 796 * @retval CPA_STATUS_RESOURCE Error related to system resources. 797 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 798 * the request. 799 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 800 * 801 * @pre 802 * Component has been initialized. 803 * @post 804 * None 805 * @note 806 * This function operates in a synchronous manner and no asynchronous 807 * callback will be generated. 808 * @see 809 * CpaCyEcdsaStats64 810 *****************************************************************************/ 811 CpaStatus 812 cpaCyEcdsaQueryStats64(const CpaInstanceHandle instanceHandle, 813 CpaCyEcdsaStats64 *pEcdsaStats); 814 815 #ifdef __cplusplus 816 } /* close the extern "C" { */ 817 #endif 818 819 #endif /*CPA_CY_ECDSA_H_*/ 820