178ee8d1cSJulian Grajkowski /*************************************************************************** 278ee8d1cSJulian Grajkowski * 378ee8d1cSJulian Grajkowski * BSD LICENSE 478ee8d1cSJulian Grajkowski * 5266b0663SKrzysztof Zdziarski * Copyright(c) 2007-2023 Intel Corporation. All rights reserved. 678ee8d1cSJulian Grajkowski * All rights reserved. 778ee8d1cSJulian Grajkowski * 878ee8d1cSJulian Grajkowski * Redistribution and use in source and binary forms, with or without 978ee8d1cSJulian Grajkowski * modification, are permitted provided that the following conditions 1078ee8d1cSJulian Grajkowski * are met: 1178ee8d1cSJulian Grajkowski * 1278ee8d1cSJulian Grajkowski * * Redistributions of source code must retain the above copyright 1378ee8d1cSJulian Grajkowski * notice, this list of conditions and the following disclaimer. 1478ee8d1cSJulian Grajkowski * * Redistributions in binary form must reproduce the above copyright 1578ee8d1cSJulian Grajkowski * notice, this list of conditions and the following disclaimer in 1678ee8d1cSJulian Grajkowski * the documentation and/or other materials provided with the 1778ee8d1cSJulian Grajkowski * distribution. 1878ee8d1cSJulian Grajkowski * * Neither the name of Intel Corporation nor the names of its 1978ee8d1cSJulian Grajkowski * contributors may be used to endorse or promote products derived 2078ee8d1cSJulian Grajkowski * from this software without specific prior written permission. 2178ee8d1cSJulian Grajkowski * 2278ee8d1cSJulian Grajkowski * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 2378ee8d1cSJulian Grajkowski * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2478ee8d1cSJulian Grajkowski * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 2578ee8d1cSJulian Grajkowski * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 2678ee8d1cSJulian Grajkowski * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 2778ee8d1cSJulian Grajkowski * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 2878ee8d1cSJulian Grajkowski * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 2978ee8d1cSJulian Grajkowski * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 3078ee8d1cSJulian Grajkowski * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 3178ee8d1cSJulian Grajkowski * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 3278ee8d1cSJulian Grajkowski * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3378ee8d1cSJulian Grajkowski * 3478ee8d1cSJulian Grajkowski * 3578ee8d1cSJulian Grajkowski ***************************************************************************/ 3678ee8d1cSJulian Grajkowski 3778ee8d1cSJulian Grajkowski /* 3878ee8d1cSJulian Grajkowski ***************************************************************************** 3978ee8d1cSJulian Grajkowski * Doxygen group definitions 4078ee8d1cSJulian Grajkowski ****************************************************************************/ 4178ee8d1cSJulian Grajkowski 4278ee8d1cSJulian Grajkowski /** 4378ee8d1cSJulian Grajkowski ***************************************************************************** 4478ee8d1cSJulian Grajkowski * @file cpa_cy_ec.h 4578ee8d1cSJulian Grajkowski * 4678ee8d1cSJulian Grajkowski * @defgroup cpaCyEc Elliptic Curve (EC) API 4778ee8d1cSJulian Grajkowski * 4878ee8d1cSJulian Grajkowski * @ingroup cpaCy 4978ee8d1cSJulian Grajkowski * 5078ee8d1cSJulian Grajkowski * @description 5178ee8d1cSJulian Grajkowski * These functions specify the API for Public Key Encryption 5278ee8d1cSJulian Grajkowski * (Cryptography) Elliptic Curve (EC) operations. 5378ee8d1cSJulian Grajkowski * 5478ee8d1cSJulian Grajkowski * All implementations will support at least the following: 5578ee8d1cSJulian Grajkowski * 5678ee8d1cSJulian Grajkowski * - "NIST RECOMMENDED ELLIPTIC CURVES FOR FEDERAL GOVERNMENT USE" 5778ee8d1cSJulian Grajkowski * as defined by 5878ee8d1cSJulian Grajkowski * http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf 5978ee8d1cSJulian Grajkowski * 6078ee8d1cSJulian Grajkowski * - Random curves where the max(log2(q), log2(n) + log2(h)) <= 512 6178ee8d1cSJulian Grajkowski * where q is the modulus, n is the order of the curve and h is the 6278ee8d1cSJulian Grajkowski * cofactor 6378ee8d1cSJulian Grajkowski * 6478ee8d1cSJulian Grajkowski * For Montgomery and Edwards 25519 and 448 elliptic curves, 6578ee8d1cSJulian Grajkowski * the following operations are supported: 6678ee8d1cSJulian Grajkowski * 1. Montgomery 25519 Curve | scalar point Multiplication 6778ee8d1cSJulian Grajkowski * Input: Montgomery affine coordinate X of point P 6878ee8d1cSJulian Grajkowski * Scalar k 69266b0663SKrzysztof Zdziarski * Output: Montgomery affine coordinate X of point [k]P 7078ee8d1cSJulian Grajkowski * Decode: Scalar k always decoded by implementation 7178ee8d1cSJulian Grajkowski * 7278ee8d1cSJulian Grajkowski * 2. Montgomery 25519 Curve | generator point Multiplication 7378ee8d1cSJulian Grajkowski * Input: Scalar k 7478ee8d1cSJulian Grajkowski * Output: Montgomery affine coordinate X of point [k]G 7578ee8d1cSJulian Grajkowski * Decode: Scalar k always decoded by implementation 7678ee8d1cSJulian Grajkowski * 7778ee8d1cSJulian Grajkowski * 3. Twisted Edwards 25519 Curve | scalar point Multiplication 7878ee8d1cSJulian Grajkowski * Input: Twisted Edwards affine coordinate X of point P 7978ee8d1cSJulian Grajkowski * Twisted Edwards affine coordinate Y of point P 8078ee8d1cSJulian Grajkowski * Scalar k 8178ee8d1cSJulian Grajkowski * Output: Twisted Edwards affine coordinate X of point [k]P 8278ee8d1cSJulian Grajkowski * Twisted Edwards affine coordinate Y of point [k]P 83266b0663SKrzysztof Zdziarski * Decode: Caller must supply parameters in MSB order, the 84266b0663SKrzysztof Zdziarski * implementation will not explicitly decode according 85266b0663SKrzysztof Zdziarski * to RFC#7748 Section 5 8678ee8d1cSJulian Grajkowski * 8778ee8d1cSJulian Grajkowski * 4. Twisted Edwards 25519 Curve | generator point Multiplication 8878ee8d1cSJulian Grajkowski * Input: Scalar k 8978ee8d1cSJulian Grajkowski * Output: Twisted Edwards affine coordinate X of point [k]G 9078ee8d1cSJulian Grajkowski * Twisted Edwards affine coordinate Y of point [k]G 91266b0663SKrzysztof Zdziarski * Decode: Caller must supply parameters in MSB order, the 92266b0663SKrzysztof Zdziarski * implementation will not explicitly decode according 93266b0663SKrzysztof Zdziarski * to RFC#7748 Section 5 9478ee8d1cSJulian Grajkowski * 9578ee8d1cSJulian Grajkowski * 5. Montgomery 448 Curve | scalar point Multiplication 9678ee8d1cSJulian Grajkowski * Input: Montgomery affine coordinate X of point P 9778ee8d1cSJulian Grajkowski * Scalar k 9878ee8d1cSJulian Grajkowski * Output: Montgomery affine coordinate X of point [k]P 9978ee8d1cSJulian Grajkowski * Decode: Scalar k always decoded by implementation 10078ee8d1cSJulian Grajkowski * 10178ee8d1cSJulian Grajkowski * 6. Montgomery 448 Curve | generator point Multiplication 10278ee8d1cSJulian Grajkowski * Input: Scalar k 10378ee8d1cSJulian Grajkowski * Output: Montgomery affine coordinate X of point [k]G 10478ee8d1cSJulian Grajkowski * Decode: Scalar k always decoded by implementation 10578ee8d1cSJulian Grajkowski * 10678ee8d1cSJulian Grajkowski * 7. Edwards 448 Curve | scalar point Multiplication 10778ee8d1cSJulian Grajkowski * Input: Edwards affine coordinate X of point P 10878ee8d1cSJulian Grajkowski * Edwards affine coordinate Y of point P 10978ee8d1cSJulian Grajkowski * Scalar k 11078ee8d1cSJulian Grajkowski * Output: Edwards affine coordinate X of point [k]P 11178ee8d1cSJulian Grajkowski * Edwards affine coordinate Y of point [k]P 112266b0663SKrzysztof Zdziarski * Decode: Caller must supply parameters in MSB order, the 113266b0663SKrzysztof Zdziarski * implementation will not explicitly decode according 114266b0663SKrzysztof Zdziarski * to RFC#7748 Section 5 11578ee8d1cSJulian Grajkowski * 11678ee8d1cSJulian Grajkowski * 8. Edwards 448 Curve | generator point Multiplication 11778ee8d1cSJulian Grajkowski * Input: Scalar k 11878ee8d1cSJulian Grajkowski * Output: Edwards affine coordinate X of point [k]G 11978ee8d1cSJulian Grajkowski * Edwards affine coordinate Y of point [k]G 120266b0663SKrzysztof Zdziarski * Decode: Caller must supply parameters in MSB order, the 121266b0663SKrzysztof Zdziarski * implementation will not explicitly decode according 122266b0663SKrzysztof Zdziarski * to RFC#7748 Section 5 12378ee8d1cSJulian Grajkowski * 12478ee8d1cSJulian Grajkowski * @note 12578ee8d1cSJulian Grajkowski * Large numbers are represented on the QuickAssist API as described 12678ee8d1cSJulian Grajkowski * in the Large Number API (@ref cpaCyLn). 12778ee8d1cSJulian Grajkowski * 12878ee8d1cSJulian Grajkowski * In addition, the bit length of large numbers passed to the API 12978ee8d1cSJulian Grajkowski * MUST NOT exceed 576 bits for Elliptic Curve operations. 13078ee8d1cSJulian Grajkowski *****************************************************************************/ 13178ee8d1cSJulian Grajkowski 13278ee8d1cSJulian Grajkowski #ifndef CPA_CY_EC_H_ 13378ee8d1cSJulian Grajkowski #define CPA_CY_EC_H_ 13478ee8d1cSJulian Grajkowski 13578ee8d1cSJulian Grajkowski #ifdef __cplusplus 13678ee8d1cSJulian Grajkowski extern "C" { 13778ee8d1cSJulian Grajkowski #endif 13878ee8d1cSJulian Grajkowski 13978ee8d1cSJulian Grajkowski #include "cpa_cy_common.h" 14078ee8d1cSJulian Grajkowski 14178ee8d1cSJulian Grajkowski /** 14278ee8d1cSJulian Grajkowski ***************************************************************************** 14378ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 14478ee8d1cSJulian Grajkowski * Field types for Elliptic Curve 14578ee8d1cSJulian Grajkowski 14678ee8d1cSJulian Grajkowski * @description 14778ee8d1cSJulian Grajkowski * As defined by FIPS-186-3, for each cryptovariable length, there are 14878ee8d1cSJulian Grajkowski * two kinds of fields. 14978ee8d1cSJulian Grajkowski * <ul> 15078ee8d1cSJulian Grajkowski * <li> A prime field is the field GF(p) which contains a prime number 15178ee8d1cSJulian Grajkowski * p of elements. The elements of this field are the integers modulo 15278ee8d1cSJulian Grajkowski * p, and the field arithmetic is implemented in terms of the 15378ee8d1cSJulian Grajkowski * arithmetic of integers modulo p.</li> 15478ee8d1cSJulian Grajkowski * 15578ee8d1cSJulian Grajkowski * <li> A binary field is the field GF(2^m) which contains 2^m elements 15678ee8d1cSJulian Grajkowski * for some m (called the degree of the field). The elements of 15778ee8d1cSJulian Grajkowski * this field are the bit strings of length m, and the field 15878ee8d1cSJulian Grajkowski * arithmetic is implemented in terms of operations on the bits.</li> 15978ee8d1cSJulian Grajkowski * </ul> 16078ee8d1cSJulian Grajkowski *****************************************************************************/ 16178ee8d1cSJulian Grajkowski typedef enum _CpaCyEcFieldType 16278ee8d1cSJulian Grajkowski { 16378ee8d1cSJulian Grajkowski CPA_CY_EC_FIELD_TYPE_PRIME = 1, 16478ee8d1cSJulian Grajkowski /**< A prime field, GF(p) */ 16578ee8d1cSJulian Grajkowski CPA_CY_EC_FIELD_TYPE_BINARY, 16678ee8d1cSJulian Grajkowski /**< A binary field, GF(2^m) */ 16778ee8d1cSJulian Grajkowski } CpaCyEcFieldType; 16878ee8d1cSJulian Grajkowski 16978ee8d1cSJulian Grajkowski /** 17078ee8d1cSJulian Grajkowski ***************************************************************************** 17178ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 172266b0663SKrzysztof Zdziarski * Enumeration listing curve types to use with generic multiplication 173266b0663SKrzysztof Zdziarski * and verification routines. 174266b0663SKrzysztof Zdziarski * 175266b0663SKrzysztof Zdziarski * @description 176266b0663SKrzysztof Zdziarski * This structure contains a list of different elliptic curve types. 177266b0663SKrzysztof Zdziarski * EC Point multiplication and other operations depend on the type of 178266b0663SKrzysztof Zdziarski * the curve. 179266b0663SKrzysztof Zdziarski * 180266b0663SKrzysztof Zdziarski * @see 181266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointMultiply() 182266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointVerify() 183266b0663SKrzysztof Zdziarski * 184266b0663SKrzysztof Zdziarski *****************************************************************************/ 185266b0663SKrzysztof Zdziarski typedef enum _CpaCyEcCurveType 186266b0663SKrzysztof Zdziarski { 187266b0663SKrzysztof Zdziarski CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_PRIME = 1, 188266b0663SKrzysztof Zdziarski /**< A Weierstrass curve with arithmetic in terms of the 189266b0663SKrzysztof Zdziarski * arithmetic of integers modulo p over a prime field. */ 190266b0663SKrzysztof Zdziarski CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_BINARY, 191266b0663SKrzysztof Zdziarski /**< A Weierstrass curve with arithmetic in terms of operations on bits 192266b0663SKrzysztof Zdziarski * over a binary field. */ 193266b0663SKrzysztof Zdziarski CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_KOBLITZ_BINARY, 194266b0663SKrzysztof Zdziarski /**< A Weierstrass-koblitz curve with arithmetic in terms of operations on 195266b0663SKrzysztof Zdziarski * the bits over a binary field. */ 196266b0663SKrzysztof Zdziarski } CpaCyEcCurveType; 197266b0663SKrzysztof Zdziarski 198266b0663SKrzysztof Zdziarski /** 199266b0663SKrzysztof Zdziarski ***************************************************************************** 200266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 20178ee8d1cSJulian Grajkowski * Curve types for Elliptic Curves defined in RFC#7748 20278ee8d1cSJulian Grajkowski 20378ee8d1cSJulian Grajkowski * @description 20478ee8d1cSJulian Grajkowski * As defined by RFC 7748, there are four elliptic curves in this 20578ee8d1cSJulian Grajkowski * group. The Montgomery curves are denoted curve25519 and curve448, 20678ee8d1cSJulian Grajkowski * and the birationally equivalent Twisted Edwards curves are denoted 20778ee8d1cSJulian Grajkowski * edwards25519 and edwards448 20878ee8d1cSJulian Grajkowski * 20978ee8d1cSJulian Grajkowski *****************************************************************************/ 21078ee8d1cSJulian Grajkowski typedef enum _CpaCyEcMontEdwdsCurveType 21178ee8d1cSJulian Grajkowski { 21278ee8d1cSJulian Grajkowski CPA_CY_EC_MONTEDWDS_CURVE25519_TYPE = 1, 21378ee8d1cSJulian Grajkowski /**< Montgomery 25519 curve */ 21478ee8d1cSJulian Grajkowski CPA_CY_EC_MONTEDWDS_ED25519_TYPE, 215266b0663SKrzysztof Zdziarski /**< Edwards 25519 curve */ 21678ee8d1cSJulian Grajkowski CPA_CY_EC_MONTEDWDS_CURVE448_TYPE, 21778ee8d1cSJulian Grajkowski /**< Montgomery 448 curve */ 21878ee8d1cSJulian Grajkowski CPA_CY_EC_MONTEDWDS_ED448_TYPE, 219266b0663SKrzysztof Zdziarski /**< Edwards 448 curve */ 22078ee8d1cSJulian Grajkowski } CpaCyEcMontEdwdsCurveType; 22178ee8d1cSJulian Grajkowski 22278ee8d1cSJulian Grajkowski /** 22378ee8d1cSJulian Grajkowski ***************************************************************************** 224266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 225266b0663SKrzysztof Zdziarski * Curve parameters for a Weierstrass type curve. 226266b0663SKrzysztof Zdziarski * 227266b0663SKrzysztof Zdziarski * @description 228266b0663SKrzysztof Zdziarski * This structure contains curve parameters for Weierstrass type 229266b0663SKrzysztof Zdziarski * curve: y^2 = x^3 + ax + b 230266b0663SKrzysztof Zdziarski * The client MUST allocate the memory for this structure 231266b0663SKrzysztof Zdziarski * When the structure is passed into the function, ownership of the memory 232266b0663SKrzysztof Zdziarski * passes to the function. Ownership of the memory returns to the client 233266b0663SKrzysztof Zdziarski * when this structure is returned in the callback function. 234266b0663SKrzysztof Zdziarski * 235266b0663SKrzysztof Zdziarski * For optimal performance all data buffers SHOULD be 8-byte aligned. 236266b0663SKrzysztof Zdziarski * The legend used in this structure is borrowed from RFC7748 237266b0663SKrzysztof Zdziarski * 238266b0663SKrzysztof Zdziarski * @note 239266b0663SKrzysztof Zdziarski * If the client modifies or frees the memory referenced in this 240266b0663SKrzysztof Zdziarski * structure after it has been submitted to the function, and before it 241266b0663SKrzysztof Zdziarski * has been returned in the callback, undefined behavior will result. 242266b0663SKrzysztof Zdziarski * 243266b0663SKrzysztof Zdziarski * @see 244266b0663SKrzysztof Zdziarski * CpaCyEcCurveParameters 245266b0663SKrzysztof Zdziarski * CpaCyEcFieldType 246266b0663SKrzysztof Zdziarski * 247266b0663SKrzysztof Zdziarski *****************************************************************************/ 248266b0663SKrzysztof Zdziarski typedef struct _CpaCyEcCurveParametersWeierstrass 249266b0663SKrzysztof Zdziarski { 250266b0663SKrzysztof Zdziarski CpaCyEcFieldType fieldType; 251266b0663SKrzysztof Zdziarski /**< Prime or Binary */ 252266b0663SKrzysztof Zdziarski CpaFlatBuffer p; 253266b0663SKrzysztof Zdziarski /**< Prime modulus or irreducible polynomial over GF(2^m) */ 254266b0663SKrzysztof Zdziarski CpaFlatBuffer a; 255266b0663SKrzysztof Zdziarski /**< a coefficient */ 256266b0663SKrzysztof Zdziarski CpaFlatBuffer b; 257266b0663SKrzysztof Zdziarski /**< b coefficient */ 258266b0663SKrzysztof Zdziarski CpaFlatBuffer h; 259266b0663SKrzysztof Zdziarski /**< Cofactor */ 260266b0663SKrzysztof Zdziarski } CpaCyEcCurveParametersWeierstrass; 261266b0663SKrzysztof Zdziarski 262266b0663SKrzysztof Zdziarski /** 263266b0663SKrzysztof Zdziarski ***************************************************************************** 264266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 265266b0663SKrzysztof Zdziarski * Union characterised by a specific curve. 266266b0663SKrzysztof Zdziarski * 267266b0663SKrzysztof Zdziarski * @description 268266b0663SKrzysztof Zdziarski * This union allows for the characterisation of different curve types 269266b0663SKrzysztof Zdziarski * encapsulted in one data type. The intention is that new curve types 270266b0663SKrzysztof Zdziarski * will be added in the future. 271266b0663SKrzysztof Zdziarski * 272266b0663SKrzysztof Zdziarski * @note 273266b0663SKrzysztof Zdziarski * 274266b0663SKrzysztof Zdziarski * @see 275266b0663SKrzysztof Zdziarski * CpaCyEcCurveParametersWeierstrass 276266b0663SKrzysztof Zdziarski * 277266b0663SKrzysztof Zdziarski *****************************************************************************/ 278266b0663SKrzysztof Zdziarski typedef union _CpaCyEcCurveParameters 279266b0663SKrzysztof Zdziarski { 280266b0663SKrzysztof Zdziarski CpaCyEcCurveParametersWeierstrass weierstrassParameters; 281266b0663SKrzysztof Zdziarski } CpaCyEcCurveParameters; 282266b0663SKrzysztof Zdziarski 283266b0663SKrzysztof Zdziarski /** 284266b0663SKrzysztof Zdziarski ***************************************************************************** 285266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 286266b0663SKrzysztof Zdziarski * Unified curve parameters. 287266b0663SKrzysztof Zdziarski * 288266b0663SKrzysztof Zdziarski * @description 289266b0663SKrzysztof Zdziarski * This structure provides a single data type that can describe a number 290266b0663SKrzysztof Zdziarski * of different curve types. The intention is to add further 291266b0663SKrzysztof Zdziarski * curve types in the future, thus the union field will allow for that 292266b0663SKrzysztof Zdziarski * expansion. 293266b0663SKrzysztof Zdziarski * 294266b0663SKrzysztof Zdziarski * The client MUST allocate the memory for this structure and the 295266b0663SKrzysztof Zdziarski * items pointed to by this structure. When the structure is passed into 296266b0663SKrzysztof Zdziarski * the function, ownership of the memory passes to the function. Ownership 297266b0663SKrzysztof Zdziarski * of the memory returns to the client when this structure is returned in 298266b0663SKrzysztof Zdziarski * the callback function. 299266b0663SKrzysztof Zdziarski * 300266b0663SKrzysztof Zdziarski * For optimal performance all data buffers SHOULD be 8-byte aligned. 301266b0663SKrzysztof Zdziarski * 302266b0663SKrzysztof Zdziarski * @note 303266b0663SKrzysztof Zdziarski * If the client modifies or frees the memory referenced in this 304266b0663SKrzysztof Zdziarski * structure after it has been submitted to the function, and before it 305266b0663SKrzysztof Zdziarski * has been returned in the callback, undefined behavior will result. 306266b0663SKrzysztof Zdziarski * 307266b0663SKrzysztof Zdziarski * @see 308266b0663SKrzysztof Zdziarski * CpaCyEcCurveParameters 309266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointMultiply 310266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointVerify 311266b0663SKrzysztof Zdziarski * 312266b0663SKrzysztof Zdziarski *****************************************************************************/ 313266b0663SKrzysztof Zdziarski typedef struct _CpaCyEcCurve 314266b0663SKrzysztof Zdziarski { 315266b0663SKrzysztof Zdziarski CpaCyEcCurveType curveType; 316266b0663SKrzysztof Zdziarski CpaCyEcCurveParameters parameters; 317266b0663SKrzysztof Zdziarski } CpaCyEcCurve; 318266b0663SKrzysztof Zdziarski 319266b0663SKrzysztof Zdziarski /** 320266b0663SKrzysztof Zdziarski ***************************************************************************** 32178ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 32278ee8d1cSJulian Grajkowski * EC Point Multiplication Operation Data. 32378ee8d1cSJulian Grajkowski * 32478ee8d1cSJulian Grajkowski * @description 32578ee8d1cSJulian Grajkowski * This structure contains the operation data for the cpaCyEcPointMultiply 32678ee8d1cSJulian Grajkowski * function. The client MUST allocate the memory for this structure and the 32778ee8d1cSJulian Grajkowski * items pointed to by this structure. When the structure is passed into 32878ee8d1cSJulian Grajkowski * the function, ownership of the memory passes to the function. Ownership 32978ee8d1cSJulian Grajkowski * of the memory returns to the client when this structure is returned in 33078ee8d1cSJulian Grajkowski * the callback function. 33178ee8d1cSJulian Grajkowski * 33278ee8d1cSJulian Grajkowski * For optimal performance all data buffers SHOULD be 8-byte aligned. 33378ee8d1cSJulian Grajkowski * 33478ee8d1cSJulian Grajkowski * All values in this structure are required to be in Most Significant Byte 33578ee8d1cSJulian Grajkowski * first order, e.g. a.pData[0] = MSB. 33678ee8d1cSJulian Grajkowski * 33778ee8d1cSJulian Grajkowski * @note 33878ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this 33978ee8d1cSJulian Grajkowski * structure after it has been submitted to the cpaCyEcPointMultiply 34078ee8d1cSJulian Grajkowski * function, and before it has been returned in the callback, undefined 34178ee8d1cSJulian Grajkowski * behavior will result. 34278ee8d1cSJulian Grajkowski * 34378ee8d1cSJulian Grajkowski * @see 34478ee8d1cSJulian Grajkowski * cpaCyEcPointMultiply() 34578ee8d1cSJulian Grajkowski * 34678ee8d1cSJulian Grajkowski *****************************************************************************/ 34778ee8d1cSJulian Grajkowski typedef struct _CpaCyEcPointMultiplyOpData { 34878ee8d1cSJulian Grajkowski CpaFlatBuffer k; 34978ee8d1cSJulian Grajkowski /**< scalar multiplier (k > 0 and k < n) */ 35078ee8d1cSJulian Grajkowski CpaFlatBuffer xg; 35178ee8d1cSJulian Grajkowski /**< x coordinate of curve point */ 35278ee8d1cSJulian Grajkowski CpaFlatBuffer yg; 35378ee8d1cSJulian Grajkowski /**< y coordinate of curve point */ 35478ee8d1cSJulian Grajkowski CpaFlatBuffer a; 35578ee8d1cSJulian Grajkowski /**< a elliptic curve coefficient */ 35678ee8d1cSJulian Grajkowski CpaFlatBuffer b; 35778ee8d1cSJulian Grajkowski /**< b elliptic curve coefficient */ 35878ee8d1cSJulian Grajkowski CpaFlatBuffer q; 35978ee8d1cSJulian Grajkowski /**< prime modulus or irreducible polynomial over GF(2^m)*/ 36078ee8d1cSJulian Grajkowski CpaFlatBuffer h; 36178ee8d1cSJulian Grajkowski /**< cofactor of the operation. 36278ee8d1cSJulian Grajkowski * If the cofactor is NOT required then set the cofactor to 1 or the 36378ee8d1cSJulian Grajkowski * data pointer of the Flat Buffer to NULL. */ 36478ee8d1cSJulian Grajkowski CpaCyEcFieldType fieldType; 36578ee8d1cSJulian Grajkowski /**< field type for the operation */ 366266b0663SKrzysztof Zdziarski } CpaCyEcPointMultiplyOpData CPA_DEPRECATED; 36778ee8d1cSJulian Grajkowski 368266b0663SKrzysztof Zdziarski /** 369266b0663SKrzysztof Zdziarski ***************************************************************************** 370266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 371266b0663SKrzysztof Zdziarski * Generic EC Point Multiplication Operation Data. 372266b0663SKrzysztof Zdziarski * 373266b0663SKrzysztof Zdziarski * @description 374266b0663SKrzysztof Zdziarski * This structure contains a generic EC point and a multiplier for use with 375266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointMultiply. This is common for representing all EC 376266b0663SKrzysztof Zdziarski * points, irrespective of curve type: Weierstrass, Montgomery and Twisted 377266b0663SKrzysztof Zdziarski * Edwards (at this time only Weierstrass are supported). The same 378266b0663SKrzysztof Zdziarski * point + multiplier format can be used when performing generator 379266b0663SKrzysztof Zdziarski * multiplication, in which case the xP, yP supplied in this structure will 380266b0663SKrzysztof Zdziarski * be ignored by QAT API library & a generator point will be inserted in 381266b0663SKrzysztof Zdziarski * their place. 382266b0663SKrzysztof Zdziarski * 383266b0663SKrzysztof Zdziarski * For optimal performance all data buffers SHOULD be 8-byte aligned. 384266b0663SKrzysztof Zdziarski * 385266b0663SKrzysztof Zdziarski * All values in this structure are required to be in Most Significant Byte 386266b0663SKrzysztof Zdziarski * first order, e.g. a.pData[0] = MSB. 387266b0663SKrzysztof Zdziarski * 388266b0663SKrzysztof Zdziarski * @note 389266b0663SKrzysztof Zdziarski * If the client modifies or frees the memory referenced in this 390266b0663SKrzysztof Zdziarski * structure after it has been submitted to the cpaCyEcGenericPointMultiply 391266b0663SKrzysztof Zdziarski * function, and before it has been returned in the callback, undefined 392266b0663SKrzysztof Zdziarski * behavior will result. 393266b0663SKrzysztof Zdziarski * 394266b0663SKrzysztof Zdziarski * @see 395266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointMultiply() 396266b0663SKrzysztof Zdziarski * 397266b0663SKrzysztof Zdziarski *****************************************************************************/ 398266b0663SKrzysztof Zdziarski typedef struct _CpaCyEcGenericPointMultiplyOpData { 399266b0663SKrzysztof Zdziarski CpaFlatBuffer k; 400266b0663SKrzysztof Zdziarski /** <scalar multiplier (k > 0 and k < n) */ 401266b0663SKrzysztof Zdziarski CpaFlatBuffer xP; 402266b0663SKrzysztof Zdziarski /** <x coordinate of public key */ 403266b0663SKrzysztof Zdziarski CpaFlatBuffer yP; 404266b0663SKrzysztof Zdziarski /** <y coordinate of public key */ 405266b0663SKrzysztof Zdziarski CpaCyEcCurve *pCurve; 406266b0663SKrzysztof Zdziarski /** <curve type specific parameters */ 407266b0663SKrzysztof Zdziarski CpaBoolean generator; 408266b0663SKrzysztof Zdziarski /** <if TRUE xP and yP are the generator points */ 409266b0663SKrzysztof Zdziarski } CpaCyEcGenericPointMultiplyOpData; 410266b0663SKrzysztof Zdziarski 411266b0663SKrzysztof Zdziarski /** 412266b0663SKrzysztof Zdziarski ***************************************************************************** 413266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 414266b0663SKrzysztof Zdziarski * Generic EC Point Verify Operation Data. 415266b0663SKrzysztof Zdziarski * 416266b0663SKrzysztof Zdziarski * @description 417266b0663SKrzysztof Zdziarski * This structure contains the operation data for the 418266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointVerify function. This is common for representing 419266b0663SKrzysztof Zdziarski * all EC points, irrespective of curve type: Weierstrass, Montgomery and 420266b0663SKrzysztof Zdziarski * Twisted Edwards (at this time only Weierstrass are supported). 421266b0663SKrzysztof Zdziarski * 422266b0663SKrzysztof Zdziarski * This structure contains a generic EC point, irrespective of curve type. 423266b0663SKrzysztof Zdziarski * It is used to verify when the <x,y> pair specified in the structure 424266b0663SKrzysztof Zdziarski * lies on the curve indicated in the cpaCyEcGenericPointVerify API. 425266b0663SKrzysztof Zdziarski * 426266b0663SKrzysztof Zdziarski * For optimal performance all data buffers SHOULD be 8-byte aligned. 427266b0663SKrzysztof Zdziarski * 428266b0663SKrzysztof Zdziarski * All values in this structure are required to be in Most Significant Byte 429266b0663SKrzysztof Zdziarski * first order, e.g. a.pData[0] = MSB. 430266b0663SKrzysztof Zdziarski * 431266b0663SKrzysztof Zdziarski * @note 432266b0663SKrzysztof Zdziarski * If the client modifies or frees the memory referenced in this 433266b0663SKrzysztof Zdziarski * structure after it has been submitted to the cpaCyEcGenericPointVerify 434266b0663SKrzysztof Zdziarski * function, and before it has been returned in the callback, undefined 435266b0663SKrzysztof Zdziarski * behavior will result. 436266b0663SKrzysztof Zdziarski * 437266b0663SKrzysztof Zdziarski * @see 438266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointVerify() 439266b0663SKrzysztof Zdziarski * 440266b0663SKrzysztof Zdziarski *****************************************************************************/ 441266b0663SKrzysztof Zdziarski typedef struct _CpaCyEcGenericPointVerifyOpData { 442266b0663SKrzysztof Zdziarski CpaFlatBuffer xP; 443266b0663SKrzysztof Zdziarski /** <x coordinate of public key */ 444266b0663SKrzysztof Zdziarski CpaFlatBuffer yP; 445266b0663SKrzysztof Zdziarski /** <y coordinate of public key */ 446266b0663SKrzysztof Zdziarski CpaCyEcCurve *pCurve; 447266b0663SKrzysztof Zdziarski /** <curve type specific parameters */ 448266b0663SKrzysztof Zdziarski } CpaCyEcGenericPointVerifyOpData; 449266b0663SKrzysztof Zdziarski 450266b0663SKrzysztof Zdziarski /** 451266b0663SKrzysztof Zdziarski ***************************************************************************** 452266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 453266b0663SKrzysztof Zdziarski * EC Point Multiplication Operation Data for Edwards or 454266b0663SKrzysztof Zdziarski * Montgomery curves as specificied in RFC#7748. 455266b0663SKrzysztof Zdziarski * 456266b0663SKrzysztof Zdziarski * @description 457266b0663SKrzysztof Zdziarski * This structure contains the operation data for the 458266b0663SKrzysztof Zdziarski * cpaCyEcMontEdwdsPointMultiply function. 459266b0663SKrzysztof Zdziarski * The client MUST allocate the memory for this structure and the 460266b0663SKrzysztof Zdziarski * items pointed to by this structure. When the structure is passed into 461266b0663SKrzysztof Zdziarski * the function, ownership of the memory passes to the function. Ownership 462266b0663SKrzysztof Zdziarski * of the memory returns to the client when this structure is returned in 463266b0663SKrzysztof Zdziarski * the callback function. 464266b0663SKrzysztof Zdziarski * 465266b0663SKrzysztof Zdziarski * For optimal performance all data buffers SHOULD be 8-byte aligned. 466266b0663SKrzysztof Zdziarski * 467266b0663SKrzysztof Zdziarski * All values in this structure are required to be in Most Significant Byte 468266b0663SKrzysztof Zdziarski * first order, e.g. a.pData[0] = MSB. 469266b0663SKrzysztof Zdziarski * 470266b0663SKrzysztof Zdziarski * @note 471266b0663SKrzysztof Zdziarski * If the client modifies or frees the memory referenced in this 472266b0663SKrzysztof Zdziarski * structure after it has been submitted to the 473266b0663SKrzysztof Zdziarski * cpaCyEcMontEdwdsPointMultiply function, and before it has been returned 474266b0663SKrzysztof Zdziarski * in the callback, undefined behavior will result. 475266b0663SKrzysztof Zdziarski * 476266b0663SKrzysztof Zdziarski * All buffers in this structure need to be: 477266b0663SKrzysztof Zdziarski * - 32 bytes in size for 25519 curves 478266b0663SKrzysztof Zdziarski * - 64 bytes in size for 448 curves 479266b0663SKrzysztof Zdziarski * 480266b0663SKrzysztof Zdziarski * @see 481266b0663SKrzysztof Zdziarski * cpaCyEcMontEdwdsPointMultiply() 482266b0663SKrzysztof Zdziarski * 483266b0663SKrzysztof Zdziarski *****************************************************************************/ 484266b0663SKrzysztof Zdziarski typedef struct _CpaCyEcMontEdwdsPointMultiplyOpData { 485266b0663SKrzysztof Zdziarski CpaCyEcMontEdwdsCurveType curveType; 486266b0663SKrzysztof Zdziarski /**< field type for the operation */ 487266b0663SKrzysztof Zdziarski CpaBoolean generator; 488266b0663SKrzysztof Zdziarski /**< True if the operation is a generator multiplication (kG) 489266b0663SKrzysztof Zdziarski * False if it is a variable point multiplcation (kP). */ 490266b0663SKrzysztof Zdziarski CpaFlatBuffer k; 491266b0663SKrzysztof Zdziarski /**< k scalar multiplier for the operation */ 492266b0663SKrzysztof Zdziarski CpaFlatBuffer x; 493266b0663SKrzysztof Zdziarski /**< x value. Used in scalar varable point multiplication operations. 494266b0663SKrzysztof Zdziarski * Not required if the generator is True. Must be NULL if not required. 495266b0663SKrzysztof Zdziarski * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 496266b0663SKrzysztof Zdziarski * curves */ 497266b0663SKrzysztof Zdziarski CpaFlatBuffer y; 498266b0663SKrzysztof Zdziarski /**< y value. Used in variable point multiplication of operations. 499266b0663SKrzysztof Zdziarski * Not required if the generator is True. 500266b0663SKrzysztof Zdziarski * Must be NULL if not required. 501266b0663SKrzysztof Zdziarski * The size of the buffer MUST be 32B for 25519 curves and 64B for 448 502266b0663SKrzysztof Zdziarski * curves */ 503266b0663SKrzysztof Zdziarski } CpaCyEcMontEdwdsPointMultiplyOpData; 50478ee8d1cSJulian Grajkowski 50578ee8d1cSJulian Grajkowski /** 50678ee8d1cSJulian Grajkowski ***************************************************************************** 50778ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 50878ee8d1cSJulian Grajkowski * EC Point Verification Operation Data. 50978ee8d1cSJulian Grajkowski * 51078ee8d1cSJulian Grajkowski * @description 51178ee8d1cSJulian Grajkowski * This structure contains the operation data for the cpaCyEcPointVerify 51278ee8d1cSJulian Grajkowski * function. The client MUST allocate the memory for this structure and the 51378ee8d1cSJulian Grajkowski * items pointed to by this structure. When the structure is passed into 51478ee8d1cSJulian Grajkowski * the function, ownership of the memory passes to the function. Ownership 51578ee8d1cSJulian Grajkowski * of the memory returns to the client when this structure is returned in 51678ee8d1cSJulian Grajkowski * the callback function. 51778ee8d1cSJulian Grajkowski * 51878ee8d1cSJulian Grajkowski * For optimal performance all data buffers SHOULD be 8-byte aligned. 51978ee8d1cSJulian Grajkowski * 52078ee8d1cSJulian Grajkowski * All values in this structure are required to be in Most Significant Byte 52178ee8d1cSJulian Grajkowski * first order, e.g. a.pData[0] = MSB. 52278ee8d1cSJulian Grajkowski * 52378ee8d1cSJulian Grajkowski * @note 52478ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this 52578ee8d1cSJulian Grajkowski * structure after it has been submitted to the CpaCyEcPointVerify 52678ee8d1cSJulian Grajkowski * function, and before it has been returned in the callback, undefined 52778ee8d1cSJulian Grajkowski * behavior will result. 52878ee8d1cSJulian Grajkowski * 52978ee8d1cSJulian Grajkowski * @see 53078ee8d1cSJulian Grajkowski * cpaCyEcPointVerify() 53178ee8d1cSJulian Grajkowski * 53278ee8d1cSJulian Grajkowski *****************************************************************************/ 53378ee8d1cSJulian Grajkowski typedef struct _CpaCyEcPointVerifyOpData { 53478ee8d1cSJulian Grajkowski CpaFlatBuffer xq; 53578ee8d1cSJulian Grajkowski /**< x coordinate candidate point */ 53678ee8d1cSJulian Grajkowski CpaFlatBuffer yq; 53778ee8d1cSJulian Grajkowski /**< y coordinate candidate point */ 53878ee8d1cSJulian Grajkowski CpaFlatBuffer q; 53978ee8d1cSJulian Grajkowski /**< prime modulus or irreducible polynomial over GF(2^m) */ 54078ee8d1cSJulian Grajkowski CpaFlatBuffer a; 54178ee8d1cSJulian Grajkowski /**< a elliptic curve coefficient */ 54278ee8d1cSJulian Grajkowski CpaFlatBuffer b; 54378ee8d1cSJulian Grajkowski /**< b elliptic curve coefficient */ 54478ee8d1cSJulian Grajkowski CpaCyEcFieldType fieldType; 54578ee8d1cSJulian Grajkowski /**< field type for the operation */ 546266b0663SKrzysztof Zdziarski } CpaCyEcPointVerifyOpData CPA_DEPRECATED; 54778ee8d1cSJulian Grajkowski 54878ee8d1cSJulian Grajkowski /** 54978ee8d1cSJulian Grajkowski ***************************************************************************** 55078ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 55178ee8d1cSJulian Grajkowski * Cryptographic EC Statistics. 55278ee8d1cSJulian Grajkowski * 55378ee8d1cSJulian Grajkowski * @description 55478ee8d1cSJulian Grajkowski * This structure contains statistics on the Cryptographic EC 55578ee8d1cSJulian Grajkowski * operations. Statistics are set to zero when the component is 55678ee8d1cSJulian Grajkowski * initialized, and are collected per instance. 55778ee8d1cSJulian Grajkowski * 55878ee8d1cSJulian Grajkowski ****************************************************************************/ 55978ee8d1cSJulian Grajkowski typedef struct _CpaCyEcStats64 { 56078ee8d1cSJulian Grajkowski Cpa64U numEcPointMultiplyRequests; 56178ee8d1cSJulian Grajkowski /**< Total number of EC Point Multiplication operation requests. */ 56278ee8d1cSJulian Grajkowski Cpa64U numEcPointMultiplyRequestErrors; 56378ee8d1cSJulian Grajkowski /**< Total number of EC Point Multiplication operation requests that had an 56478ee8d1cSJulian Grajkowski * error and could not be processed. */ 56578ee8d1cSJulian Grajkowski Cpa64U numEcPointMultiplyCompleted; 56678ee8d1cSJulian Grajkowski /**< Total number of EC Point Multiplication operation requests that 56778ee8d1cSJulian Grajkowski * completed successfully. */ 56878ee8d1cSJulian Grajkowski Cpa64U numEcPointMultiplyCompletedError; 56978ee8d1cSJulian Grajkowski /**< Total number of EC Point Multiplication operation requests that could 57078ee8d1cSJulian Grajkowski * not be completed successfully due to errors. */ 57178ee8d1cSJulian Grajkowski Cpa64U numEcPointMultiplyCompletedOutputInvalid; 57278ee8d1cSJulian Grajkowski /**< Total number of EC Point Multiplication operation requests that could 57378ee8d1cSJulian Grajkowski * not be completed successfully due to an invalid output. 57478ee8d1cSJulian Grajkowski * Note that this does not indicate an error. */ 57578ee8d1cSJulian Grajkowski Cpa64U numEcPointVerifyRequests; 57678ee8d1cSJulian Grajkowski /**< Total number of EC Point Verification operation requests. */ 57778ee8d1cSJulian Grajkowski Cpa64U numEcPointVerifyRequestErrors; 57878ee8d1cSJulian Grajkowski /**< Total number of EC Point Verification operation requests that had an 57978ee8d1cSJulian Grajkowski * error and could not be processed. */ 58078ee8d1cSJulian Grajkowski Cpa64U numEcPointVerifyCompleted; 58178ee8d1cSJulian Grajkowski /**< Total number of EC Point Verification operation requests that completed 58278ee8d1cSJulian Grajkowski * successfully. */ 58378ee8d1cSJulian Grajkowski Cpa64U numEcPointVerifyCompletedErrors; 58478ee8d1cSJulian Grajkowski /**< Total number of EC Point Verification operation requests that could 58578ee8d1cSJulian Grajkowski * not be completed successfully due to errors. */ 58678ee8d1cSJulian Grajkowski Cpa64U numEcPointVerifyCompletedOutputInvalid; 58778ee8d1cSJulian Grajkowski /**< Total number of EC Point Verification operation requests that had an 58878ee8d1cSJulian Grajkowski * invalid output. Note that this does not indicate an error. */ 58978ee8d1cSJulian Grajkowski } CpaCyEcStats64; 59078ee8d1cSJulian Grajkowski 59178ee8d1cSJulian Grajkowski 59278ee8d1cSJulian Grajkowski /** 59378ee8d1cSJulian Grajkowski ***************************************************************************** 59478ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 59578ee8d1cSJulian Grajkowski * Definition of callback function invoked for cpaCyEcPointMultiply 59678ee8d1cSJulian Grajkowski * requests. 59778ee8d1cSJulian Grajkowski * @context 59878ee8d1cSJulian Grajkowski * This callback function can be executed in a context that DOES NOT 59978ee8d1cSJulian Grajkowski * permit sleeping to occur. 60078ee8d1cSJulian Grajkowski * @assumptions 60178ee8d1cSJulian Grajkowski * None 60278ee8d1cSJulian Grajkowski * @sideEffects 60378ee8d1cSJulian Grajkowski * None 60478ee8d1cSJulian Grajkowski * @reentrant 60578ee8d1cSJulian Grajkowski * No 60678ee8d1cSJulian Grajkowski * @threadSafe 60778ee8d1cSJulian Grajkowski * Yes 60878ee8d1cSJulian Grajkowski * 60978ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 61078ee8d1cSJulian Grajkowski * @param[in] status Status of the operation. Valid values are 61178ee8d1cSJulian Grajkowski * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 61278ee8d1cSJulian Grajkowski * CPA_STATUS_UNSUPPORTED. 61378ee8d1cSJulian Grajkowski * @param[in] pOpData Opaque pointer to Operation data supplied in 61478ee8d1cSJulian Grajkowski * request. 61578ee8d1cSJulian Grajkowski * @param[in] multiplyStatus Status of the point multiplication. 61678ee8d1cSJulian Grajkowski * @param[in] pXk x coordinate of resultant EC point. 61778ee8d1cSJulian Grajkowski * @param[in] pYk y coordinate of resultant EC point. 61878ee8d1cSJulian Grajkowski * 61978ee8d1cSJulian Grajkowski * @retval 62078ee8d1cSJulian Grajkowski * None 62178ee8d1cSJulian Grajkowski * @pre 62278ee8d1cSJulian Grajkowski * Component has been initialized. 62378ee8d1cSJulian Grajkowski * @post 62478ee8d1cSJulian Grajkowski * None 62578ee8d1cSJulian Grajkowski * @note 62678ee8d1cSJulian Grajkowski * None 62778ee8d1cSJulian Grajkowski * @see 628266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointMultiply() 62978ee8d1cSJulian Grajkowski * 63078ee8d1cSJulian Grajkowski *****************************************************************************/ 63178ee8d1cSJulian Grajkowski typedef void (*CpaCyEcPointMultiplyCbFunc)(void *pCallbackTag, 63278ee8d1cSJulian Grajkowski CpaStatus status, 63378ee8d1cSJulian Grajkowski void *pOpData, 63478ee8d1cSJulian Grajkowski CpaBoolean multiplyStatus, 63578ee8d1cSJulian Grajkowski CpaFlatBuffer *pXk, 63678ee8d1cSJulian Grajkowski CpaFlatBuffer *pYk); 63778ee8d1cSJulian Grajkowski 63878ee8d1cSJulian Grajkowski 63978ee8d1cSJulian Grajkowski /** 64078ee8d1cSJulian Grajkowski ***************************************************************************** 64178ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 642266b0663SKrzysztof Zdziarski * Definition of callback function invoked for cpaCyEcGenericPointVerify 64378ee8d1cSJulian Grajkowski * requests. 64478ee8d1cSJulian Grajkowski * @context 64578ee8d1cSJulian Grajkowski * This callback function can be executed in a context that DOES NOT 64678ee8d1cSJulian Grajkowski * permit sleeping to occur. 64778ee8d1cSJulian Grajkowski * @assumptions 64878ee8d1cSJulian Grajkowski * None 64978ee8d1cSJulian Grajkowski * @sideEffects 65078ee8d1cSJulian Grajkowski * None 65178ee8d1cSJulian Grajkowski * @reentrant 65278ee8d1cSJulian Grajkowski * No 65378ee8d1cSJulian Grajkowski * @threadSafe 65478ee8d1cSJulian Grajkowski * Yes 65578ee8d1cSJulian Grajkowski * 65678ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 65778ee8d1cSJulian Grajkowski * @param[in] status Status of the operation. Valid values are 65878ee8d1cSJulian Grajkowski * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 65978ee8d1cSJulian Grajkowski * CPA_STATUS_UNSUPPORTED. 66078ee8d1cSJulian Grajkowski * @param[in] pOpData Operation data pointer supplied in request. 66178ee8d1cSJulian Grajkowski * @param[in] verifyStatus Set to CPA_FALSE if the point is NOT on the 66278ee8d1cSJulian Grajkowski * curve or at infinity. Set to CPA_TRUE if the 66378ee8d1cSJulian Grajkowski * point is on the curve. 66478ee8d1cSJulian Grajkowski * 66578ee8d1cSJulian Grajkowski * @return 66678ee8d1cSJulian Grajkowski * None 66778ee8d1cSJulian Grajkowski * @pre 66878ee8d1cSJulian Grajkowski * Component has been initialized. 66978ee8d1cSJulian Grajkowski * @post 67078ee8d1cSJulian Grajkowski * None 67178ee8d1cSJulian Grajkowski * @note 67278ee8d1cSJulian Grajkowski * None 67378ee8d1cSJulian Grajkowski * @see 674266b0663SKrzysztof Zdziarski * cpaCyEcGenericPointVerify() 67578ee8d1cSJulian Grajkowski * 67678ee8d1cSJulian Grajkowski *****************************************************************************/ 67778ee8d1cSJulian Grajkowski typedef void (*CpaCyEcPointVerifyCbFunc)(void *pCallbackTag, 67878ee8d1cSJulian Grajkowski CpaStatus status, 67978ee8d1cSJulian Grajkowski void *pOpData, 68078ee8d1cSJulian Grajkowski CpaBoolean verifyStatus); 68178ee8d1cSJulian Grajkowski 68278ee8d1cSJulian Grajkowski 68378ee8d1cSJulian Grajkowski /** 68478ee8d1cSJulian Grajkowski ***************************************************************************** 68578ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 68678ee8d1cSJulian Grajkowski * Perform EC Point Multiplication. 68778ee8d1cSJulian Grajkowski * 688266b0663SKrzysztof Zdziarski * @deprecated 689266b0663SKrzysztof Zdziarski * This function is replaced with @ref cpaCyEcGenericPointMultiply 690266b0663SKrzysztof Zdziarski * 69178ee8d1cSJulian Grajkowski * @description 69278ee8d1cSJulian Grajkowski * This function performs Elliptic Curve Point Multiplication as per 69378ee8d1cSJulian Grajkowski * ANSI X9.63 Annex D.3.2. 69478ee8d1cSJulian Grajkowski * 69578ee8d1cSJulian Grajkowski * @context 69678ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 69778ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 69878ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 69978ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 70078ee8d1cSJulian Grajkowski * @assumptions 70178ee8d1cSJulian Grajkowski * None 70278ee8d1cSJulian Grajkowski * @sideEffects 70378ee8d1cSJulian Grajkowski * None 70478ee8d1cSJulian Grajkowski * @blocking 70578ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 70678ee8d1cSJulian Grajkowski * @reentrant 70778ee8d1cSJulian Grajkowski * No 70878ee8d1cSJulian Grajkowski * @threadSafe 70978ee8d1cSJulian Grajkowski * Yes 71078ee8d1cSJulian Grajkowski * 71178ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 71278ee8d1cSJulian Grajkowski * @param[in] pCb Callback function pointer. If this is set to 71378ee8d1cSJulian Grajkowski * a NULL value the function will operate 71478ee8d1cSJulian Grajkowski * synchronously. 71578ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 71678ee8d1cSJulian Grajkowski * @param[in] pOpData Structure containing all the data needed to 71778ee8d1cSJulian Grajkowski * perform the operation. The client code 71878ee8d1cSJulian Grajkowski * allocates the memory for this structure. This 71978ee8d1cSJulian Grajkowski * component takes ownership of the memory until 72078ee8d1cSJulian Grajkowski * it is returned in the callback. 72178ee8d1cSJulian Grajkowski * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 72278ee8d1cSJulian Grajkowski * valid (CPA_TRUE) or the output is invalid 72378ee8d1cSJulian Grajkowski * (CPA_FALSE). 72478ee8d1cSJulian Grajkowski * @param[out] pXk Pointer to xk flat buffer. 72578ee8d1cSJulian Grajkowski * @param[out] pYk Pointer to yk flat buffer. 72678ee8d1cSJulian Grajkowski * 72778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 72878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 72978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 73078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 73178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 73278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 73378ee8d1cSJulian Grajkowski * the request. 73478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 73578ee8d1cSJulian Grajkowski * 73678ee8d1cSJulian Grajkowski * @pre 73778ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 73878ee8d1cSJulian Grajkowski * @post 73978ee8d1cSJulian Grajkowski * None 74078ee8d1cSJulian Grajkowski * @note 74178ee8d1cSJulian Grajkowski * When pCb is non-NULL an asynchronous callback of type 74278ee8d1cSJulian Grajkowski * CpaCyEcPointMultiplyCbFunc is generated in response to this function 74378ee8d1cSJulian Grajkowski * call. 74478ee8d1cSJulian Grajkowski * For optimal performance, data pointers SHOULD be 8-byte aligned. 74578ee8d1cSJulian Grajkowski * 74678ee8d1cSJulian Grajkowski * @see 74778ee8d1cSJulian Grajkowski * CpaCyEcPointMultiplyOpData, 74878ee8d1cSJulian Grajkowski * CpaCyEcPointMultiplyCbFunc 74978ee8d1cSJulian Grajkowski * 75078ee8d1cSJulian Grajkowski *****************************************************************************/ 751266b0663SKrzysztof Zdziarski CpaStatus CPA_DEPRECATED 75278ee8d1cSJulian Grajkowski cpaCyEcPointMultiply(const CpaInstanceHandle instanceHandle, 75378ee8d1cSJulian Grajkowski const CpaCyEcPointMultiplyCbFunc pCb, 75478ee8d1cSJulian Grajkowski void *pCallbackTag, 75578ee8d1cSJulian Grajkowski const CpaCyEcPointMultiplyOpData *pOpData, 75678ee8d1cSJulian Grajkowski CpaBoolean *pMultiplyStatus, 75778ee8d1cSJulian Grajkowski CpaFlatBuffer *pXk, 75878ee8d1cSJulian Grajkowski CpaFlatBuffer *pYk); 75978ee8d1cSJulian Grajkowski 76078ee8d1cSJulian Grajkowski 76178ee8d1cSJulian Grajkowski /** 76278ee8d1cSJulian Grajkowski ***************************************************************************** 76378ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 76478ee8d1cSJulian Grajkowski * Verify that a point is on an elliptic curve. 76578ee8d1cSJulian Grajkowski * 766266b0663SKrzysztof Zdziarski * @deprecated 767266b0663SKrzysztof Zdziarski * This function is replaced with @ref cpaCyEcGenericPointVerify 768266b0663SKrzysztof Zdziarski * 76978ee8d1cSJulian Grajkowski * @description 77078ee8d1cSJulian Grajkowski * This function performs Elliptic Curve Point Verification, as per 77178ee8d1cSJulian Grajkowski * steps a, b and c of ANSI X9.62 Annex A.4.2. (To perform the final 77278ee8d1cSJulian Grajkowski * step d, the user can call @ref cpaCyEcPointMultiply.) 77378ee8d1cSJulian Grajkowski * 77478ee8d1cSJulian Grajkowski * This function checks if the specified point satisfies the 77578ee8d1cSJulian Grajkowski * Weierstrass equation for an Elliptic Curve. 77678ee8d1cSJulian Grajkowski * 77778ee8d1cSJulian Grajkowski * For GF(p): 77878ee8d1cSJulian Grajkowski * y^2 = (x^3 + ax + b) mod p 77978ee8d1cSJulian Grajkowski * For GF(2^m): 78078ee8d1cSJulian Grajkowski * y^2 + xy = x^3 + ax^2 + b mod p 78178ee8d1cSJulian Grajkowski * where p is the irreducible polynomial over GF(2^m) 78278ee8d1cSJulian Grajkowski * 78378ee8d1cSJulian Grajkowski * Use this function to verify a point is in the correct range and is 78478ee8d1cSJulian Grajkowski * NOT the point at infinity. 78578ee8d1cSJulian Grajkowski * 78678ee8d1cSJulian Grajkowski * @context 78778ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 78878ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 78978ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 79078ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 79178ee8d1cSJulian Grajkowski * @assumptions 79278ee8d1cSJulian Grajkowski * None 79378ee8d1cSJulian Grajkowski * @sideEffects 79478ee8d1cSJulian Grajkowski * None 79578ee8d1cSJulian Grajkowski * @blocking 79678ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 79778ee8d1cSJulian Grajkowski * @reentrant 79878ee8d1cSJulian Grajkowski * No 79978ee8d1cSJulian Grajkowski * @threadSafe 80078ee8d1cSJulian Grajkowski * Yes 80178ee8d1cSJulian Grajkowski * 80278ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 80378ee8d1cSJulian Grajkowski * @param[in] pCb Callback function pointer. If this is set to 80478ee8d1cSJulian Grajkowski * a NULL value the function will operate 80578ee8d1cSJulian Grajkowski * synchronously. 80678ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 80778ee8d1cSJulian Grajkowski * @param[in] pOpData Structure containing all the data needed to 80878ee8d1cSJulian Grajkowski * perform the operation. The client code 80978ee8d1cSJulian Grajkowski * allocates the memory for this structure. This 81078ee8d1cSJulian Grajkowski * component takes ownership of the memory until 81178ee8d1cSJulian Grajkowski * it is returned in the callback. 81278ee8d1cSJulian Grajkowski * @param[out] pVerifyStatus In synchronous mode, set to CPA_FALSE if the 81378ee8d1cSJulian Grajkowski * point is NOT on the curve or at infinity. Set 81478ee8d1cSJulian Grajkowski * to CPA_TRUE if the point is on the curve. 81578ee8d1cSJulian Grajkowski * 81678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 81778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 81878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 81978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 82078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 82178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 82278ee8d1cSJulian Grajkowski * the request. 82378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 82478ee8d1cSJulian Grajkowski * 82578ee8d1cSJulian Grajkowski * @pre 82678ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 82778ee8d1cSJulian Grajkowski * @post 82878ee8d1cSJulian Grajkowski * None 82978ee8d1cSJulian Grajkowski * @note 83078ee8d1cSJulian Grajkowski * When pCb is non-NULL an asynchronous callback of type 83178ee8d1cSJulian Grajkowski * CpaCyEcPointVerifyCbFunc is generated in response to this function 83278ee8d1cSJulian Grajkowski * call. 83378ee8d1cSJulian Grajkowski * For optimal performance, data pointers SHOULD be 8-byte aligned. 83478ee8d1cSJulian Grajkowski * 83578ee8d1cSJulian Grajkowski * @see 83678ee8d1cSJulian Grajkowski * CpaCyEcPointVerifyOpData, 83778ee8d1cSJulian Grajkowski * CpaCyEcPointVerifyCbFunc 83878ee8d1cSJulian Grajkowski * 83978ee8d1cSJulian Grajkowski *****************************************************************************/ 840266b0663SKrzysztof Zdziarski CpaStatus CPA_DEPRECATED 84178ee8d1cSJulian Grajkowski cpaCyEcPointVerify(const CpaInstanceHandle instanceHandle, 84278ee8d1cSJulian Grajkowski const CpaCyEcPointVerifyCbFunc pCb, 84378ee8d1cSJulian Grajkowski void *pCallbackTag, 84478ee8d1cSJulian Grajkowski const CpaCyEcPointVerifyOpData *pOpData, 84578ee8d1cSJulian Grajkowski CpaBoolean *pVerifyStatus); 84678ee8d1cSJulian Grajkowski 84778ee8d1cSJulian Grajkowski /** 84878ee8d1cSJulian Grajkowski ***************************************************************************** 849266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 850266b0663SKrzysztof Zdziarski * Generic ECC point multiplication operation. 851266b0663SKrzysztof Zdziarski * 852266b0663SKrzysztof Zdziarski * @description 853266b0663SKrzysztof Zdziarski * This is the generic ECC point multiplication operation, which is 854266b0663SKrzysztof Zdziarski * agnostic to the type of the curve used. 855266b0663SKrzysztof Zdziarski * 856266b0663SKrzysztof Zdziarski * @context 857266b0663SKrzysztof Zdziarski * 858266b0663SKrzysztof Zdziarski * @assumptions 859266b0663SKrzysztof Zdziarski * None 860266b0663SKrzysztof Zdziarski * @sideEffects 861266b0663SKrzysztof Zdziarski * None 862266b0663SKrzysztof Zdziarski * @blocking 863266b0663SKrzysztof Zdziarski * Yes when configured to operate in synchronous mode. 864266b0663SKrzysztof Zdziarski * @reentrant 865266b0663SKrzysztof Zdziarski * No 866266b0663SKrzysztof Zdziarski * @threadSafe 867266b0663SKrzysztof Zdziarski * Yes 868266b0663SKrzysztof Zdziarski * 869266b0663SKrzysztof Zdziarski * @param[in] instanceHandle Instance handle. 870266b0663SKrzysztof Zdziarski * @param[in] pCb Callback function pointer. If this is set 871266b0663SKrzysztof Zdziarski * to a NULL value, the function will operate 872266b0663SKrzysztof Zdziarski * synchronously. 873266b0663SKrzysztof Zdziarski * @param[in] pCallbackTag User-supplied value to help identify 874266b0663SKrzysztof Zdziarski * request. 875266b0663SKrzysztof Zdziarski * @param[in] pOpData Structure containing all the data needed to 876266b0663SKrzysztof Zdziarski * perform the operation. The client code 877266b0663SKrzysztof Zdziarski * allocates the memory for this structure. 878266b0663SKrzysztof Zdziarski * This component takes ownership of the 879266b0663SKrzysztof Zdziarski * memory until it is returned in the 880266b0663SKrzysztof Zdziarski * callback. 881266b0663SKrzysztof Zdziarski * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 882266b0663SKrzysztof Zdziarski * valid (CPA_TRUE) or the output is invalid 883266b0663SKrzysztof Zdziarski * (CPA_FALSE). 884266b0663SKrzysztof Zdziarski * 885266b0663SKrzysztof Zdziarski * @param[out] pXk Pointer to xk flat buffer. 886266b0663SKrzysztof Zdziarski * @param[out] pYk Pointer to yk flat buffer. 887266b0663SKrzysztof Zdziarski * 888266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_SUCCESS Function executed successfully. 889266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_FAIL Function failed. 890266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 891266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_RESOURCE Error related to system resources. 892266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 893266b0663SKrzysztof Zdziarski * the request. 894266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 895266b0663SKrzysztof Zdziarski * 896266b0663SKrzysztof Zdziarski * @pre 897266b0663SKrzysztof Zdziarski * Component has been initialized. 898266b0663SKrzysztof Zdziarski * @post 899266b0663SKrzysztof Zdziarski * None 900266b0663SKrzysztof Zdziarski * @note 901266b0663SKrzysztof Zdziarski * When pCb is non-NULL an asynchronous callback of type 902266b0663SKrzysztof Zdziarski * CpaCyEcPointMultiplyCbFunc is generated in response to this function 903266b0663SKrzysztof Zdziarski * call. 904266b0663SKrzysztof Zdziarski * For optimal performance, data pointers SHOULD be 8-byte aligned. 905266b0663SKrzysztof Zdziarski * @see 906266b0663SKrzysztof Zdziarski * CpaCyEcPointMultiplyOpData, 907266b0663SKrzysztof Zdziarski * CpaCyEcPointMultiplyCbFunc 908266b0663SKrzysztof Zdziarski * CpaCyEcCurveType 909266b0663SKrzysztof Zdziarski * CpaCyEcCurveParameters 910266b0663SKrzysztof Zdziarski *****************************************************************************/ 911266b0663SKrzysztof Zdziarski CpaStatus 912266b0663SKrzysztof Zdziarski cpaCyEcGenericPointMultiply( 913266b0663SKrzysztof Zdziarski const CpaInstanceHandle instanceHandle, 914266b0663SKrzysztof Zdziarski const CpaCyEcPointMultiplyCbFunc pCb, 915266b0663SKrzysztof Zdziarski void *pCallbackTag, 916266b0663SKrzysztof Zdziarski const CpaCyEcGenericPointMultiplyOpData *pOpData, 917266b0663SKrzysztof Zdziarski CpaBoolean *pMultiplyStatus, 918266b0663SKrzysztof Zdziarski CpaFlatBuffer *pXk, 919266b0663SKrzysztof Zdziarski CpaFlatBuffer *pYk); 920266b0663SKrzysztof Zdziarski 921266b0663SKrzysztof Zdziarski /** 922266b0663SKrzysztof Zdziarski ***************************************************************************** 923266b0663SKrzysztof Zdziarski * @ingroup cpaCyEc 924266b0663SKrzysztof Zdziarski * Generic ECC point verification operation. 925266b0663SKrzysztof Zdziarski * 926266b0663SKrzysztof Zdziarski * @description 927266b0663SKrzysztof Zdziarski * This is the generic ECC point verification operation, which is 928266b0663SKrzysztof Zdziarski * agnostic to the type of the curve used. 929266b0663SKrzysztof Zdziarski * 930266b0663SKrzysztof Zdziarski * @context 931266b0663SKrzysztof Zdziarski * 932266b0663SKrzysztof Zdziarski * @assumptions 933266b0663SKrzysztof Zdziarski * None 934266b0663SKrzysztof Zdziarski * @sideEffects 935266b0663SKrzysztof Zdziarski * None 936266b0663SKrzysztof Zdziarski * @blocking 937266b0663SKrzysztof Zdziarski * Yes when configured to operate in synchronous mode. 938266b0663SKrzysztof Zdziarski * @reentrant 939266b0663SKrzysztof Zdziarski * No 940266b0663SKrzysztof Zdziarski * @threadSafe 941266b0663SKrzysztof Zdziarski * Yes 942266b0663SKrzysztof Zdziarski * 943266b0663SKrzysztof Zdziarski * @param[in] instanceHandle Instance handle. 944266b0663SKrzysztof Zdziarski * @param[in] pCb Callback function pointer. If this is set 945266b0663SKrzysztof Zdziarski * to a NULL value the function will operate 946266b0663SKrzysztof Zdziarski * synchronously. 947266b0663SKrzysztof Zdziarski * @param[in] pCallbackTag User-supplied value to help identify 948266b0663SKrzysztof Zdziarski * request. 949266b0663SKrzysztof Zdziarski * @param[in] pOpData Structure containing all the data needed to 950266b0663SKrzysztof Zdziarski * perform the operation. The client code 951266b0663SKrzysztof Zdziarski * allocates the memory for this structure. 952266b0663SKrzysztof Zdziarski * This component takes ownership of the 953266b0663SKrzysztof Zdziarski * memory until it is returned in the 954266b0663SKrzysztof Zdziarski * callback. 955266b0663SKrzysztof Zdziarski * @param[out] pVerifyStatus In synchronous mode, the verification 956266b0663SKrzysztof Zdziarski * output is valid (CPA_TRUE) or the output is 957266b0663SKrzysztof Zdziarski * invalid (CPA_FALSE). 958266b0663SKrzysztof Zdziarski 959266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_SUCCESS Function executed successfully. 960266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_FAIL Function failed. 961266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 962266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_RESOURCE Error related to system resources. 963266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 964266b0663SKrzysztof Zdziarski * the request. 965266b0663SKrzysztof Zdziarski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 966266b0663SKrzysztof Zdziarski * 967266b0663SKrzysztof Zdziarski * @pre 968266b0663SKrzysztof Zdziarski * Component has been initialized. 969266b0663SKrzysztof Zdziarski * @post 970266b0663SKrzysztof Zdziarski * None 971266b0663SKrzysztof Zdziarski * @note 972266b0663SKrzysztof Zdziarski * When pCb is non-NULL an asynchronous callback of type 973266b0663SKrzysztof Zdziarski * CpaCyEcPointVerifyCbFunc is generated in response to this function call. 974266b0663SKrzysztof Zdziarski * For optimal performance, data pointers SHOULD be 8-byte aligned. 975266b0663SKrzysztof Zdziarski * @see 976266b0663SKrzysztof Zdziarski * CpaCyEcGenericPointVerifyOpData, 977266b0663SKrzysztof Zdziarski * CpaCyEcPointVerifyCbFunc 978266b0663SKrzysztof Zdziarski * CpaCyEcCurveType 979266b0663SKrzysztof Zdziarski * CpaCyEcCurveParameters 980266b0663SKrzysztof Zdziarski *****************************************************************************/ 981266b0663SKrzysztof Zdziarski CpaStatus 982266b0663SKrzysztof Zdziarski cpaCyEcGenericPointVerify ( 983266b0663SKrzysztof Zdziarski const CpaInstanceHandle instanceHandle, 984266b0663SKrzysztof Zdziarski const CpaCyEcPointVerifyCbFunc pCb, 985266b0663SKrzysztof Zdziarski void *pCallbackTag, 986266b0663SKrzysztof Zdziarski const CpaCyEcGenericPointVerifyOpData *pOpData, 987266b0663SKrzysztof Zdziarski CpaBoolean *pVerifyStatus); 988266b0663SKrzysztof Zdziarski 989266b0663SKrzysztof Zdziarski /** 990266b0663SKrzysztof Zdziarski ***************************************************************************** 99178ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 99278ee8d1cSJulian Grajkowski * Perform EC Point Multiplication on an Edwards or Montgomery curve as 99378ee8d1cSJulian Grajkowski * defined in RFC#7748. 99478ee8d1cSJulian Grajkowski * 99578ee8d1cSJulian Grajkowski * @description 99678ee8d1cSJulian Grajkowski * This function performs Elliptic Curve Point Multiplication as per 99778ee8d1cSJulian Grajkowski * RFC#7748 99878ee8d1cSJulian Grajkowski * 99978ee8d1cSJulian Grajkowski * @context 100078ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 100178ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 100278ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 100378ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 100478ee8d1cSJulian Grajkowski * @assumptions 100578ee8d1cSJulian Grajkowski * None 100678ee8d1cSJulian Grajkowski * @sideEffects 100778ee8d1cSJulian Grajkowski * None 100878ee8d1cSJulian Grajkowski * @blocking 100978ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 101078ee8d1cSJulian Grajkowski * @reentrant 101178ee8d1cSJulian Grajkowski * No 101278ee8d1cSJulian Grajkowski * @threadSafe 101378ee8d1cSJulian Grajkowski * Yes 101478ee8d1cSJulian Grajkowski * 101578ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 101678ee8d1cSJulian Grajkowski * @param[in] pCb Callback function pointer. If this is set to 101778ee8d1cSJulian Grajkowski * a NULL value the function will operate 101878ee8d1cSJulian Grajkowski * synchronously. 101978ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 102078ee8d1cSJulian Grajkowski * @param[in] pOpData Structure containing all the data needed to 102178ee8d1cSJulian Grajkowski * perform the operation. The client code 102278ee8d1cSJulian Grajkowski * allocates the memory for this structure. This 102378ee8d1cSJulian Grajkowski * component takes ownership of the memory until 102478ee8d1cSJulian Grajkowski * it is returned in the callback. 102578ee8d1cSJulian Grajkowski * @param[out] pMultiplyStatus In synchronous mode, the multiply output is 102678ee8d1cSJulian Grajkowski * valid (CPA_TRUE) or the output is invalid 102778ee8d1cSJulian Grajkowski * (CPA_FALSE). 102878ee8d1cSJulian Grajkowski * @param[out] pXk Pointer to xk flat buffer. 102978ee8d1cSJulian Grajkowski * @param[out] pYk Pointer to yk flat buffer. 103078ee8d1cSJulian Grajkowski * 103178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 103278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 103378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 103478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter in. 103578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 103678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 103778ee8d1cSJulian Grajkowski * the request. 103878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 103978ee8d1cSJulian Grajkowski * 104078ee8d1cSJulian Grajkowski * @pre 104178ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 104278ee8d1cSJulian Grajkowski * @post 104378ee8d1cSJulian Grajkowski * None 104478ee8d1cSJulian Grajkowski * @note 104578ee8d1cSJulian Grajkowski * When pCb is non-NULL an asynchronous callback of type 104678ee8d1cSJulian Grajkowski * CpaCyEcPointMultiplyCbFunc is generated in response to this function 104778ee8d1cSJulian Grajkowski * call. 104878ee8d1cSJulian Grajkowski * For optimal performance, data pointers SHOULD be 8-byte aligned. 104978ee8d1cSJulian Grajkowski * 105078ee8d1cSJulian Grajkowski * @see 105178ee8d1cSJulian Grajkowski * CpaCyEcMontEdwdsPointMultiplyOpData, 105278ee8d1cSJulian Grajkowski * CpaCyEcMontEdwdsPointMultiplyCbFunc 105378ee8d1cSJulian Grajkowski * 105478ee8d1cSJulian Grajkowski *****************************************************************************/ 105578ee8d1cSJulian Grajkowski CpaStatus 105678ee8d1cSJulian Grajkowski cpaCyEcMontEdwdsPointMultiply(const CpaInstanceHandle instanceHandle, 105778ee8d1cSJulian Grajkowski const CpaCyEcPointMultiplyCbFunc pCb, 105878ee8d1cSJulian Grajkowski void *pCallbackTag, 105978ee8d1cSJulian Grajkowski const CpaCyEcMontEdwdsPointMultiplyOpData *pOpData, 106078ee8d1cSJulian Grajkowski CpaBoolean *pMultiplyStatus, 106178ee8d1cSJulian Grajkowski CpaFlatBuffer *pXk, 106278ee8d1cSJulian Grajkowski CpaFlatBuffer *pYk); 106378ee8d1cSJulian Grajkowski 106478ee8d1cSJulian Grajkowski /** 106578ee8d1cSJulian Grajkowski ***************************************************************************** 106678ee8d1cSJulian Grajkowski * @ingroup cpaCyEc 106778ee8d1cSJulian Grajkowski * Query statistics for a specific EC instance. 106878ee8d1cSJulian Grajkowski * 106978ee8d1cSJulian Grajkowski * @description 107078ee8d1cSJulian Grajkowski * This function will query a specific instance of the EC implementation 107178ee8d1cSJulian Grajkowski * for statistics. The user MUST allocate the CpaCyEcStats64 structure 107278ee8d1cSJulian Grajkowski * and pass the reference to that structure into this function call. This 107378ee8d1cSJulian Grajkowski * function writes the statistic results into the passed in 107478ee8d1cSJulian Grajkowski * CpaCyEcStats64 structure. 107578ee8d1cSJulian Grajkowski * 107678ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 107778ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 107878ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 107978ee8d1cSJulian Grajkowski * 108078ee8d1cSJulian Grajkowski * @context 108178ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 108278ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 108378ee8d1cSJulian Grajkowski * @assumptions 108478ee8d1cSJulian Grajkowski * None 108578ee8d1cSJulian Grajkowski * @sideEffects 108678ee8d1cSJulian Grajkowski * None 108778ee8d1cSJulian Grajkowski * @blocking 108878ee8d1cSJulian Grajkowski * This function is synchronous and blocking. 108978ee8d1cSJulian Grajkowski * @reentrant 109078ee8d1cSJulian Grajkowski * No 109178ee8d1cSJulian Grajkowski * @threadSafe 109278ee8d1cSJulian Grajkowski * Yes 109378ee8d1cSJulian Grajkowski * 109478ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 109578ee8d1cSJulian Grajkowski * @param[out] pEcStats Pointer to memory into which the statistics 109678ee8d1cSJulian Grajkowski * will be written. 109778ee8d1cSJulian Grajkowski * 109878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 109978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 110078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 110178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 110278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 110378ee8d1cSJulian Grajkowski * the request. 110478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 110578ee8d1cSJulian Grajkowski * 110678ee8d1cSJulian Grajkowski * @pre 110778ee8d1cSJulian Grajkowski * Component has been initialized. 110878ee8d1cSJulian Grajkowski * @post 110978ee8d1cSJulian Grajkowski * None 111078ee8d1cSJulian Grajkowski * @note 111178ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 111278ee8d1cSJulian Grajkowski * callback will be generated. 111378ee8d1cSJulian Grajkowski * @see 111478ee8d1cSJulian Grajkowski * CpaCyEcStats64 111578ee8d1cSJulian Grajkowski *****************************************************************************/ 111678ee8d1cSJulian Grajkowski CpaStatus 111778ee8d1cSJulian Grajkowski cpaCyEcQueryStats64(const CpaInstanceHandle instanceHandle, 111878ee8d1cSJulian Grajkowski CpaCyEcStats64 *pEcStats); 111978ee8d1cSJulian Grajkowski 112078ee8d1cSJulian Grajkowski #ifdef __cplusplus 112178ee8d1cSJulian Grajkowski } /* close the extern "C" { */ 112278ee8d1cSJulian Grajkowski #endif 112378ee8d1cSJulian Grajkowski 112478ee8d1cSJulian Grajkowski #endif /*CPA_CY_EC_H_*/ 1125