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