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_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 * @ingroup cpaCyEcdsa 273 * Cryptographic ECDSA Statistics. 274 * @description 275 * This structure contains statistics on the Cryptographic ECDSA 276 * operations. Statistics are set to zero when the component is 277 * initialized, and are collected per instance. 278 * 279 ****************************************************************************/ 280 typedef struct _CpaCyEcdsaStats64 { 281 Cpa64U numEcdsaSignRRequests; 282 /**< Total number of ECDSA Sign R operation requests. */ 283 Cpa64U numEcdsaSignRRequestErrors; 284 /**< Total number of ECDSA Sign R operation requests that had an error and 285 * could not be processed. */ 286 Cpa64U numEcdsaSignRCompleted; 287 /**< Total number of ECDSA Sign R operation requests that completed 288 * successfully. */ 289 Cpa64U numEcdsaSignRCompletedErrors; 290 /**< Total number of ECDSA Sign R operation requests that could 291 * not be completed successfully due to errors. */ 292 Cpa64U numEcdsaSignRCompletedOutputInvalid; 293 /**< Total number of ECDSA Sign R operation requests could not be completed 294 * successfully due to an invalid output. 295 * Note that this does not indicate an error. */ 296 Cpa64U numEcdsaSignSRequests; 297 /**< Total number of ECDSA Sign S operation requests. */ 298 Cpa64U numEcdsaSignSRequestErrors; 299 /**< Total number of ECDSA Sign S operation requests that had an error and 300 * could not be processed. */ 301 Cpa64U numEcdsaSignSCompleted; 302 /**< Total number of ECDSA Sign S operation requests that completed 303 * successfully. */ 304 Cpa64U numEcdsaSignSCompletedErrors; 305 /**< Total number of ECDSA Sign S operation requests that could 306 * not be completed successfully due to errors. */ 307 Cpa64U numEcdsaSignSCompletedOutputInvalid; 308 /**< Total number of ECDSA Sign S operation requests could not be completed 309 * successfully due to an invalid output. 310 * Note that this does not indicate an error. */ 311 Cpa64U numEcdsaSignRSRequests; 312 /**< Total number of ECDSA Sign R & S operation requests. */ 313 Cpa64U numEcdsaSignRSRequestErrors; 314 /**< Total number of ECDSA Sign R & S operation requests that had an 315 * error and could not be processed. */ 316 Cpa64U numEcdsaSignRSCompleted; 317 /**< Total number of ECDSA Sign R & S operation requests that completed 318 * successfully. */ 319 Cpa64U numEcdsaSignRSCompletedErrors; 320 /**< Total number of ECDSA Sign R & S operation requests that could 321 * not be completed successfully due to errors. */ 322 Cpa64U numEcdsaSignRSCompletedOutputInvalid; 323 /**< Total number of ECDSA Sign R & S operation requests could not be 324 * completed successfully due to an invalid output. 325 * Note that this does not indicate an error. */ 326 Cpa64U numEcdsaVerifyRequests; 327 /**< Total number of ECDSA Verification operation requests. */ 328 Cpa64U numEcdsaVerifyRequestErrors; 329 /**< Total number of ECDSA Verification operation requests that had an 330 * error and could not be processed. */ 331 Cpa64U numEcdsaVerifyCompleted; 332 /**< Total number of ECDSA Verification operation requests that completed 333 * successfully. */ 334 Cpa64U numEcdsaVerifyCompletedErrors; 335 /**< Total number of ECDSA Verification operation requests that could 336 * not be completed successfully due to errors. */ 337 Cpa64U numEcdsaVerifyCompletedOutputInvalid; 338 /**< Total number of ECDSA Verification operation requests that resulted 339 * in an invalid output. 340 * Note that this does not indicate an error. */ 341 Cpa64U numKptEcdsaSignRSCompletedOutputInvalid; 342 /**< Total number of KPT ECDSA Sign R & S operation requests could not be 343 * completed successfully due to an invalid output. 344 * Note that this does not indicate an error. */ 345 Cpa64U numKptEcdsaSignRSCompleted; 346 /**< Total number of KPT ECDSA Sign R & S operation requests that completed 347 * successfully. */ 348 Cpa64U numKptEcdsaSignRSRequests; 349 /**< Total number of KPT ECDSA Sign R & S operation requests. */ 350 Cpa64U numKptEcdsaSignRSRequestErrors; 351 /**< Total number of KPT ECDSA Sign R & S operation requests that had an 352 * error and could not be processed. */ 353 Cpa64U numKptEcdsaSignRSCompletedErrors; 354 /**< Total number of KPT ECDSA Sign R & S operation requests that could 355 * not be completed successfully due to errors. */ 356 } CpaCyEcdsaStats64; 357 358 359 /** 360 ***************************************************************************** 361 * @ingroup cpaCyEcdsa 362 * Definition of a generic callback function invoked for a number of the 363 * ECDSA Sign API functions. 364 * 365 * @description 366 * This is the prototype for the CpaCyEcdsaGenSignCbFunc callback function. 367 * 368 * @context 369 * This callback function can be executed in a context that DOES NOT 370 * permit sleeping to occur. 371 * @assumptions 372 * None 373 * @sideEffects 374 * None 375 * @reentrant 376 * No 377 * @threadSafe 378 * Yes 379 * 380 * @param[in] pCallbackTag User-supplied value to help identify request. 381 * @param[in] status Status of the operation. Valid values are 382 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 383 * CPA_STATUS_UNSUPPORTED. 384 * @param[in] pOpData Opaque pointer to Operation data supplied in 385 * request. 386 * @param[in] multiplyStatus Status of the point multiplication. 387 * @param[in] pOut Output data from the request. 388 * 389 * @retval 390 * None 391 * @pre 392 * Component has been initialized. 393 * @post 394 * None 395 * @note 396 * None 397 * @see 398 * cpaCyEcdsaSignR() 399 * cpaCyEcdsaSignS() 400 * 401 *****************************************************************************/ 402 typedef void (*CpaCyEcdsaGenSignCbFunc)(void *pCallbackTag, 403 CpaStatus status, 404 void *pOpData, 405 CpaBoolean multiplyStatus, 406 CpaFlatBuffer *pOut); 407 408 409 /** 410 ***************************************************************************** 411 * @ingroup cpaCyEcdsa 412 * Definition of callback function invoked for cpaCyEcdsaSignRS 413 * requests. 414 * 415 * @description 416 * This is the prototype for the CpaCyEcdsaSignRSCbFunc callback function, 417 * which will provide the ECDSA message signature r and s parameters. 418 * 419 * @context 420 * This callback function can be executed in a context that DOES NOT 421 * permit sleeping to occur. 422 * @assumptions 423 * None 424 * @sideEffects 425 * None 426 * @reentrant 427 * No 428 * @threadSafe 429 * Yes 430 * 431 * @param[in] pCallbackTag User-supplied value to help identify request. 432 * @param[in] status Status of the operation. Valid values are 433 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 434 * CPA_STATUS_UNSUPPORTED. 435 * @param[in] pOpData Operation data pointer supplied in request. 436 * @param[in] multiplyStatus Status of the point multiplication. 437 * @param[in] pR Ecdsa message signature r. 438 * @param[in] pS Ecdsa message signature s. 439 * 440 * 441 * @retval 442 * None 443 * @pre 444 * Component has been initialized. 445 * @post 446 * None 447 * @note 448 * None 449 * @see 450 * cpaCyEcdsaSignRS() 451 * 452 *****************************************************************************/ 453 typedef void (*CpaCyEcdsaSignRSCbFunc)(void *pCallbackTag, 454 CpaStatus status, 455 void *pOpData, 456 CpaBoolean multiplyStatus, 457 CpaFlatBuffer *pR, 458 CpaFlatBuffer *pS); 459 460 461 /** 462 ***************************************************************************** 463 * @ingroup cpaCyEcdsa 464 * Definition of callback function invoked for cpaCyEcdsaVerify requests. 465 * 466 * @description 467 * This is the prototype for the CpaCyEcdsaVerifyCbFunc callback function. 468 * 469 * @context 470 * This callback function can be executed in a context that DOES NOT 471 * permit sleeping to occur. 472 * @assumptions 473 * None 474 * @sideEffects 475 * None 476 * @reentrant 477 * No 478 * @threadSafe 479 * Yes 480 * 481 * @param[in] pCallbackTag User-supplied value to help identify request. 482 * @param[in] status Status of the operation. Valid values are 483 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 484 * CPA_STATUS_UNSUPPORTED. 485 * @param[in] pOpData Operation data pointer supplied in request. 486 * @param[in] verifyStatus The verification status. 487 * 488 * @retval 489 * None 490 * @pre 491 * Component has been initialized. 492 * @post 493 * None 494 * @note 495 * None 496 * @see 497 * cpaCyEcdsaVerify() 498 * 499 *****************************************************************************/ 500 typedef void (*CpaCyEcdsaVerifyCbFunc)(void *pCallbackTag, 501 CpaStatus status, 502 void *pOpData, 503 CpaBoolean verifyStatus); 504 505 506 /** 507 ***************************************************************************** 508 * @ingroup cpaCyEcdsa 509 * Generate ECDSA Signature R. 510 * 511 * @description 512 * This function generates ECDSA Signature R as per ANSI X9.62 2005 513 * section 7.3. 514 * 515 * @context 516 * When called as an asynchronous function it cannot sleep. It can be 517 * executed in a context that does not permit sleeping. 518 * When called as a synchronous function it may sleep. It MUST NOT be 519 * executed in a context that DOES NOT permit sleeping. 520 * @assumptions 521 * None 522 * @sideEffects 523 * None 524 * @blocking 525 * Yes when configured to operate in synchronous mode. 526 * @reentrant 527 * No 528 * @threadSafe 529 * Yes 530 * 531 * @param[in] instanceHandle Instance handle. 532 * @param[in] pCb Callback function pointer. If this is set to a 533 * NULL value the function will operate 534 * synchronously. 535 * @param[in] pCallbackTag User-supplied value to help identify request. 536 * @param[in] pOpData Structure containing all the data needed to 537 * perform the operation. The client code 538 * allocates the memory for this structure. This 539 * component takes ownership of the memory until 540 * it is returned in the callback. 541 * @param[out] pSignStatus In synchronous mode, the multiply output is 542 * valid (CPA_TRUE) or the output is invalid 543 * (CPA_FALSE). 544 * @param[out] pR ECDSA message signature r. 545 * 546 * 547 * @retval CPA_STATUS_SUCCESS Function executed successfully. 548 * @retval CPA_STATUS_FAIL Function failed. 549 * @retval CPA_STATUS_RETRY Resubmit the request. 550 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 551 * @retval CPA_STATUS_RESOURCE Error related to system resources. 552 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 553 * the request. 554 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 555 * 556 * @pre 557 * The component has been initialized via cpaCyStartInstance function. 558 * @post 559 * None 560 * @note 561 * When pCb is non-NULL an asynchronous callback is generated in response 562 * to this function call. 563 * For optimal performance, data pointers SHOULD be 8-byte aligned. 564 * 565 * @see 566 * None 567 *****************************************************************************/ 568 CpaStatus 569 cpaCyEcdsaSignR(const CpaInstanceHandle instanceHandle, 570 const CpaCyEcdsaGenSignCbFunc pCb, 571 void *pCallbackTag, 572 const CpaCyEcdsaSignROpData *pOpData, 573 CpaBoolean *pSignStatus, 574 CpaFlatBuffer *pR); 575 576 577 /** 578 ***************************************************************************** 579 * @ingroup cpaCyEcdsa 580 * Generate ECDSA Signature S. 581 * 582 * @description 583 * This function generates ECDSA Signature S as per ANSI X9.62 2005 584 * section 7.3. 585 * 586 * @context 587 * When called as an asynchronous function it cannot sleep. It can be 588 * executed in a context that does not permit sleeping. 589 * When called as a synchronous function it may sleep. It MUST NOT be 590 * executed in a context that DOES NOT permit sleeping. 591 * @assumptions 592 * None 593 * @sideEffects 594 * None 595 * @blocking 596 * Yes when configured to operate in synchronous mode. 597 * @reentrant 598 * No 599 * @threadSafe 600 * Yes 601 * 602 * @param[in] instanceHandle Instance handle. 603 * @param[in] pCb Callback function pointer. If this is set to a 604 * NULL value the function will operate 605 * synchronously. 606 * @param[in] pCallbackTag User-supplied value to help identify request. 607 * @param[in] pOpData Structure containing all the data needed to 608 * perform the operation. The client code 609 * allocates the memory for this structure. This 610 * component takes ownership of the memory until 611 * it is returned in the callback. 612 * @param[out] pSignStatus In synchronous mode, the multiply output is 613 * valid (CPA_TRUE) or the output is invalid 614 * (CPA_FALSE). 615 * @param[out] pS ECDSA message signature s. 616 * 617 * 618 * @retval CPA_STATUS_SUCCESS Function executed successfully. 619 * @retval CPA_STATUS_FAIL Function failed. 620 * @retval CPA_STATUS_RETRY Resubmit the request. 621 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 622 * @retval CPA_STATUS_RESOURCE Error related to system resources. 623 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 624 * the request. 625 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 626 * 627 * @pre 628 * The component has been initialized via cpaCyStartInstance function. 629 * @post 630 * None 631 * @note 632 * When pCb is non-NULL an asynchronous callback is generated in response 633 * to this function call. 634 * For optimal performance, data pointers SHOULD be 8-byte aligned. 635 * 636 * @see 637 * None 638 *****************************************************************************/ 639 CpaStatus 640 cpaCyEcdsaSignS(const CpaInstanceHandle instanceHandle, 641 const CpaCyEcdsaGenSignCbFunc pCb, 642 void *pCallbackTag, 643 const CpaCyEcdsaSignSOpData *pOpData, 644 CpaBoolean *pSignStatus, 645 CpaFlatBuffer *pS); 646 647 648 /** 649 ***************************************************************************** 650 * @ingroup cpaCyEcdsa 651 * Generate ECDSA Signature R & S. 652 * 653 * @description 654 * This function generates ECDSA Signature R & S as per ANSI X9.62 2005 655 * section 7.3. 656 * 657 * @context 658 * When called as an asynchronous function it cannot sleep. It can be 659 * executed in a context that does not permit sleeping. 660 * When called as a synchronous function it may sleep. It MUST NOT be 661 * executed in a context that DOES NOT permit sleeping. 662 * @assumptions 663 * None 664 * @sideEffects 665 * None 666 * @blocking 667 * Yes when configured to operate in synchronous mode. 668 * @reentrant 669 * No 670 * @threadSafe 671 * Yes 672 * 673 * @param[in] instanceHandle Instance handle. 674 * @param[in] pCb Callback function pointer. If this is set to a 675 * NULL value the function will operate 676 * synchronously. 677 * @param[in] pCallbackTag User-supplied value to help identify request. 678 * @param[in] pOpData Structure containing all the data needed to 679 * perform the operation. The client code 680 * allocates the memory for this structure. This 681 * component takes ownership of the memory until 682 * it is returned in the callback. 683 * @param[out] pSignStatus In synchronous mode, the multiply output is 684 * valid (CPA_TRUE) or the output is invalid 685 * (CPA_FALSE). 686 * @param[out] pR ECDSA message signature r. 687 * @param[out] pS ECDSA message signature s. 688 * 689 * @retval CPA_STATUS_SUCCESS Function executed successfully. 690 * @retval CPA_STATUS_FAIL Function failed. 691 * @retval CPA_STATUS_RETRY Resubmit the request. 692 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 693 * @retval CPA_STATUS_RESOURCE Error related to system resources. 694 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 695 * the request. 696 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 697 * 698 * @pre 699 * The component has been initialized via cpaCyStartInstance function. 700 * @post 701 * None 702 * @note 703 * When pCb is non-NULL an asynchronous callback is generated in response 704 * to this function call. 705 * For optimal performance, data pointers SHOULD be 8-byte aligned. 706 * 707 * @see 708 * None 709 *****************************************************************************/ 710 CpaStatus 711 cpaCyEcdsaSignRS(const CpaInstanceHandle instanceHandle, 712 const CpaCyEcdsaSignRSCbFunc pCb, 713 void *pCallbackTag, 714 const CpaCyEcdsaSignRSOpData *pOpData, 715 CpaBoolean *pSignStatus, 716 CpaFlatBuffer *pR, 717 CpaFlatBuffer *pS); 718 719 720 /** 721 ***************************************************************************** 722 * @ingroup cpaCyEcdsa 723 * Verify ECDSA Public Key. 724 * 725 * @description 726 * This function performs ECDSA Verify as per ANSI X9.62 2005 section 7.4. 727 * 728 * A response status of ok (verifyStatus == CPA_TRUE) means that the 729 * signature was verified 730 * 731 * @context 732 * When called as an asynchronous function it cannot sleep. It can be 733 * executed in a context that does not permit sleeping. 734 * When called as a synchronous function it may sleep. It MUST NOT be 735 * executed in a context that DOES NOT permit sleeping. 736 * @assumptions 737 * None 738 * @sideEffects 739 * None 740 * @blocking 741 * Yes when configured to operate in synchronous mode. 742 * @reentrant 743 * No 744 * @threadSafe 745 * Yes 746 * 747 * @param[in] instanceHandle Instance handle. 748 * @param[in] pCb Callback function pointer. If this is set to 749 * a NULL value the function will operate 750 * synchronously. 751 * @param[in] pCallbackTag User-supplied value to help identify request. 752 * @param[in] pOpData Structure containing all the data needed to 753 * perform the operation. The client code 754 * allocates the memory for this structure. This 755 * component takes ownership of the memory until 756 * it is returned in the callback. 757 * @param[out] pVerifyStatus In synchronous mode, set to CPA_FALSE if the 758 * point is NOT on the curve or at infinity. Set 759 * to CPA_TRUE if the point is on the curve. 760 * 761 * @retval CPA_STATUS_SUCCESS Function executed successfully. 762 * @retval CPA_STATUS_FAIL Function failed. 763 * @retval CPA_STATUS_RETRY Resubmit the request. 764 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 765 * @retval CPA_STATUS_RESOURCE Error related to system resources. 766 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 767 * the request. 768 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 769 * 770 * @pre 771 * The component has been initialized via cpaCyStartInstance function. 772 * @post 773 * None 774 * @note 775 * When pCb is non-NULL an asynchronous callback of type 776 * CpaCyEcdsaVerifyCbFunc is generated in response to this function 777 * call. 778 * For optimal performance, data pointers SHOULD be 8-byte aligned. 779 * 780 * @see 781 * CpaCyEcdsaVerifyOpData, 782 * CpaCyEcdsaVerifyCbFunc 783 * 784 *****************************************************************************/ 785 CpaStatus 786 cpaCyEcdsaVerify(const CpaInstanceHandle instanceHandle, 787 const CpaCyEcdsaVerifyCbFunc pCb, 788 void *pCallbackTag, 789 const CpaCyEcdsaVerifyOpData *pOpData, 790 CpaBoolean *pVerifyStatus); 791 792 /** 793 ***************************************************************************** 794 * @ingroup cpaCyEcdsa 795 * Query statistics for a specific ECDSA instance. 796 * 797 * @description 798 * This function will query a specific instance of the ECDSA implementation 799 * for statistics. The user MUST allocate the CpaCyEcdsaStats64 structure 800 * and pass the reference to that structure into this function call. This 801 * function writes the statistic results into the passed in 802 * CpaCyEcdsaStats64 structure. 803 * 804 * Note: statistics returned by this function do not interrupt current data 805 * processing and as such can be slightly out of sync with operations that 806 * are in progress during the statistics retrieval process. 807 * 808 * @context 809 * This is a synchronous function and it can sleep. It MUST NOT be 810 * executed in a context that DOES NOT permit sleeping. 811 * @assumptions 812 * None 813 * @sideEffects 814 * None 815 * @blocking 816 * This function is synchronous and blocking. 817 * @reentrant 818 * No 819 * @threadSafe 820 * Yes 821 * 822 * @param[in] instanceHandle Instance handle. 823 * @param[out] pEcdsaStats Pointer to memory into which the statistics 824 * will be written. 825 * 826 * @retval CPA_STATUS_SUCCESS Function executed successfully. 827 * @retval CPA_STATUS_FAIL Function failed. 828 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 829 * @retval CPA_STATUS_RESOURCE Error related to system resources. 830 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 831 * the request. 832 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 833 * 834 * @pre 835 * Component has been initialized. 836 * @post 837 * None 838 * @note 839 * This function operates in a synchronous manner and no asynchronous 840 * callback will be generated. 841 * @see 842 * CpaCyEcdsaStats64 843 *****************************************************************************/ 844 CpaStatus 845 cpaCyEcdsaQueryStats64(const CpaInstanceHandle instanceHandle, 846 CpaCyEcdsaStats64 *pEcdsaStats); 847 848 #ifdef __cplusplus 849 } /* close the extern "C" { */ 850 #endif 851 852 #endif /*CPA_CY_ECDSA_H_*/ 853