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