/* SPDX-License-Identifier: BSD-3-Clause */ /* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_ecdh.h * * @defgroup cpaCyEcdh Elliptic Curve Diffie-Hellman (ECDH) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) Elliptic Curve Diffie-Hellman (ECDH) operations. * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). * * In addition, the bit length of large numbers passed to the API * MUST NOT exceed 576 bits for Elliptic Curve operations. *****************************************************************************/ #ifndef CPA_CY_ECDH_H_ #define CPA_CY_ECDH_H_ #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" #include "cpa_cy_ec.h" /** ***************************************************************************** * @ingroup cpaCyEcdh * ECDH Point Multiplication Operation Data. * * @description * This structure contains the operation data for the * cpaCyEcdhPointMultiply function. The client MUST allocate the memory * for this structure and the items pointed to by this structure. When * the structure is passed into the function, ownership of the memory * passes to the function. Ownership of the memory returns to the client * when this structure is returned in the callback function. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcdhPointMultiply * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcdhPointMultiply() * *****************************************************************************/ typedef struct _CpaCyEcdhPointMultiplyOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaFlatBuffer xg; /**< x coordinate of curve point */ CpaFlatBuffer yg; /**< y coordinate of curve point */ CpaFlatBuffer a; /**< a equation coefficient */ CpaFlatBuffer b; /**< b equation coefficient */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^r) */ CpaFlatBuffer h; /**< cofactor of the operation. * If the cofactor is NOT required then set the cofactor to 1 or the * data pointer of the Flat Buffer to NULL. * There are some restrictions on the value of the cofactor. * Implementations of this API will support at least the following: * <ul> * <li>NIST standard curves and their cofactors (1, 2 and 4)</li> * * <li>Random curves where max(log2(p), log2(n)+log2(h)) <= 512, where * p is the modulus, n is the order of the curve and h is the cofactor * </li> * </ul> */ CpaCyEcFieldType fieldType; /**< field type for the operation */ CpaBoolean pointVerify; /**< set to CPA_TRUE to do a verification before the multiplication */ } CpaCyEcdhPointMultiplyOpData; /** ***************************************************************************** * @ingroup cpaCyEcdh * Cryptographic ECDH Statistics. * @description * This structure contains statistics on the Cryptographic ECDH * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyEcdhStats64 { Cpa64U numEcdhPointMultiplyRequests; /**< Total number of ECDH Point Multiplication operation requests. */ Cpa64U numEcdhPointMultiplyRequestErrors; /**< Total number of ECDH Point Multiplication operation requests that had * an error and could not be processed. */ Cpa64U numEcdhPointMultiplyCompleted; /**< Total number of ECDH Point Multiplication operation requests that * completed successfully. */ Cpa64U numEcdhPointMultiplyCompletedError; /**< Total number of ECDH Point Multiplication operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdhRequestCompletedOutputInvalid; /**< Total number of ECDH Point Multiplication or Point Verify operation * requests that could not be completed successfully due to an invalid * output. * Note that this does not indicate an error. */ } CpaCyEcdhStats64; /** ***************************************************************************** * @ingroup cpaCyEcdh * Definition of callback function invoked for cpaCyEcdhPointMultiply * requests. * * @description * This is the prototype for the CpaCyEcdhPointMultiplyCbFunc callback * function * * @context * This callback function can be executed in a context that DOES NOT * permit sleeping to occur. * @assumptions * None * @sideEffects * None * @reentrant * No * @threadSafe * Yes * * @param[in] pCallbackTag User-supplied value to help identify request. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] pOpData Opaque pointer to Operation data supplied in * request. * @param[in] pXk Output x coordinate from the request. * @param[in] pYk Output y coordinate from the request. * @param[in] multiplyStatus Status of the point multiplication and the * verification when the pointVerify bit is set * in the CpaCyEcdhPointMultiplyOpData structure. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcdhPointMultiply() * *****************************************************************************/ typedef void (*CpaCyEcdhPointMultiplyCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean multiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @ingroup cpaCyEcdh * ECDH Point Multiplication. * * @description * This function performs ECDH Point Multiplication as defined in * ANSI X9.63 2001 section 5.4 * * @context * When called as an asynchronous function it cannot sleep. It can be * executed in a context that does not permit sleeping. * When called as a synchronous function it may sleep. It MUST NOT be * executed in a context that DOES NOT permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * Yes when configured to operate in synchronous mode. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pCb Callback function pointer. If this is set to * a NULL value the function will operate * synchronously. * @param[in] pCallbackTag User-supplied value to help identify request. * @param[in] pOpData Structure containing all the data needed to * perform the operation. The client code * allocates the memory for this structure. This * component takes ownership of the memory until * it is returned in the callback. * @param[out] pMultiplyStatus In synchronous mode, the status of the point * multiplication and the verification when the * pointVerify bit is set in the * CpaCyEcdhPointMultiplyOpData structure. Set to * CPA_FALSE if the point is NOT on the curve or * at infinity. Set to CPA_TRUE if the point is * on the curve. * @param[out] pXk Pointer to x coordinate flat buffer. * @param[out] pYk Pointer to y coordinate flat buffer. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @retval CPA_STATUS_RETRY Resubmit the request. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_RESOURCE Error related to system resources. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @note * When pCb is non-NULL an asynchronous callback of type * CpaCyEcdhPointMultiplyCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcdhPointMultiplyOpData, * CpaCyEcdhPointMultiplyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcdhPointMultiply(const CpaInstanceHandle instanceHandle, const CpaCyEcdhPointMultiplyCbFunc pCb, void *pCallbackTag, const CpaCyEcdhPointMultiplyOpData *pOpData, CpaBoolean *pMultiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @ingroup cpaCyEcdh * Query statistics for a specific ECDH instance. * * @description * This function will query a specific instance of the ECDH implementation * for statistics. The user MUST allocate the CpaCyEcdhStats64 structure * and pass the reference to that structure into this function call. This * function writes the statistic results into the passed in * CpaCyEcdhStats64 structure. * * Note: statistics returned by this function do not interrupt current data * processing and as such can be slightly out of sync with operations that * are in progress during the statistics retrieval process. * * @context * This is a synchronous function and it can sleep. It MUST NOT be * executed in a context that DOES NOT permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pEcdhStats Pointer to memory into which the statistics * will be written. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_RESOURCE Error related to system resources. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * Component has been initialized. * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * @see * CpaCyEcdhStats64 *****************************************************************************/ CpaStatus cpaCyEcdhQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyEcdhStats64 *pEcdhStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /*CPA_CY_ECDH_H_*/
