1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /* 5 ***************************************************************************** 6 * Doxygen group definitions 7 ****************************************************************************/ 8 9 /** 10 ***************************************************************************** 11 * @file cpa_cy_ecdh.h 12 * 13 * @defgroup cpaCyEcdh Elliptic Curve Diffie-Hellman (ECDH) API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for Public Key Encryption 19 * (Cryptography) Elliptic Curve Diffie-Hellman (ECDH) operations. 20 * 21 * @note 22 * Large numbers are represented on the QuickAssist API as described 23 * in the Large Number API (@ref cpaCyLn). 24 * 25 * In addition, the bit length of large numbers passed to the API 26 * MUST NOT exceed 576 bits for Elliptic Curve operations. 27 *****************************************************************************/ 28 29 #ifndef CPA_CY_ECDH_H_ 30 #define CPA_CY_ECDH_H_ 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #include "cpa_cy_common.h" 37 #include "cpa_cy_ec.h" 38 39 /** 40 ***************************************************************************** 41 * @ingroup cpaCyEcdh 42 * ECDH Point Multiplication Operation Data. 43 * 44 * @description 45 * This structure contains the operation data for the 46 * cpaCyEcdhPointMultiply function. The client MUST allocate the memory 47 * for this structure and the items pointed to by this structure. When 48 * the structure is passed into the function, ownership of the memory 49 * passes to the function. Ownership of the memory returns to the client 50 * when this structure is returned in the callback function. 51 * 52 * For optimal performance all data buffers SHOULD be 8-byte aligned. 53 * 54 * All values in this structure are required to be in Most Significant Byte 55 * first order, e.g. a.pData[0] = MSB. 56 * 57 * @note 58 * If the client modifies or frees the memory referenced in this 59 * structure after it has been submitted to the cpaCyEcdhPointMultiply 60 * function, and before it has been returned in the callback, undefined 61 * behavior will result. 62 * 63 * @see 64 * cpaCyEcdhPointMultiply() 65 * 66 *****************************************************************************/ 67 typedef struct _CpaCyEcdhPointMultiplyOpData { 68 CpaFlatBuffer k; 69 /**< scalar multiplier (k > 0 and k < n) */ 70 CpaFlatBuffer xg; 71 /**< x coordinate of curve point */ 72 CpaFlatBuffer yg; 73 /**< y coordinate of curve point */ 74 CpaFlatBuffer a; 75 /**< a equation coefficient */ 76 CpaFlatBuffer b; 77 /**< b equation coefficient */ 78 CpaFlatBuffer q; 79 /**< prime modulus or irreducible polynomial over GF(2^r) */ 80 CpaFlatBuffer h; 81 /**< cofactor of the operation. 82 * If the cofactor is NOT required then set the cofactor to 1 or the 83 * data pointer of the Flat Buffer to NULL. 84 * There are some restrictions on the value of the cofactor. 85 * Implementations of this API will support at least the following: 86 * <ul> 87 * <li>NIST standard curves and their cofactors (1, 2 and 4)</li> 88 * 89 * <li>Random curves where max(log2(p), log2(n)+log2(h)) <= 512, where 90 * p is the modulus, n is the order of the curve and h is the cofactor 91 * </li> 92 * </ul> 93 */ 94 95 CpaCyEcFieldType fieldType; 96 /**< field type for the operation */ 97 CpaBoolean pointVerify; 98 /**< set to CPA_TRUE to do a verification before the multiplication */ 99 } CpaCyEcdhPointMultiplyOpData; 100 101 102 /** 103 ***************************************************************************** 104 * @ingroup cpaCyEcdh 105 * Cryptographic ECDH Statistics. 106 * @description 107 * This structure contains statistics on the Cryptographic ECDH 108 * operations. Statistics are set to zero when the component is 109 * initialized, and are collected per instance. 110 * 111 ****************************************************************************/ 112 typedef struct _CpaCyEcdhStats64 { 113 Cpa64U numEcdhPointMultiplyRequests; 114 /**< Total number of ECDH Point Multiplication operation requests. */ 115 Cpa64U numEcdhPointMultiplyRequestErrors; 116 /**< Total number of ECDH Point Multiplication operation requests that had 117 * an error and could not be processed. */ 118 Cpa64U numEcdhPointMultiplyCompleted; 119 /**< Total number of ECDH Point Multiplication operation requests that 120 * completed successfully. */ 121 Cpa64U numEcdhPointMultiplyCompletedError; 122 /**< Total number of ECDH Point Multiplication operation requests that could 123 * not be completed successfully due to errors. */ 124 Cpa64U numEcdhRequestCompletedOutputInvalid; 125 /**< Total number of ECDH Point Multiplication or Point Verify operation 126 * requests that could not be completed successfully due to an invalid 127 * output. 128 * Note that this does not indicate an error. */ 129 } CpaCyEcdhStats64; 130 131 132 /** 133 ***************************************************************************** 134 * @ingroup cpaCyEcdh 135 * Definition of callback function invoked for cpaCyEcdhPointMultiply 136 * requests. 137 * 138 * @description 139 * This is the prototype for the CpaCyEcdhPointMultiplyCbFunc callback 140 * function 141 * 142 * @context 143 * This callback function can be executed in a context that DOES NOT 144 * permit sleeping to occur. 145 * @assumptions 146 * None 147 * @sideEffects 148 * None 149 * @reentrant 150 * No 151 * @threadSafe 152 * Yes 153 * 154 * @param[in] pCallbackTag User-supplied value to help identify request. 155 * @param[in] status Status of the operation. Valid values are 156 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 157 * CPA_STATUS_UNSUPPORTED. 158 * @param[in] pOpData Opaque pointer to Operation data supplied in 159 * request. 160 * @param[in] pXk Output x coordinate from the request. 161 * @param[in] pYk Output y coordinate from the request. 162 * @param[in] multiplyStatus Status of the point multiplication and the 163 * verification when the pointVerify bit is set 164 * in the CpaCyEcdhPointMultiplyOpData structure. 165 * 166 * @retval 167 * None 168 * @pre 169 * Component has been initialized. 170 * @post 171 * None 172 * @note 173 * None 174 * @see 175 * cpaCyEcdhPointMultiply() 176 * 177 *****************************************************************************/ 178 typedef void (*CpaCyEcdhPointMultiplyCbFunc)(void *pCallbackTag, 179 CpaStatus status, 180 void *pOpData, 181 CpaBoolean multiplyStatus, 182 CpaFlatBuffer *pXk, 183 CpaFlatBuffer *pYk); 184 185 186 /** 187 ***************************************************************************** 188 * @ingroup cpaCyEcdh 189 * ECDH Point Multiplication. 190 * 191 * @description 192 * This function performs ECDH Point Multiplication as defined in 193 * ANSI X9.63 2001 section 5.4 194 * 195 * @context 196 * When called as an asynchronous function it cannot sleep. It can be 197 * executed in a context that does not permit sleeping. 198 * When called as a synchronous function it may sleep. It MUST NOT be 199 * executed in a context that DOES NOT permit sleeping. 200 * @assumptions 201 * None 202 * @sideEffects 203 * None 204 * @blocking 205 * Yes when configured to operate in synchronous mode. 206 * @reentrant 207 * No 208 * @threadSafe 209 * Yes 210 * 211 * @param[in] instanceHandle Instance handle. 212 * @param[in] pCb Callback function pointer. If this is set to 213 * a NULL value the function will operate 214 * synchronously. 215 * @param[in] pCallbackTag User-supplied value to help identify request. 216 * @param[in] pOpData Structure containing all the data needed to 217 * perform the operation. The client code 218 * allocates the memory for this structure. This 219 * component takes ownership of the memory until 220 * it is returned in the callback. 221 * @param[out] pMultiplyStatus In synchronous mode, the status of the point 222 * multiplication and the verification when the 223 * pointVerify bit is set in the 224 * CpaCyEcdhPointMultiplyOpData structure. Set to 225 * CPA_FALSE if the point is NOT on the curve or 226 * at infinity. Set to CPA_TRUE if the point is 227 * on the curve. 228 * @param[out] pXk Pointer to x coordinate flat buffer. 229 * @param[out] pYk Pointer to y coordinate flat buffer. 230 * 231 * @retval CPA_STATUS_SUCCESS Function executed successfully. 232 * @retval CPA_STATUS_FAIL Function failed. 233 * @retval CPA_STATUS_RETRY Resubmit the request. 234 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 235 * @retval CPA_STATUS_RESOURCE Error related to system resources. 236 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 237 * the request. 238 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 239 * 240 * @pre 241 * The component has been initialized via cpaCyStartInstance function. 242 * @post 243 * None 244 * @note 245 * When pCb is non-NULL an asynchronous callback of type 246 * CpaCyEcdhPointMultiplyCbFunc is generated in response to this function 247 * call. 248 * For optimal performance, data pointers SHOULD be 8-byte aligned. 249 * 250 * @see 251 * CpaCyEcdhPointMultiplyOpData, 252 * CpaCyEcdhPointMultiplyCbFunc 253 * 254 *****************************************************************************/ 255 CpaStatus 256 cpaCyEcdhPointMultiply(const CpaInstanceHandle instanceHandle, 257 const CpaCyEcdhPointMultiplyCbFunc pCb, 258 void *pCallbackTag, 259 const CpaCyEcdhPointMultiplyOpData *pOpData, 260 CpaBoolean *pMultiplyStatus, 261 CpaFlatBuffer *pXk, 262 CpaFlatBuffer *pYk); 263 264 /** 265 ***************************************************************************** 266 * @ingroup cpaCyEcdh 267 * Query statistics for a specific ECDH instance. 268 * 269 * @description 270 * This function will query a specific instance of the ECDH implementation 271 * for statistics. The user MUST allocate the CpaCyEcdhStats64 structure 272 * and pass the reference to that structure into this function call. This 273 * function writes the statistic results into the passed in 274 * CpaCyEcdhStats64 structure. 275 * 276 * Note: statistics returned by this function do not interrupt current data 277 * processing and as such can be slightly out of sync with operations that 278 * are in progress during the statistics retrieval process. 279 * 280 * @context 281 * This is a synchronous function and it can sleep. It MUST NOT be 282 * executed in a context that DOES NOT permit sleeping. 283 * @assumptions 284 * None 285 * @sideEffects 286 * None 287 * @blocking 288 * This function is synchronous and blocking. 289 * @reentrant 290 * No 291 * @threadSafe 292 * Yes 293 * 294 * @param[in] instanceHandle Instance handle. 295 * @param[out] pEcdhStats Pointer to memory into which the statistics 296 * will be written. 297 * 298 * @retval CPA_STATUS_SUCCESS Function executed successfully. 299 * @retval CPA_STATUS_FAIL Function failed. 300 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 301 * @retval CPA_STATUS_RESOURCE Error related to system resources. 302 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 303 * the request. 304 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 305 * 306 * @pre 307 * Component has been initialized. 308 * @post 309 * None 310 * @note 311 * This function operates in a synchronous manner and no asynchronous 312 * callback will be generated. 313 * @see 314 * CpaCyEcdhStats64 315 *****************************************************************************/ 316 CpaStatus 317 cpaCyEcdhQueryStats64(const CpaInstanceHandle instanceHandle, 318 CpaCyEcdhStats64 *pEcdhStats); 319 320 #ifdef __cplusplus 321 } /* close the extern "C" { */ 322 #endif 323 324 #endif /*CPA_CY_ECDH_H_*/ 325