1 /*************************************************************************** 2 * 3 * BSD LICENSE 4 * 5 * Copyright(c) 2007-2022 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 ***************************************************************************** 300 * @ingroup cpaCyEcdh 301 * Query statistics for a specific ECDH instance. 302 * 303 * @description 304 * This function will query a specific instance of the ECDH implementation 305 * for statistics. The user MUST allocate the CpaCyEcdhStats64 structure 306 * and pass the reference to that structure into this function call. This 307 * function writes the statistic results into the passed in 308 * CpaCyEcdhStats64 structure. 309 * 310 * Note: statistics returned by this function do not interrupt current data 311 * processing and as such can be slightly out of sync with operations that 312 * are in progress during the statistics retrieval process. 313 * 314 * @context 315 * This is a synchronous function and it can sleep. It MUST NOT be 316 * executed in a context that DOES NOT permit sleeping. 317 * @assumptions 318 * None 319 * @sideEffects 320 * None 321 * @blocking 322 * This function is synchronous and blocking. 323 * @reentrant 324 * No 325 * @threadSafe 326 * Yes 327 * 328 * @param[in] instanceHandle Instance handle. 329 * @param[out] pEcdhStats Pointer to memory into which the statistics 330 * will be written. 331 * 332 * @retval CPA_STATUS_SUCCESS Function executed successfully. 333 * @retval CPA_STATUS_FAIL Function failed. 334 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 335 * @retval CPA_STATUS_RESOURCE Error related to system resources. 336 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 337 * the request. 338 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 339 * 340 * @pre 341 * Component has been initialized. 342 * @post 343 * None 344 * @note 345 * This function operates in a synchronous manner and no asynchronous 346 * callback will be generated. 347 * @see 348 * CpaCyEcdhStats64 349 *****************************************************************************/ 350 CpaStatus 351 cpaCyEcdhQueryStats64(const CpaInstanceHandle instanceHandle, 352 CpaCyEcdhStats64 *pEcdhStats); 353 354 #ifdef __cplusplus 355 } /* close the extern "C" { */ 356 #endif 357 358 #endif /*CPA_CY_ECDH_H_*/ 359