1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /* 5 ***************************************************************************** 6 * Doxygen group definitions 7 ****************************************************************************/ 8 9 /** 10 ***************************************************************************** 11 * @file cpa_cy_ec.h 12 * 13 * @defgroup cpaCyEc Elliptic Curve (EC) API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for Public Key Encryption 19 * (Cryptography) Elliptic Curve (EC) operations. 20 * 21 * All implementations will support at least the following: 22 * 23 * - "NIST RECOMMENDED ELLIPTIC CURVES FOR FEDERAL GOVERNMENT USE" 24 * as defined by 25 * http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf 26 * 27 * - Random curves where the max(log2(q), log2(n) + log2(h)) <= 512 28 * where q is the modulus, n is the order of the curve and h is the 29 * cofactor 30 * 31 * For Montgomery and Edwards 25519 and 448 elliptic curves, 32 * the following operations are supported: 33 * 1. Montgomery 25519 Curve | scalar point Multiplication 34 * Input: Montgomery affine coordinate X of point P 35 * Scalar k 36 * Output: Montgomery affine coordinate X of point [k]P 37 * Decode: Scalar k always decoded by implementation 38 * 39 * 2. Montgomery 25519 Curve | generator point Multiplication 40 * Input: Scalar k 41 * Output: Montgomery affine coordinate X of point [k]G 42 * Decode: Scalar k always decoded by implementation 43 * 44 * 3. Twisted Edwards 25519 Curve | scalar point Multiplication 45 * Input: Twisted Edwards affine coordinate X of point P 46 * Twisted Edwards affine coordinate Y of point P 47 * Scalar k 48 * Output: Twisted Edwards affine coordinate X of point [k]P 49 * Twisted Edwards affine coordinate Y of point [k]P 50 * Decode: Caller must supply parameters in MSB order, the 51 * implementation will not explicitly decode according 52 * to RFC#7748 Section 5 53 * 54 * 4. Twisted Edwards 25519 Curve | generator point Multiplication 55 * Input: Scalar k 56 * Output: Twisted Edwards affine coordinate X of point [k]G 57 * Twisted Edwards affine coordinate Y of point [k]G 58 * Decode: Caller must supply parameters in MSB order, the 59 * implementation will not explicitly decode according 60 * to RFC#7748 Section 5 61 * 62 * 5. Montgomery 448 Curve | scalar point Multiplication 63 * Input: Montgomery affine coordinate X of point P 64 * Scalar k 65 * Output: Montgomery affine coordinate X of point [k]P 66 * Decode: Scalar k always decoded by implementation 67 * 68 * 6. Montgomery 448 Curve | generator point Multiplication 69 * Input: Scalar k 70 * Output: Montgomery affine coordinate X of point [k]G 71 * Decode: Scalar k always decoded by implementation 72 * 73 * 7. Edwards 448 Curve | scalar point Multiplication 74 * Input: Edwards affine coordinate X of point P 75 * Edwards affine coordinate Y of point P 76 * Scalar k 77 * Output: Edwards affine coordinate X of point [k]P 78 * Edwards affine coordinate Y of point [k]P 79 * Decode: Caller must supply parameters in MSB order, the 80 * implementation will not explicitly decode according 81 * to RFC#7748 Section 5 82 * 83 * 8. Edwards 448 Curve | generator point Multiplication 84 * Input: Scalar k 85 * Output: Edwards affine coordinate X of point [k]G 86 * Edwards affine coordinate Y of point [k]G 87 * Decode: Caller must supply parameters in MSB order, the 88 * implementation will not explicitly decode according 89 * to RFC#7748 Section 5 90 * 91 * @note 92 * Large numbers are represented on the QuickAssist API as described 93 * in the Large Number API (@ref cpaCyLn). 94 * 95 * In addition, the bit length of large numbers passed to the API 96 * MUST NOT exceed 576 bits for Elliptic Curve operations. 97 *****************************************************************************/ 98 99 #ifndef CPA_CY_EC_H_ 100 #define CPA_CY_EC_H_ 101 102 #ifdef __cplusplus 103 extern "C" { 104 #endif 105 106 #include "cpa_cy_common.h" 107 108 /** 109 ***************************************************************************** 110 * @ingroup cpaCyEc 111 * Field types for Elliptic Curve 112 113 * @description 114 * As defined by FIPS-186-3, for each cryptovariable length, there are 115 * two kinds of fields. 116 * <ul> 117 * <li> A prime field is the field GF(p) which contains a prime number 118 * p of elements. The elements of this field are the integers modulo 119 * p, and the field arithmetic is implemented in terms of the 120 * arithmetic of integers modulo p.</li> 121 * 122 * <li> A binary field is the field GF(2^m) which contains 2^m elements 123 * for some m (called the degree of the field). The elements of 124 * this field are the bit strings of length m, and the field 125 * arithmetic is implemented in terms of operations on the bits.</li> 126 * </ul> 127 *****************************************************************************/ 128 typedef enum _CpaCyEcFieldType 129 { 130 CPA_CY_EC_FIELD_TYPE_PRIME = 1, 131 /**< A prime field, GF(p) */ 132 CPA_CY_EC_FIELD_TYPE_BINARY, 133 /**< A binary field, GF(2^m) */ 134 } CpaCyEcFieldType; 135 136 /** 137 ***************************************************************************** 138 * @ingroup cpaCyEc 139 * Enumeration listing curve types to use with generic multiplication 140 * and verification routines. 141 * 142 * @description 143 * This structure contains a list of different elliptic curve types. 144 * EC Point multiplication and other operations depend on the type of 145 * the curve. 146 * 147 * @see 148 * cpaCyEcGenericPointMultiply() 149 * cpaCyEcGenericPointVerify() 150 * 151 *****************************************************************************/ 152 typedef enum _CpaCyEcCurveType 153 { 154 CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_PRIME = 1, 155 /**< A Weierstrass curve with arithmetic in terms of the 156 * arithmetic of integers modulo p over a prime field. */ 157 CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_BINARY, 158 /**< A Weierstrass curve with arithmetic in terms of operations on bits 159 * over a binary field. */ 160 CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_KOBLITZ_BINARY, 161 /**< A Weierstrass-koblitz curve with arithmetic in terms of operations on 162 * the bits over a binary field. */ 163 } CpaCyEcCurveType; 164 165 /** 166 ***************************************************************************** 167 * @ingroup cpaCyEc 168 * Curve types for Elliptic Curves defined in RFC#7748 169 170 * @description 171 * As defined by RFC 7748, there are four elliptic curves in this 172 * group. The Montgomery curves are denoted curve25519 and curve448, 173 * and the birationally equivalent Twisted Edwards curves are denoted 174 * edwards25519 and edwards448 175 * 176 *****************************************************************************/ 177 typedef enum _CpaCyEcMontEdwdsCurveType 178 { 179 CPA_CY_EC_MONTEDWDS_CURVE25519_TYPE = 1, 180 /**< Montgomery 25519 curve */ 181 CPA_CY_EC_MONTEDWDS_ED25519_TYPE, 182 /**< Edwards 25519 curve */ 183 CPA_CY_EC_MONTEDWDS_CURVE448_TYPE, 184 /**< Montgomery 448 curve */ 185 CPA_CY_EC_MONTEDWDS_ED448_TYPE, 186 /**< Edwards 448 curve */ 187 } CpaCyEcMontEdwdsCurveType; 188 189 /** 190 ***************************************************************************** 191 * @ingroup cpaCyEc 192 * Curve parameters for a Weierstrass type curve. 193 * 194 * @description 195 * This structure contains curve parameters for Weierstrass type 196 * curve: y^2 = x^3 + ax + b 197 * The client MUST allocate the memory for this structure 198 * When the structure is passed into the function, ownership of the memory 199 * passes to the function. Ownership of the memory returns to the client 200 * when this structure is returned in the callback function. 201 * 202 * For optimal performance all data buffers SHOULD be 8-byte aligned. 203 * The legend used in this structure is borrowed from RFC7748 204 * 205 * @note 206 * If the client modifies or frees the memory referenced in this 207 * structure after it has been submitted to the function, and before it 208 * has been returned in the callback, undefined behavior will result. 209 * 210 * @see 211 * CpaCyEcCurveParameters 212 * CpaCyEcFieldType 213 * 214 *****************************************************************************/ 215 typedef struct _CpaCyEcCurveParametersWeierstrass 216 { 217 CpaCyEcFieldType fieldType; 218 /**< Prime or Binary */ 219 CpaFlatBuffer p; 220 /**< Prime modulus or irreducible polynomial over GF(2^m) */ 221 CpaFlatBuffer a; 222 /**< a coefficient */ 223 CpaFlatBuffer b; 224 /**< b coefficient */ 225 CpaFlatBuffer h; 226 /**< Cofactor */ 227 } CpaCyEcCurveParametersWeierstrass; 228 229 /** 230 ***************************************************************************** 231 * @ingroup cpaCyEc 232 * Union characterised by a specific curve. 233 * 234 * @description 235 * This union allows for the characterisation of different curve types 236 * encapsulated in one data type. The intention is that new curve types 237 * will be added in the future. 238 * 239 * @note 240 * 241 * @see 242 * CpaCyEcCurveParametersWeierstrass 243 * 244 *****************************************************************************/ 245 typedef union _CpaCyEcCurveParameters 246 { 247 CpaCyEcCurveParametersWeierstrass weierstrassParameters; 248 } CpaCyEcCurveParameters; 249 250 /** 251 ***************************************************************************** 252 * @ingroup cpaCyEc 253 * Unified curve parameters. 254 * 255 * @description 256 * This structure provides a single data type that can describe a number 257 * of different curve types. The intention is to add further 258 * curve types in the future, thus the union field will allow for that 259 * expansion. 260 * 261 * The client MUST allocate the memory for this structure and the 262 * items pointed to by this structure. When the structure is passed into 263 * the function, ownership of the memory passes to the function. Ownership 264 * of the memory returns to the client when this structure is returned in 265 * the callback function. 266 * 267 * For optimal performance all data buffers SHOULD be 8-byte aligned. 268 * 269 * @note 270 * If the client modifies or frees the memory referenced in this 271 * structure after it has been submitted to the function, and before it 272 * has been returned in the callback, undefined behavior will result. 273 * 274 * @see 275 * CpaCyEcCurveParameters 276 * cpaCyEcGenericPointMultiply 277 * cpaCyEcGenericPointVerify 278 * 279 *****************************************************************************/ 280 typedef struct _CpaCyEcCurve 281 { 282 CpaCyEcCurveType curveType; 283 CpaCyEcCurveParameters parameters; 284 } CpaCyEcCurve; 285 286 /** 287 ***************************************************************************** 288 * @ingroup cpaCyEc 289 * EC Point Multiplication Operation Data. 290 * 291 * @description 292 * This structure contains the operation data for the cpaCyEcPointMultiply 293 * function. The client MUST allocate the memory for this structure and the 294 * items pointed to by this structure. When the structure is passed into 295 * the function, ownership of the memory passes to the function. Ownership 296 * of the memory returns to the client when this structure is returned in 297 * the callback function. 298 * 299 * For optimal performance all data buffers SHOULD be 8-byte aligned. 300 * 301 * All values in this structure are required to be in Most Significant Byte 302 * first order, e.g. a.pData[0] = MSB. 303 * 304 * @note 305 * If the client modifies or frees the memory referenced in this 306 * structure after it has been submitted to the cpaCyEcPointMultiply 307 * function, and before it has been returned in the callback, undefined 308 * behavior will result. 309 * 310 * @see 311 * cpaCyEcPointMultiply() 312 * 313 *****************************************************************************/ 314 typedef struct _CpaCyEcPointMultiplyOpData { 315 CpaFlatBuffer k; 316 /**< scalar multiplier (k > 0 and k < n) */ 317 CpaFlatBuffer xg; 318 /**< x coordinate of curve point */ 319 CpaFlatBuffer yg; 320 /**< y coordinate of curve point */ 321 CpaFlatBuffer a; 322 /**< a elliptic curve coefficient */ 323 CpaFlatBuffer b; 324 /**< b elliptic curve coefficient */ 325 CpaFlatBuffer q; 326 /**< prime modulus or irreducible polynomial over GF(2^m)*/ 327 CpaFlatBuffer h; 328 /**< cofactor of the operation. 329 * If the cofactor is NOT required then set the cofactor to 1 or the 330 * data pointer of the Flat Buffer to NULL. */ 331 CpaCyEcFieldType fieldType; 332 /**< field type for the operation */ 333 } CpaCyEcPointMultiplyOpData CPA_DEPRECATED; 334 335 /** 336 ***************************************************************************** 337 * @ingroup cpaCyEc 338 * Generic EC Point Multiplication Operation Data. 339 * 340 * @description 341 * This structure contains a generic EC point and a multiplier for use with 342 * cpaCyEcGenericPointMultiply. This is common for representing all EC 343 * points, irrespective of curve type: Weierstrass, Montgomery and Twisted 344 * Edwards (at this time only Weierstrass are supported). The same 345 * point + multiplier format can be used when performing generator 346 * multiplication, in which case the xP, yP supplied in this structure will 347 * be ignored by QAT API library & a generator point will be inserted in 348 * their place. 349 * 350 * For optimal performance all data buffers SHOULD be 8-byte aligned. 351 * 352 * All values in this structure are required to be in Most Significant Byte 353 * first order, e.g. a.pData[0] = MSB. 354 * 355 * @note 356 * If the client modifies or frees the memory referenced in this 357 * structure after it has been submitted to the cpaCyEcGenericPointMultiply 358 * function, and before it has been returned in the callback, undefined 359 * behavior will result. 360 * 361 * @see 362 * cpaCyEcGenericPointMultiply() 363 * 364 *****************************************************************************/ 365 typedef struct _CpaCyEcGenericPointMultiplyOpData { 366 CpaFlatBuffer k; 367 /** <scalar multiplier (k > 0 and k < n) */ 368 CpaFlatBuffer xP; 369 /** <x coordinate of public key */ 370 CpaFlatBuffer yP; 371 /** <y coordinate of public key */ 372 CpaCyEcCurve *pCurve; 373 /** <curve type specific parameters */ 374 CpaBoolean generator; 375 /** <if TRUE xP and yP are the generator points */ 376 } CpaCyEcGenericPointMultiplyOpData; 377 378 /** 379 ***************************************************************************** 380 * @ingroup cpaCyEc 381 * Generic EC Point Verify Operation Data. 382 * 383 * @description 384 * This structure contains the operation data for the 385 * cpaCyEcGenericPointVerify function. This is common for representing 386 * all EC points, irrespective of curve type: Weierstrass, Montgomery and 387 * Twisted Edwards (at this time only Weierstrass are supported). 388 * 389 * This structure contains a generic EC point, irrespective of curve type. 390 * It is used to verify when the <x,y> pair specified in the structure 391 * lies on the curve indicated in the cpaCyEcGenericPointVerify API. 392 * 393 * For optimal performance all data buffers SHOULD be 8-byte aligned. 394 * 395 * All values in this structure are required to be in Most Significant Byte 396 * first order, e.g. a.pData[0] = MSB. 397 * 398 * @note 399 * If the client modifies or frees the memory referenced in this 400 * structure after it has been submitted to the cpaCyEcGenericPointVerify 401 * function, and before it has been returned in the callback, undefined 402 * behavior will result. 403 * 404 * @see 405 * cpaCyEcGenericPointVerify() 406 * 407 *****************************************************************************/ 408 typedef struct _CpaCyEcGenericPointVerifyOpData { 409 CpaFlatBuffer xP; 410 /** <x coordinate of public key */ 411 CpaFlatBuffer yP; 412 /** <y coordinate of public key */ 413 CpaCyEcCurve *pCurve; 414 /** <curve type specific parameters */ 415 } CpaCyEcGenericPointVerifyOpData; 416 417 /** 418 ***************************************************************************** 419 * @ingroup cpaCyEc 420 * EC Point Multiplication Operation Data for Edwards or 421 * Montgomery curves as specified in RFC#7748. 422 * 423 * @description 424 * This structure contains the operation data for the 425 * cpaCyEcMontEdwdsPointMultiply function. 426 * The client MUST allocate the memory for this structure and the 427 * items pointed to by this structure. When the structure is passed into 428 * the function, ownership of the memory passes to the function. Ownership 429 * of the memory returns to the client when this structure is returned in 430 * the callback function. 431 * 432 * For optimal performance all data buffers SHOULD be 8-byte aligned. 433 * 434 * All values in this structure are required to be in Most Significant Byte 435 * first order, e.g. a.pData[0] = MSB. 436 * 437 * @note 438 * If the client modifies or frees the memory referenced in this 439 * structure after it has been submitted to the 440 * cpaCyEcMontEdwdsPointMultiply function, and before it has been returned 441 * in the callback, undefined behavior will result. 442 * 443 * All buffers in this structure need to be: 444 * - 32 bytes in size for 25519 curves 445 * - 64 bytes in size for 448 curves 446 * 447 * @see 448 * cpaCyEcMontEdwdsPointMultiply() 449 * 450 *****************************************************************************/ 451 typedef struct _CpaCyEcMontEdwdsPointMultiplyOpData { 452 CpaCyEcMontEdwdsCurveType curveType; 453 /**< field type for the operation */ 454 CpaBoolean generator; 455 /**< True if the operation is a generator multiplication (kG) 456 * False if it is a variable point multiplication (kP). */ 457 CpaFlatBuffer k; 458 /**< k scalar multiplier for the operation */ 459 CpaFlatBuffer x; 460 /**< x value. Used in scalar variable point multiplication operations. 461 * Not required if the generator is True. Must be NULL if not required. 462 * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 463 * curves */ 464 CpaFlatBuffer y; 465 /**< y value. Used in variable point multiplication of operations. 466 * Not required if the generator is True. 467 * Must be NULL if not required. 468 * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 469 * curves */ 470 } CpaCyEcMontEdwdsPointMultiplyOpData; 471 472 /** 473 ***************************************************************************** 474 * @ingroup cpaCyEc 475 * EC Point Verification Operation Data. 476 * 477 * @description 478 * This structure contains the operation data for the cpaCyEcPointVerify 479 * function. The client MUST allocate the memory for this structure and the 480 * items pointed to by this structure. When the structure is passed into 481 * the function, ownership of the memory passes to the function. Ownership 482 * of the memory returns to the client when this structure is returned in 483 * the callback function. 484 * 485 * For optimal performance all data buffers SHOULD be 8-byte aligned. 486 * 487 * All values in this structure are required to be in Most Significant Byte 488 * first order, e.g. a.pData[0] = MSB. 489 * 490 * @note 491 * If the client modifies or frees the memory referenced in this 492 * structure after it has been submitted to the CpaCyEcPointVerify 493 * function, and before it has been returned in the callback, undefined 494 * behavior will result. 495 * 496 * @see 497 * cpaCyEcPointVerify() 498 * 499 *****************************************************************************/ 500 typedef struct _CpaCyEcPointVerifyOpData { 501 CpaFlatBuffer xq; 502 /**< x coordinate candidate point */ 503 CpaFlatBuffer yq; 504 /**< y coordinate candidate point */ 505 CpaFlatBuffer q; 506 /**< prime modulus or irreducible polynomial over GF(2^m) */ 507 CpaFlatBuffer a; 508 /**< a elliptic curve coefficient */ 509 CpaFlatBuffer b; 510 /**< b elliptic curve coefficient */ 511 CpaCyEcFieldType fieldType; 512 /**< field type for the operation */ 513 } CpaCyEcPointVerifyOpData CPA_DEPRECATED; 514 515 /** 516 ***************************************************************************** 517 * @ingroup cpaCyEc 518 * Cryptographic EC Statistics. 519 * 520 * @description 521 * This structure contains statistics on the Cryptographic EC 522 * operations. Statistics are set to zero when the component is 523 * initialized, and are collected per instance. 524 * 525 ****************************************************************************/ 526 typedef struct _CpaCyEcStats64 { 527 Cpa64U numEcPointMultiplyRequests; 528 /**< Total number of EC Point Multiplication operation requests. */ 529 Cpa64U numEcPointMultiplyRequestErrors; 530 /**< Total number of EC Point Multiplication operation requests that had an 531 * error and could not be processed. */ 532 Cpa64U numEcPointMultiplyCompleted; 533 /**< Total number of EC Point Multiplication operation requests that 534 * completed successfully. */ 535 Cpa64U numEcPointMultiplyCompletedError; 536 /**< Total number of EC Point Multiplication operation requests that could 537 * not be completed successfully due to errors. */ 538 Cpa64U numEcPointMultiplyCompletedOutputInvalid; 539 /**< Total number of EC Point Multiplication operation requests that could 540 * not be completed successfully due to an invalid output. 541 * Note that this does not indicate an error. */ 542 Cpa64U numEcPointVerifyRequests; 543 /**< Total number of EC Point Verification operation requests. */ 544 Cpa64U numEcPointVerifyRequestErrors; 545 /**< Total number of EC Point Verification operation requests that had an 546 * error and could not be processed. */ 547 Cpa64U numEcPointVerifyCompleted; 548 /**< Total number of EC Point Verification operation requests that completed 549 * successfully. */ 550 Cpa64U numEcPointVerifyCompletedErrors; 551 /**< Total number of EC Point Verification operation requests that could 552 * not be completed successfully due to errors. */ 553 Cpa64U numEcPointVerifyCompletedOutputInvalid; 554 /**< Total number of EC Point Verification operation requests that had an 555 * invalid output. Note that this does not indicate an error. */ 556 } CpaCyEcStats64; 557 558 559 /** 560 ***************************************************************************** 561 * @ingroup cpaCyEc 562 * Definition of callback function invoked for cpaCyEcPointMultiply 563 * requests. 564 * @context 565 * This callback function can be executed in a context that DOES NOT 566 * permit sleeping to occur. 567 * @assumptions 568 * None 569 * @sideEffects 570 * None 571 * @reentrant 572 * No 573 * @threadSafe 574 * Yes 575 * 576 * @param[in] pCallbackTag User-supplied value to help identify request. 577 * @param[in] status Status of the operation. Valid values are 578 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 579 * CPA_STATUS_UNSUPPORTED. 580 * @param[in] pOpData Opaque pointer to Operation data supplied in 581 * request. 582 * @param[in] multiplyStatus Status of the point multiplication. 583 * @param[in] pXk x coordinate of resultant EC point. 584 * @param[in] pYk y coordinate of resultant EC point. 585 * 586 * @retval 587 * None 588 * @pre 589 * Component has been initialized. 590 * @post 591 * None 592 * @note 593 * None 594 * @see 595 * cpaCyEcGenericPointMultiply() 596 * 597 *****************************************************************************/ 598 typedef void (*CpaCyEcPointMultiplyCbFunc)(void *pCallbackTag, 599 CpaStatus status, 600 void *pOpData, 601 CpaBoolean multiplyStatus, 602 CpaFlatBuffer *pXk, 603 CpaFlatBuffer *pYk); 604 605 606 /** 607 ***************************************************************************** 608 * @ingroup cpaCyEc 609 * Definition of callback function invoked for cpaCyEcGenericPointVerify 610 * requests. 611 * @context 612 * This callback function can be executed in a context that DOES NOT 613 * permit sleeping to occur. 614 * @assumptions 615 * None 616 * @sideEffects 617 * None 618 * @reentrant 619 * No 620 * @threadSafe 621 * Yes 622 * 623 * @param[in] pCallbackTag User-supplied value to help identify request. 624 * @param[in] status Status of the operation. Valid values are 625 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 626 * CPA_STATUS_UNSUPPORTED. 627 * @param[in] pOpData Operation data pointer supplied in request. 628 * @param[in] verifyStatus Set to CPA_FALSE if the point is NOT on the 629 * curve or at infinity. Set to CPA_TRUE if the 630 * point is on the curve. 631 * 632 * @return 633 * None 634 * @pre 635 * Component has been initialized. 636 * @post 637 * None 638 * @note 639 * None 640 * @see 641 * cpaCyEcGenericPointVerify() 642 * 643 *****************************************************************************/ 644 typedef void (*CpaCyEcPointVerifyCbFunc)(void *pCallbackTag, 645 CpaStatus status, 646 void *pOpData, 647 CpaBoolean verifyStatus); 648 649 650 /** 651 ***************************************************************************** 652 * @ingroup cpaCyEc 653 * Perform EC Point Multiplication. 654 * 655 * @deprecated 656 * This function is replaced with @ref cpaCyEcGenericPointMultiply 657 * 658 * @description 659 * This function performs Elliptic Curve Point Multiplication as per 660 * ANSI X9.63 Annex D.3.2. 661 * 662 * @context 663 * When called as an asynchronous function it cannot sleep. It can be 664 * executed in a context that does not permit sleeping. 665 * When called as a synchronous function it may sleep. It MUST NOT be 666 * executed in a context that DOES NOT permit sleeping. 667 * @assumptions 668 * None 669 * @sideEffects 670 * None 671 * @blocking 672 * Yes when configured to operate in synchronous mode. 673 * @reentrant 674 * No 675 * @threadSafe 676 * Yes 677 * 678 * @param[in] instanceHandle Instance handle. 679 * @param[in] pCb Callback function pointer. If this is set to 680 * a NULL value the function will operate 681 * synchronously. 682 * @param[in] pCallbackTag User-supplied value to help identify request. 683 * @param[in] pOpData Structure containing all the data needed to 684 * perform the operation. The client code 685 * allocates the memory for this structure. This 686 * component takes ownership of the memory until 687 * it is returned in the callback. 688 * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 689 * valid (CPA_TRUE) or the output is invalid 690 * (CPA_FALSE). 691 * @param[out] pXk Pointer to xk flat buffer. 692 * @param[out] pYk Pointer to yk flat buffer. 693 * 694 * @retval CPA_STATUS_SUCCESS Function executed successfully. 695 * @retval CPA_STATUS_FAIL Function failed. 696 * @retval CPA_STATUS_RETRY Resubmit the request. 697 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 698 * @retval CPA_STATUS_RESOURCE Error related to system resources. 699 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 700 * the request. 701 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 702 * 703 * @pre 704 * The component has been initialized via cpaCyStartInstance function. 705 * @post 706 * None 707 * @note 708 * When pCb is non-NULL an asynchronous callback of type 709 * CpaCyEcPointMultiplyCbFunc is generated in response to this function 710 * call. 711 * For optimal performance, data pointers SHOULD be 8-byte aligned. 712 * 713 * @see 714 * CpaCyEcPointMultiplyOpData, 715 * CpaCyEcPointMultiplyCbFunc 716 * 717 *****************************************************************************/ 718 CpaStatus CPA_DEPRECATED 719 cpaCyEcPointMultiply(const CpaInstanceHandle instanceHandle, 720 const CpaCyEcPointMultiplyCbFunc pCb, 721 void *pCallbackTag, 722 const CpaCyEcPointMultiplyOpData *pOpData, 723 CpaBoolean *pMultiplyStatus, 724 CpaFlatBuffer *pXk, 725 CpaFlatBuffer *pYk); 726 727 728 /** 729 ***************************************************************************** 730 * @ingroup cpaCyEc 731 * Verify that a point is on an elliptic curve. 732 * 733 * @deprecated 734 * This function is replaced with @ref cpaCyEcGenericPointVerify 735 * 736 * @description 737 * This function performs Elliptic Curve Point Verification, as per 738 * steps a, b and c of ANSI X9.62 Annex A.4.2. (To perform the final 739 * step d, the user can call @ref cpaCyEcPointMultiply.) 740 * 741 * This function checks if the specified point satisfies the 742 * Weierstrass equation for an Elliptic Curve. 743 * 744 * For GF(p): 745 * y^2 = (x^3 + ax + b) mod p 746 * For GF(2^m): 747 * y^2 + xy = x^3 + ax^2 + b mod p 748 * where p is the irreducible polynomial over GF(2^m) 749 * 750 * Use this function to verify a point is in the correct range and is 751 * NOT the point at infinity. 752 * 753 * @context 754 * When called as an asynchronous function it cannot sleep. It can be 755 * executed in a context that does not permit sleeping. 756 * When called as a synchronous function it may sleep. It MUST NOT be 757 * executed in a context that DOES NOT permit sleeping. 758 * @assumptions 759 * None 760 * @sideEffects 761 * None 762 * @blocking 763 * Yes when configured to operate in synchronous mode. 764 * @reentrant 765 * No 766 * @threadSafe 767 * Yes 768 * 769 * @param[in] instanceHandle Instance handle. 770 * @param[in] pCb Callback function pointer. If this is set to 771 * a NULL value the function will operate 772 * synchronously. 773 * @param[in] pCallbackTag User-supplied value to help identify request. 774 * @param[in] pOpData Structure containing all the data needed to 775 * perform the operation. The client code 776 * allocates the memory for this structure. This 777 * component takes ownership of the memory until 778 * it is returned in the callback. 779 * @param[out] pVerifyStatus In synchronous mode, set to CPA_FALSE if the 780 * point is NOT on the curve or at infinity. Set 781 * to CPA_TRUE if the point is on the curve. 782 * 783 * @retval CPA_STATUS_SUCCESS Function executed successfully. 784 * @retval CPA_STATUS_FAIL Function failed. 785 * @retval CPA_STATUS_RETRY Resubmit the request. 786 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 787 * @retval CPA_STATUS_RESOURCE Error related to system resources. 788 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 789 * the request. 790 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 791 * 792 * @pre 793 * The component has been initialized via cpaCyStartInstance function. 794 * @post 795 * None 796 * @note 797 * When pCb is non-NULL an asynchronous callback of type 798 * CpaCyEcPointVerifyCbFunc is generated in response to this function 799 * call. 800 * For optimal performance, data pointers SHOULD be 8-byte aligned. 801 * 802 * @see 803 * CpaCyEcPointVerifyOpData, 804 * CpaCyEcPointVerifyCbFunc 805 * 806 *****************************************************************************/ 807 CpaStatus CPA_DEPRECATED 808 cpaCyEcPointVerify(const CpaInstanceHandle instanceHandle, 809 const CpaCyEcPointVerifyCbFunc pCb, 810 void *pCallbackTag, 811 const CpaCyEcPointVerifyOpData *pOpData, 812 CpaBoolean *pVerifyStatus); 813 814 /** 815 ***************************************************************************** 816 * @ingroup cpaCyEc 817 * Generic ECC point multiplication operation. 818 * 819 * @description 820 * This is the generic ECC point multiplication operation, which is 821 * agnostic to the type of the curve used. 822 * 823 * @context 824 * 825 * @assumptions 826 * None 827 * @sideEffects 828 * None 829 * @blocking 830 * Yes when configured to operate in synchronous mode. 831 * @reentrant 832 * No 833 * @threadSafe 834 * Yes 835 * 836 * @param[in] instanceHandle Instance handle. 837 * @param[in] pCb Callback function pointer. If this is set 838 * to a NULL value, the function will operate 839 * synchronously. 840 * @param[in] pCallbackTag User-supplied value to help identify 841 * request. 842 * @param[in] pOpData Structure containing all the data needed to 843 * perform the operation. The client code 844 * allocates the memory for this structure. 845 * This component takes ownership of the 846 * memory until it is returned in the 847 * callback. 848 * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 849 * valid (CPA_TRUE) or the output is invalid 850 * (CPA_FALSE). 851 * 852 * @param[out] pXk Pointer to xk flat buffer. 853 * @param[out] pYk Pointer to yk flat buffer. 854 * 855 * @retval CPA_STATUS_SUCCESS Function executed successfully. 856 * @retval CPA_STATUS_FAIL Function failed. 857 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 858 * @retval CPA_STATUS_RESOURCE Error related to system resources. 859 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 860 * the request. 861 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 862 * 863 * @pre 864 * Component has been initialized. 865 * @post 866 * None 867 * @note 868 * When pCb is non-NULL an asynchronous callback of type 869 * CpaCyEcPointMultiplyCbFunc is generated in response to this function 870 * call. 871 * For optimal performance, data pointers SHOULD be 8-byte aligned. 872 * @see 873 * CpaCyEcPointMultiplyOpData, 874 * CpaCyEcPointMultiplyCbFunc 875 * CpaCyEcCurveType 876 * CpaCyEcCurveParameters 877 *****************************************************************************/ 878 CpaStatus 879 cpaCyEcGenericPointMultiply( 880 const CpaInstanceHandle instanceHandle, 881 const CpaCyEcPointMultiplyCbFunc pCb, 882 void *pCallbackTag, 883 const CpaCyEcGenericPointMultiplyOpData *pOpData, 884 CpaBoolean *pMultiplyStatus, 885 CpaFlatBuffer *pXk, 886 CpaFlatBuffer *pYk); 887 888 /** 889 ***************************************************************************** 890 * @ingroup cpaCyEc 891 * Generic ECC point verification operation. 892 * 893 * @description 894 * This is the generic ECC point verification operation, which is 895 * agnostic to the type of the curve used. 896 * 897 * @context 898 * 899 * @assumptions 900 * None 901 * @sideEffects 902 * None 903 * @blocking 904 * Yes when configured to operate in synchronous mode. 905 * @reentrant 906 * No 907 * @threadSafe 908 * Yes 909 * 910 * @param[in] instanceHandle Instance handle. 911 * @param[in] pCb Callback function pointer. If this is set 912 * to a NULL value the function will operate 913 * synchronously. 914 * @param[in] pCallbackTag User-supplied value to help identify 915 * request. 916 * @param[in] pOpData Structure containing all the data needed to 917 * perform the operation. The client code 918 * allocates the memory for this structure. 919 * This component takes ownership of the 920 * memory until it is returned in the 921 * callback. 922 * @param[out] pVerifyStatus In synchronous mode, the verification 923 * output is valid (CPA_TRUE) or the output is 924 * invalid (CPA_FALSE). 925 926 * @retval CPA_STATUS_SUCCESS Function executed successfully. 927 * @retval CPA_STATUS_FAIL Function failed. 928 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 929 * @retval CPA_STATUS_RESOURCE Error related to system resources. 930 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 931 * the request. 932 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 933 * 934 * @pre 935 * Component has been initialized. 936 * @post 937 * None 938 * @note 939 * When pCb is non-NULL an asynchronous callback of type 940 * CpaCyEcPointVerifyCbFunc is generated in response to this function call. 941 * For optimal performance, data pointers SHOULD be 8-byte aligned. 942 * @see 943 * CpaCyEcGenericPointVerifyOpData, 944 * CpaCyEcPointVerifyCbFunc 945 * CpaCyEcCurveType 946 * CpaCyEcCurveParameters 947 *****************************************************************************/ 948 CpaStatus 949 cpaCyEcGenericPointVerify ( 950 const CpaInstanceHandle instanceHandle, 951 const CpaCyEcPointVerifyCbFunc pCb, 952 void *pCallbackTag, 953 const CpaCyEcGenericPointVerifyOpData *pOpData, 954 CpaBoolean *pVerifyStatus); 955 956 /** 957 ***************************************************************************** 958 * @ingroup cpaCyEc 959 * Perform EC Point Multiplication on an Edwards or Montgomery curve as 960 * defined in RFC#7748. 961 * 962 * @description 963 * This function performs Elliptic Curve Point Multiplication as per 964 * RFC#7748 965 * 966 * @context 967 * When called as an asynchronous function it cannot sleep. It can be 968 * executed in a context that does not permit sleeping. 969 * When called as a synchronous function it may sleep. It MUST NOT be 970 * executed in a context that DOES NOT permit sleeping. 971 * @assumptions 972 * None 973 * @sideEffects 974 * None 975 * @blocking 976 * Yes when configured to operate in synchronous mode. 977 * @reentrant 978 * No 979 * @threadSafe 980 * Yes 981 * 982 * @param[in] instanceHandle Instance handle. 983 * @param[in] pCb Callback function pointer. If this is set to 984 * a NULL value the function will operate 985 * synchronously. 986 * @param[in] pCallbackTag User-supplied value to help identify request. 987 * @param[in] pOpData Structure containing all the data needed to 988 * perform the operation. The client code 989 * allocates the memory for this structure. This 990 * component takes ownership of the memory until 991 * it is returned in the callback. 992 * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 993 * valid (CPA_TRUE) or the output is invalid 994 * (CPA_FALSE). 995 * @param[out] pXk Pointer to xk flat buffer. 996 * @param[out] pYk Pointer to yk flat buffer. 997 * 998 * @retval CPA_STATUS_SUCCESS Function executed successfully. 999 * @retval CPA_STATUS_FAIL Function failed. 1000 * @retval CPA_STATUS_RETRY Resubmit the request. 1001 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 1002 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1003 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1004 * the request. 1005 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1006 * 1007 * @pre 1008 * The component has been initialized via cpaCyStartInstance function. 1009 * @post 1010 * None 1011 * @note 1012 * When pCb is non-NULL an asynchronous callback of type 1013 * CpaCyEcPointMultiplyCbFunc is generated in response to this function 1014 * call. 1015 * For optimal performance, data pointers SHOULD be 8-byte aligned. 1016 * 1017 * @see 1018 * CpaCyEcMontEdwdsPointMultiplyOpData, 1019 * CpaCyEcMontEdwdsPointMultiplyCbFunc 1020 * 1021 *****************************************************************************/ 1022 CpaStatus 1023 cpaCyEcMontEdwdsPointMultiply(const CpaInstanceHandle instanceHandle, 1024 const CpaCyEcPointMultiplyCbFunc pCb, 1025 void *pCallbackTag, 1026 const CpaCyEcMontEdwdsPointMultiplyOpData *pOpData, 1027 CpaBoolean *pMultiplyStatus, 1028 CpaFlatBuffer *pXk, 1029 CpaFlatBuffer *pYk); 1030 1031 /** 1032 ***************************************************************************** 1033 * @ingroup cpaCyEc 1034 * Query statistics for a specific EC instance. 1035 * 1036 * @description 1037 * This function will query a specific instance of the EC implementation 1038 * for statistics. The user MUST allocate the CpaCyEcStats64 structure 1039 * and pass the reference to that structure into this function call. This 1040 * function writes the statistic results into the passed in 1041 * CpaCyEcStats64 structure. 1042 * 1043 * Note: statistics returned by this function do not interrupt current data 1044 * processing and as such can be slightly out of sync with operations that 1045 * are in progress during the statistics retrieval process. 1046 * 1047 * @context 1048 * This is a synchronous function and it can sleep. It MUST NOT be 1049 * executed in a context that DOES NOT permit sleeping. 1050 * @assumptions 1051 * None 1052 * @sideEffects 1053 * None 1054 * @blocking 1055 * This function is synchronous and blocking. 1056 * @reentrant 1057 * No 1058 * @threadSafe 1059 * Yes 1060 * 1061 * @param[in] instanceHandle Instance handle. 1062 * @param[out] pEcStats Pointer to memory into which the statistics 1063 * will be written. 1064 * 1065 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1066 * @retval CPA_STATUS_FAIL Function failed. 1067 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1068 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1069 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1070 * the request. 1071 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1072 * 1073 * @pre 1074 * Component has been initialized. 1075 * @post 1076 * None 1077 * @note 1078 * This function operates in a synchronous manner and no asynchronous 1079 * callback will be generated. 1080 * @see 1081 * CpaCyEcStats64 1082 *****************************************************************************/ 1083 CpaStatus 1084 cpaCyEcQueryStats64(const CpaInstanceHandle instanceHandle, 1085 CpaCyEcStats64 *pEcStats); 1086 1087 #ifdef __cplusplus 1088 } /* close the extern "C" { */ 1089 #endif 1090 1091 #endif /*CPA_CY_EC_H_*/ 1092