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