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_ec.h 45 * 46 * @defgroup cpaCyEc Elliptic Curve (EC) API 47 * 48 * @ingroup cpaCy 49 * 50 * @description 51 * These functions specify the API for Public Key Encryption 52 * (Cryptography) Elliptic Curve (EC) operations. 53 * 54 * All implementations will support at least the following: 55 * 56 * - "NIST RECOMMENDED ELLIPTIC CURVES FOR FEDERAL GOVERNMENT USE" 57 * as defined by 58 * http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf 59 * 60 * - Random curves where the max(log2(q), log2(n) + log2(h)) <= 512 61 * where q is the modulus, n is the order of the curve and h is the 62 * cofactor 63 * 64 * For Montgomery and Edwards 25519 and 448 elliptic curves, 65 * the following operations are supported: 66 * 1. Montgomery 25519 Curve | scalar point Multiplication 67 * Input: Montgomery affine coordinate X of point P 68 * Scalar k 69 * Output: Montgomery affine coordinate X of point [k/P 70 * Decode: Scalar k always decoded by implementation 71 * 72 * 2. Montgomery 25519 Curve | generator point Multiplication 73 * Input: Scalar k 74 * Output: Montgomery affine coordinate X of point [k]G 75 * Decode: Scalar k always decoded by implementation 76 * 77 * 3. Twisted Edwards 25519 Curve | scalar point Multiplication 78 * Input: Twisted Edwards affine coordinate X of point P 79 * Twisted Edwards affine coordinate Y of point P 80 * Scalar k 81 * Output: Twisted Edwards affine coordinate X of point [k]P 82 * Twisted Edwards affine coordinate Y of point [k]P 83 * Decode: Caller must specify if decoding is required 84 * 85 * 4. Twisted Edwards 25519 Curve | generator point Multiplication 86 * Input: Scalar k 87 * Output: Twisted Edwards affine coordinate X of point [k]G 88 * Twisted Edwards affine coordinate Y of point [k]G 89 * Decode: Caller must specify if decoding is required 90 * 91 * 5. Montgomery 448 Curve | scalar point Multiplication 92 * Input: Montgomery affine coordinate X of point P 93 * Scalar k 94 * Output: Montgomery affine coordinate X of point [k]P 95 * Decode: Scalar k always decoded by implementation 96 * 97 * 6. Montgomery 448 Curve | generator point Multiplication 98 * Input: Scalar k 99 * Output: Montgomery affine coordinate X of point [k]G 100 * Decode: Scalar k always decoded by implementation 101 * 102 * 7. Edwards 448 Curve | scalar point Multiplication 103 * Input: Edwards affine coordinate X of point P 104 * Edwards affine coordinate Y of point P 105 * Scalar k 106 * Output: Edwards affine coordinate X of point [k]P 107 * Edwards affine coordinate Y of point [k]P 108 * Decode: Caller must specify if decoding is required 109 * 110 * 8. Edwards 448 Curve | generator point Multiplication 111 * Input: Scalar k 112 * Output: Edwards affine coordinate X of point [k]G 113 * Edwards affine coordinate Y of point [k]G 114 * Decode: Caller must specify if decoding is required 115 * 116 * @note 117 * Large numbers are represented on the QuickAssist API as described 118 * in the Large Number API (@ref cpaCyLn). 119 * 120 * In addition, the bit length of large numbers passed to the API 121 * MUST NOT exceed 576 bits for Elliptic Curve operations. 122 *****************************************************************************/ 123 124 #ifndef CPA_CY_EC_H_ 125 #define CPA_CY_EC_H_ 126 127 #ifdef __cplusplus 128 extern "C" { 129 #endif 130 131 #include "cpa_cy_common.h" 132 133 /** 134 ***************************************************************************** 135 * @ingroup cpaCyEc 136 * Field types for Elliptic Curve 137 138 * @description 139 * As defined by FIPS-186-3, for each cryptovariable length, there are 140 * two kinds of fields. 141 * <ul> 142 * <li> A prime field is the field GF(p) which contains a prime number 143 * p of elements. The elements of this field are the integers modulo 144 * p, and the field arithmetic is implemented in terms of the 145 * arithmetic of integers modulo p.</li> 146 * 147 * <li> A binary field is the field GF(2^m) which contains 2^m elements 148 * for some m (called the degree of the field). The elements of 149 * this field are the bit strings of length m, and the field 150 * arithmetic is implemented in terms of operations on the bits.</li> 151 * </ul> 152 *****************************************************************************/ 153 typedef enum _CpaCyEcFieldType 154 { 155 CPA_CY_EC_FIELD_TYPE_PRIME = 1, 156 /**< A prime field, GF(p) */ 157 CPA_CY_EC_FIELD_TYPE_BINARY, 158 /**< A binary field, GF(2^m) */ 159 } CpaCyEcFieldType; 160 161 /** 162 ***************************************************************************** 163 * @ingroup cpaCyEc 164 * Curve types for Elliptic Curves defined in RFC#7748 165 166 * @description 167 * As defined by RFC 7748, there are four elliptic curves in this 168 * group. The Montgomery curves are denoted curve25519 and curve448, 169 * and the birationally equivalent Twisted Edwards curves are denoted 170 * edwards25519 and edwards448 171 * 172 *****************************************************************************/ 173 typedef enum _CpaCyEcMontEdwdsCurveType 174 { 175 CPA_CY_EC_MONTEDWDS_CURVE25519_TYPE = 1, 176 /**< Montgomery 25519 curve */ 177 CPA_CY_EC_MONTEDWDS_ED25519_TYPE, 178 /**< Twisted Edwards 25519 curve */ 179 CPA_CY_EC_MONTEDWDS_CURVE448_TYPE, 180 /**< Montgomery 448 curve */ 181 CPA_CY_EC_MONTEDWDS_ED448_TYPE, 182 /**< Twisted Edwards 448 curve */ 183 } CpaCyEcMontEdwdsCurveType; 184 185 /** 186 ***************************************************************************** 187 * @file cpa_cy_ec.h 188 * @ingroup cpaCyEc 189 * EC Point Multiplication Operation Data. 190 * 191 * @description 192 * This structure contains the operation data for the cpaCyEcPointMultiply 193 * function. The client MUST allocate the memory for this structure and the 194 * items pointed to by this structure. When the structure is passed into 195 * the function, ownership of the memory passes to the function. Ownership 196 * of the memory returns to the client when this structure is returned in 197 * the callback function. 198 * 199 * For optimal performance all data buffers SHOULD be 8-byte aligned. 200 * 201 * All values in this structure are required to be in Most Significant Byte 202 * first order, e.g. a.pData[0] = MSB. 203 * 204 * @note 205 * If the client modifies or frees the memory referenced in this 206 * structure after it has been submitted to the cpaCyEcPointMultiply 207 * function, and before it has been returned in the callback, undefined 208 * behavior will result. 209 * 210 * @see 211 * cpaCyEcPointMultiply() 212 * 213 *****************************************************************************/ 214 typedef struct _CpaCyEcPointMultiplyOpData { 215 CpaFlatBuffer k; 216 /**< scalar multiplier (k > 0 and k < n) */ 217 CpaFlatBuffer xg; 218 /**< x coordinate of curve point */ 219 CpaFlatBuffer yg; 220 /**< y coordinate of curve point */ 221 CpaFlatBuffer a; 222 /**< a elliptic curve coefficient */ 223 CpaFlatBuffer b; 224 /**< b elliptic curve coefficient */ 225 CpaFlatBuffer q; 226 /**< prime modulus or irreducible polynomial over GF(2^m)*/ 227 CpaFlatBuffer h; 228 /**< cofactor of the operation. 229 * If the cofactor is NOT required then set the cofactor to 1 or the 230 * data pointer of the Flat Buffer to NULL. */ 231 CpaCyEcFieldType fieldType; 232 /**< field type for the operation */ 233 } CpaCyEcPointMultiplyOpData; 234 235 236 /** 237 ***************************************************************************** 238 * @ingroup cpaCyEc 239 * EC Point Verification Operation Data. 240 * 241 * @description 242 * This structure contains the operation data for the cpaCyEcPointVerify 243 * function. The client MUST allocate the memory for this structure and the 244 * items pointed to by this structure. When the structure is passed into 245 * the function, ownership of the memory passes to the function. Ownership 246 * of the memory returns to the client when this structure is returned in 247 * the callback function. 248 * 249 * For optimal performance all data buffers SHOULD be 8-byte aligned. 250 * 251 * All values in this structure are required to be in Most Significant Byte 252 * first order, e.g. a.pData[0] = MSB. 253 * 254 * @note 255 * If the client modifies or frees the memory referenced in this 256 * structure after it has been submitted to the CpaCyEcPointVerify 257 * function, and before it has been returned in the callback, undefined 258 * behavior will result. 259 * 260 * @see 261 * cpaCyEcPointVerify() 262 * 263 *****************************************************************************/ 264 typedef struct _CpaCyEcPointVerifyOpData { 265 CpaFlatBuffer xq; 266 /**< x coordinate candidate point */ 267 CpaFlatBuffer yq; 268 /**< y coordinate candidate point */ 269 CpaFlatBuffer q; 270 /**< prime modulus or irreducible polynomial over GF(2^m) */ 271 CpaFlatBuffer a; 272 /**< a elliptic curve coefficient */ 273 CpaFlatBuffer b; 274 /**< b elliptic curve coefficient */ 275 276 CpaCyEcFieldType fieldType; 277 /**< field type for the operation */ 278 } CpaCyEcPointVerifyOpData; 279 280 /** 281 ***************************************************************************** 282 * @file cpa_cy_ec.h 283 * @ingroup cpaCyEc 284 * EC Point Multiplication Operation Data for Edwards or 285 8 Montgomery curves as specificied in RFC#7748. 286 * 287 * @description 288 * This structure contains the operation data for the 289 * cpaCyEcMontEdwdsPointMultiply function. 290 * The client MUST allocate the memory for this structure and the 291 * items pointed to by this structure. When the structure is passed into 292 * the function, ownership of the memory passes to the function. Ownership 293 * of the memory returns to the client when this structure is returned in 294 * the callback function. 295 * 296 * For optimal performance all data buffers SHOULD be 8-byte aligned. 297 * 298 * All values in this structure are required to be in Most Significant Byte 299 * first order, e.g. a.pData[0] = MSB. 300 * 301 * @note 302 * If the client modifies or frees the memory referenced in this 303 * structure after it has been submitted to the cpaCyEcPointMultiply 304 * function, and before it has been returned in the callback, undefined 305 * behavior will result. 306 * 307 * All buffers in this structure need to be: 308 * - 32 bytes in size for 25519 curves 309 * - 64 bytes in size for 448 curves 310 * 311 * @see 312 * cpaCyEcMontEdwdsPointMultiply() 313 * 314 *****************************************************************************/ 315 typedef struct _CpaCyEcMontEdwdsPointMultiplyOpData { 316 CpaCyEcMontEdwdsCurveType curveType; 317 /**< field type for the operation */ 318 CpaBoolean generator; 319 /**< True if the operation is a generator multiplication (kG) 320 * False if it is a variable point multiplcation (kP). */ 321 CpaFlatBuffer k; 322 /**< k or generator for the operation */ 323 CpaFlatBuffer x; 324 /**< x value. Used in scalar varable point multiplication operations. 325 * Not required if the generator is True. Must be NULL if not required. 326 * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 327 * curves */ 328 CpaFlatBuffer y; 329 /**< y value. Used in variable point multiplication of operations. 330 * Not required for curves defined only on scalar operations. 331 * Not required if the generator is True. 332 * Must be NULL if not required. 333 * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 334 * curves */ 335 } CpaCyEcMontEdwdsPointMultiplyOpData; 336 337 /** 338 ***************************************************************************** 339 * @ingroup cpaCyEc 340 * Cryptographic EC Statistics. 341 * 342 * @description 343 * This structure contains statistics on the Cryptographic EC 344 * operations. Statistics are set to zero when the component is 345 * initialized, and are collected per instance. 346 * 347 ****************************************************************************/ 348 typedef struct _CpaCyEcStats64 { 349 Cpa64U numEcPointMultiplyRequests; 350 /**< Total number of EC Point Multiplication operation requests. */ 351 Cpa64U numEcPointMultiplyRequestErrors; 352 /**< Total number of EC Point Multiplication operation requests that had an 353 * error and could not be processed. */ 354 Cpa64U numEcPointMultiplyCompleted; 355 /**< Total number of EC Point Multiplication operation requests that 356 * completed successfully. */ 357 Cpa64U numEcPointMultiplyCompletedError; 358 /**< Total number of EC Point Multiplication operation requests that could 359 * not be completed successfully due to errors. */ 360 Cpa64U numEcPointMultiplyCompletedOutputInvalid; 361 /**< Total number of EC Point Multiplication operation requests that could 362 * not be completed successfully due to an invalid output. 363 * Note that this does not indicate an error. */ 364 Cpa64U numEcPointVerifyRequests; 365 /**< Total number of EC Point Verification operation requests. */ 366 Cpa64U numEcPointVerifyRequestErrors; 367 /**< Total number of EC Point Verification operation requests that had an 368 * error and could not be processed. */ 369 Cpa64U numEcPointVerifyCompleted; 370 /**< Total number of EC Point Verification operation requests that completed 371 * successfully. */ 372 Cpa64U numEcPointVerifyCompletedErrors; 373 /**< Total number of EC Point Verification operation requests that could 374 * not be completed successfully due to errors. */ 375 Cpa64U numEcPointVerifyCompletedOutputInvalid; 376 /**< Total number of EC Point Verification operation requests that had an 377 * invalid output. Note that this does not indicate an error. */ 378 } CpaCyEcStats64; 379 380 381 /** 382 ***************************************************************************** 383 * @ingroup cpaCyEc 384 * Definition of callback function invoked for cpaCyEcPointMultiply 385 * requests. 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 Opaque pointer to Operation data supplied in 403 * request. 404 * @param[in] multiplyStatus Status of the point multiplication. 405 * @param[in] pXk x coordinate of resultant EC point. 406 * @param[in] pYk y coordinate of resultant EC point. 407 * 408 * @retval 409 * None 410 * @pre 411 * Component has been initialized. 412 * @post 413 * None 414 * @note 415 * None 416 * @see 417 * cpaCyEcPointMultiply() 418 * 419 *****************************************************************************/ 420 typedef void (*CpaCyEcPointMultiplyCbFunc)(void *pCallbackTag, 421 CpaStatus status, 422 void *pOpData, 423 CpaBoolean multiplyStatus, 424 CpaFlatBuffer *pXk, 425 CpaFlatBuffer *pYk); 426 427 428 /** 429 ***************************************************************************** 430 * @ingroup cpaCyEc 431 * Definition of callback function invoked for cpaCyEcPointVerify 432 * requests. 433 * @context 434 * This callback function can be executed in a context that DOES NOT 435 * permit sleeping to occur. 436 * @assumptions 437 * None 438 * @sideEffects 439 * None 440 * @reentrant 441 * No 442 * @threadSafe 443 * Yes 444 * 445 * @param[in] pCallbackTag User-supplied value to help identify request. 446 * @param[in] status Status of the operation. Valid values are 447 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 448 * CPA_STATUS_UNSUPPORTED. 449 * @param[in] pOpData Operation data pointer supplied in request. 450 * @param[in] verifyStatus Set to CPA_FALSE if the point is NOT on the 451 * curve or at infinity. Set to CPA_TRUE if the 452 * point is on the curve. 453 * 454 * @return 455 * None 456 * @pre 457 * Component has been initialized. 458 * @post 459 * None 460 * @note 461 * None 462 * @see 463 * cpaCyEcPointVerify() 464 * 465 *****************************************************************************/ 466 typedef void (*CpaCyEcPointVerifyCbFunc)(void *pCallbackTag, 467 CpaStatus status, 468 void *pOpData, 469 CpaBoolean verifyStatus); 470 471 472 /** 473 ***************************************************************************** 474 * @ingroup cpaCyEc 475 * Perform EC Point Multiplication. 476 * 477 * @description 478 * This function performs Elliptic Curve Point Multiplication as per 479 * ANSI X9.63 Annex D.3.2. 480 * 481 * @context 482 * When called as an asynchronous function it cannot sleep. It can be 483 * executed in a context that does not permit sleeping. 484 * When called as a synchronous function it may sleep. It MUST NOT be 485 * executed in a context that DOES NOT permit sleeping. 486 * @assumptions 487 * None 488 * @sideEffects 489 * None 490 * @blocking 491 * Yes when configured to operate in synchronous mode. 492 * @reentrant 493 * No 494 * @threadSafe 495 * Yes 496 * 497 * @param[in] instanceHandle Instance handle. 498 * @param[in] pCb Callback function pointer. If this is set to 499 * a NULL value the function will operate 500 * synchronously. 501 * @param[in] pCallbackTag User-supplied value to help identify request. 502 * @param[in] pOpData Structure containing all the data needed to 503 * perform the operation. The client code 504 * allocates the memory for this structure. This 505 * component takes ownership of the memory until 506 * it is returned in the callback. 507 * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 508 * valid (CPA_TRUE) or the output is invalid 509 * (CPA_FALSE). 510 * @param[out] pXk Pointer to xk flat buffer. 511 * @param[out] pYk Pointer to yk flat buffer. 512 * 513 * @retval CPA_STATUS_SUCCESS Function executed successfully. 514 * @retval CPA_STATUS_FAIL Function failed. 515 * @retval CPA_STATUS_RETRY Resubmit the request. 516 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 517 * @retval CPA_STATUS_RESOURCE Error related to system resources. 518 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 519 * the request. 520 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 521 * 522 * @pre 523 * The component has been initialized via cpaCyStartInstance function. 524 * @post 525 * None 526 * @note 527 * When pCb is non-NULL an asynchronous callback of type 528 * CpaCyEcPointMultiplyCbFunc is generated in response to this function 529 * call. 530 * For optimal performance, data pointers SHOULD be 8-byte aligned. 531 * 532 * @see 533 * CpaCyEcPointMultiplyOpData, 534 * CpaCyEcPointMultiplyCbFunc 535 * 536 *****************************************************************************/ 537 CpaStatus 538 cpaCyEcPointMultiply(const CpaInstanceHandle instanceHandle, 539 const CpaCyEcPointMultiplyCbFunc pCb, 540 void *pCallbackTag, 541 const CpaCyEcPointMultiplyOpData *pOpData, 542 CpaBoolean *pMultiplyStatus, 543 CpaFlatBuffer *pXk, 544 CpaFlatBuffer *pYk); 545 546 547 /** 548 ***************************************************************************** 549 * @ingroup cpaCyEc 550 * Verify that a point is on an elliptic curve. 551 * 552 * @description 553 * This function performs Elliptic Curve Point Verification, as per 554 * steps a, b and c of ANSI X9.62 Annex A.4.2. (To perform the final 555 * step d, the user can call @ref cpaCyEcPointMultiply.) 556 * 557 * This function checks if the specified point satisfies the 558 * Weierstrass equation for an Elliptic Curve. 559 * 560 * For GF(p): 561 * y^2 = (x^3 + ax + b) mod p 562 * For GF(2^m): 563 * y^2 + xy = x^3 + ax^2 + b mod p 564 * where p is the irreducible polynomial over GF(2^m) 565 * 566 * Use this function to verify a point is in the correct range and is 567 * NOT the point at infinity. 568 * 569 * @context 570 * When called as an asynchronous function it cannot sleep. It can be 571 * executed in a context that does not permit sleeping. 572 * When called as a synchronous function it may sleep. It MUST NOT be 573 * executed in a context that DOES NOT permit sleeping. 574 * @assumptions 575 * None 576 * @sideEffects 577 * None 578 * @blocking 579 * Yes when configured to operate in synchronous mode. 580 * @reentrant 581 * No 582 * @threadSafe 583 * Yes 584 * 585 * @param[in] instanceHandle Instance handle. 586 * @param[in] pCb Callback function pointer. If this is set to 587 * a NULL value the function will operate 588 * synchronously. 589 * @param[in] pCallbackTag User-supplied value to help identify request. 590 * @param[in] pOpData Structure containing all the data needed to 591 * perform the operation. The client code 592 * allocates the memory for this structure. This 593 * component takes ownership of the memory until 594 * it is returned in the callback. 595 * @param[out] pVerifyStatus In synchronous mode, set to CPA_FALSE if the 596 * point is NOT on the curve or at infinity. Set 597 * to CPA_TRUE if the point is on the curve. 598 * 599 * @retval CPA_STATUS_SUCCESS Function executed successfully. 600 * @retval CPA_STATUS_FAIL Function failed. 601 * @retval CPA_STATUS_RETRY Resubmit the request. 602 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 603 * @retval CPA_STATUS_RESOURCE Error related to system resources. 604 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 605 * the request. 606 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 607 * 608 * @pre 609 * The component has been initialized via cpaCyStartInstance function. 610 * @post 611 * None 612 * @note 613 * When pCb is non-NULL an asynchronous callback of type 614 * CpaCyEcPointVerifyCbFunc is generated in response to this function 615 * call. 616 * For optimal performance, data pointers SHOULD be 8-byte aligned. 617 * 618 * @see 619 * CpaCyEcPointVerifyOpData, 620 * CpaCyEcPointVerifyCbFunc 621 * 622 *****************************************************************************/ 623 CpaStatus 624 cpaCyEcPointVerify(const CpaInstanceHandle instanceHandle, 625 const CpaCyEcPointVerifyCbFunc pCb, 626 void *pCallbackTag, 627 const CpaCyEcPointVerifyOpData *pOpData, 628 CpaBoolean *pVerifyStatus); 629 630 /** 631 ***************************************************************************** 632 * @file cpa_cy_ec.h 633 * @ingroup cpaCyEc 634 * Perform EC Point Multiplication on an Edwards or Montgomery curve as 635 * defined in RFC#7748. 636 * 637 * @description 638 * This function performs Elliptic Curve Point Multiplication as per 639 * RFC#7748 640 * 641 * @context 642 * When called as an asynchronous function it cannot sleep. It can be 643 * executed in a context that does not permit sleeping. 644 * When called as a synchronous function it may sleep. It MUST NOT be 645 * executed in a context that DOES NOT permit sleeping. 646 * @assumptions 647 * None 648 * @sideEffects 649 * None 650 * @blocking 651 * Yes when configured to operate in synchronous mode. 652 * @reentrant 653 * No 654 * @threadSafe 655 * Yes 656 * 657 * @param[in] instanceHandle Instance handle. 658 * @param[in] pCb Callback function pointer. If this is set to 659 * a NULL value the function will operate 660 * synchronously. 661 * @param[in] pCallbackTag User-supplied value to help identify request. 662 * @param[in] pOpData Structure containing all the data needed to 663 * perform the operation. The client code 664 * allocates the memory for this structure. This 665 * component takes ownership of the memory until 666 * it is returned in the callback. 667 * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 668 * valid (CPA_TRUE) or the output is invalid 669 * (CPA_FALSE). 670 * @param[out] pXk Pointer to xk flat buffer. 671 * @param[out] pYk Pointer to yk flat buffer. 672 * 673 * @retval CPA_STATUS_SUCCESS Function executed successfully. 674 * @retval CPA_STATUS_FAIL Function failed. 675 * @retval CPA_STATUS_RETRY Resubmit the request. 676 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 677 * @retval CPA_STATUS_RESOURCE Error related to system resources. 678 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 679 * the request. 680 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 681 * 682 * @pre 683 * The component has been initialized via cpaCyStartInstance function. 684 * @post 685 * None 686 * @note 687 * When pCb is non-NULL an asynchronous callback of type 688 * CpaCyEcPointMultiplyCbFunc is generated in response to this function 689 * call. 690 * For optimal performance, data pointers SHOULD be 8-byte aligned. 691 * 692 * @see 693 * CpaCyEcMontEdwdsPointMultiplyOpData, 694 * CpaCyEcMontEdwdsPointMultiplyCbFunc 695 * 696 *****************************************************************************/ 697 CpaStatus 698 cpaCyEcMontEdwdsPointMultiply(const CpaInstanceHandle instanceHandle, 699 const CpaCyEcPointMultiplyCbFunc pCb, 700 void *pCallbackTag, 701 const CpaCyEcMontEdwdsPointMultiplyOpData *pOpData, 702 CpaBoolean *pMultiplyStatus, 703 CpaFlatBuffer *pXk, 704 CpaFlatBuffer *pYk); 705 706 /** 707 ***************************************************************************** 708 * @ingroup cpaCyEc 709 * Query statistics for a specific EC instance. 710 * 711 * @description 712 * This function will query a specific instance of the EC implementation 713 * for statistics. The user MUST allocate the CpaCyEcStats64 structure 714 * and pass the reference to that structure into this function call. This 715 * function writes the statistic results into the passed in 716 * CpaCyEcStats64 structure. 717 * 718 * Note: statistics returned by this function do not interrupt current data 719 * processing and as such can be slightly out of sync with operations that 720 * are in progress during the statistics retrieval process. 721 * 722 * @context 723 * This is a synchronous function and it can sleep. It MUST NOT be 724 * executed in a context that DOES NOT permit sleeping. 725 * @assumptions 726 * None 727 * @sideEffects 728 * None 729 * @blocking 730 * This function is synchronous and blocking. 731 * @reentrant 732 * No 733 * @threadSafe 734 * Yes 735 * 736 * @param[in] instanceHandle Instance handle. 737 * @param[out] pEcStats Pointer to memory into which the statistics 738 * will be written. 739 * 740 * @retval CPA_STATUS_SUCCESS Function executed successfully. 741 * @retval CPA_STATUS_FAIL Function failed. 742 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 743 * @retval CPA_STATUS_RESOURCE Error related to system resources. 744 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 745 * the request. 746 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 747 * 748 * @pre 749 * Component has been initialized. 750 * @post 751 * None 752 * @note 753 * This function operates in a synchronous manner and no asynchronous 754 * callback will be generated. 755 * @see 756 * CpaCyEcStats64 757 *****************************************************************************/ 758 CpaStatus 759 cpaCyEcQueryStats64(const CpaInstanceHandle instanceHandle, 760 CpaCyEcStats64 *pEcStats); 761 762 #ifdef __cplusplus 763 } /* close the extern "C" { */ 764 #endif 765 766 #endif /*CPA_CY_EC_H_*/ 767