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_dh.h 4578ee8d1cSJulian Grajkowski * 4678ee8d1cSJulian Grajkowski * @defgroup cpaCyDh Diffie-Hellman (DH) 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) operations for use with Diffie-Hellman algorithm. 5378ee8d1cSJulian Grajkowski * 5478ee8d1cSJulian Grajkowski * @note 5578ee8d1cSJulian Grajkowski * Large numbers are represented on the QuickAssist API as described 5678ee8d1cSJulian Grajkowski * in the Large Number API (@ref cpaCyLn). 5778ee8d1cSJulian Grajkowski *****************************************************************************/ 5878ee8d1cSJulian Grajkowski 5978ee8d1cSJulian Grajkowski #ifndef CPA_CY_DH_H 6078ee8d1cSJulian Grajkowski #define CPA_CY_DH_H 6178ee8d1cSJulian Grajkowski 6278ee8d1cSJulian Grajkowski #ifdef __cplusplus 6378ee8d1cSJulian Grajkowski extern "C" { 6478ee8d1cSJulian Grajkowski #endif 6578ee8d1cSJulian Grajkowski 6678ee8d1cSJulian Grajkowski #include "cpa_cy_common.h" 6778ee8d1cSJulian Grajkowski /** 6878ee8d1cSJulian Grajkowski ***************************************************************************** 6978ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 7078ee8d1cSJulian Grajkowski * Diffie-Hellman Phase 1 Key Generation Data. 7178ee8d1cSJulian Grajkowski * @description 7278ee8d1cSJulian Grajkowski * This structure lists the different items that are required in the 7378ee8d1cSJulian Grajkowski * cpaCyDhKeyGenPhase1 function. The client MUST allocate the memory for 7478ee8d1cSJulian Grajkowski * this structure. When the structure is passed into the function, 7578ee8d1cSJulian Grajkowski * ownership of the memory passes to the function. Ownership of the memory 7678ee8d1cSJulian Grajkowski * returns to the client when this structure is returned with the 7778ee8d1cSJulian Grajkowski * CpaCyDhPhase1KeyGenOpData structure. 7878ee8d1cSJulian Grajkowski * 7978ee8d1cSJulian Grajkowski * @note 8078ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this structure 8178ee8d1cSJulian Grajkowski * after it has been submitted to the cpaCyDhKeyGenPhase1 function, and 8278ee8d1cSJulian Grajkowski * before it has been returned in the callback, undefined behavior will 8378ee8d1cSJulian Grajkowski * result. 8478ee8d1cSJulian Grajkowski * All values in this structure are required to be in Most Significant Byte 8578ee8d1cSJulian Grajkowski * first order, e.g. primeP.pData[0] = MSB. 8678ee8d1cSJulian Grajkowski * 8778ee8d1cSJulian Grajkowski *****************************************************************************/ 8878ee8d1cSJulian Grajkowski typedef struct _CpaCyDhPhase1KeyGenOpData { 8978ee8d1cSJulian Grajkowski CpaFlatBuffer primeP; 9078ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the random odd prime number (p). 9178ee8d1cSJulian Grajkowski * The bit-length of this number may be one of 768, 1024, 1536, 2048, 92266b0663SKrzysztof Zdziarski * 3072, 4096 or 8192. 9378ee8d1cSJulian Grajkowski */ 9478ee8d1cSJulian Grajkowski CpaFlatBuffer baseG; 9578ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to base (g). This MUST comply with 9678ee8d1cSJulian Grajkowski * the following: 9778ee8d1cSJulian Grajkowski * 0 < g < p. 9878ee8d1cSJulian Grajkowski */ 9978ee8d1cSJulian Grajkowski CpaFlatBuffer privateValueX; 10078ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the private value (x). This is a 10178ee8d1cSJulian Grajkowski * random value which MUST satisfy the following condition: 10278ee8d1cSJulian Grajkowski * 0 < PrivateValueX < (PrimeP - 1) 10378ee8d1cSJulian Grajkowski * 10478ee8d1cSJulian Grajkowski * Refer to PKCS #3: Diffie-Hellman Key-Agreement Standard for details. 10578ee8d1cSJulian Grajkowski * The client creating this data MUST ensure the compliance of this value 10678ee8d1cSJulian Grajkowski * with the standard. Note: This value is also needed to complete local 10778ee8d1cSJulian Grajkowski * phase 2 Diffie-Hellman operation.*/ 10878ee8d1cSJulian Grajkowski } CpaCyDhPhase1KeyGenOpData; 10978ee8d1cSJulian Grajkowski 11078ee8d1cSJulian Grajkowski /** 11178ee8d1cSJulian Grajkowski ***************************************************************************** 11278ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 11378ee8d1cSJulian Grajkowski * Diffie-Hellman Phase 2 Secret Key Generation Data. 11478ee8d1cSJulian Grajkowski * @description 11578ee8d1cSJulian Grajkowski * This structure lists the different items that required in the 11678ee8d1cSJulian Grajkowski * cpaCyDhKeyGenPhase2Secret function. The client MUST allocate the 11778ee8d1cSJulian Grajkowski * memory for this structure. When the structure is passed into the 11878ee8d1cSJulian Grajkowski * function, ownership of the memory passes to the function. Ownership of 11978ee8d1cSJulian Grajkowski * the memory returns to the client when this structure is returned with 12078ee8d1cSJulian Grajkowski * the callback. 12178ee8d1cSJulian Grajkowski * @note 12278ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this structure 12378ee8d1cSJulian Grajkowski * after it has been submitted to the cpaCyDhKeyGenPhase2Secret 12478ee8d1cSJulian Grajkowski * function, and before it has been returned in the callback, undefined 12578ee8d1cSJulian Grajkowski * behavior will result. 12678ee8d1cSJulian Grajkowski * All values in this structure are required to be in Most Significant Byte 12778ee8d1cSJulian Grajkowski * first order, e.g. primeP.pData[0] = MSB. 12878ee8d1cSJulian Grajkowski * 12978ee8d1cSJulian Grajkowski *****************************************************************************/ 13078ee8d1cSJulian Grajkowski typedef struct _CpaCyDhPhase2SecretKeyGenOpData { 13178ee8d1cSJulian Grajkowski CpaFlatBuffer primeP; 13278ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the random odd prime number (p). 13378ee8d1cSJulian Grajkowski * The bit-length of this number may be one of 768, 1024, 1536, 2048, 134266b0663SKrzysztof Zdziarski * 3072, 4096 or 8192. 13578ee8d1cSJulian Grajkowski * This SHOULD be same prime number as was used in the phase 1 key 13678ee8d1cSJulian Grajkowski * generation operation. */ 13778ee8d1cSJulian Grajkowski CpaFlatBuffer remoteOctetStringPV; 13878ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the remote entity 13978ee8d1cSJulian Grajkowski * octet string Public Value (PV). */ 14078ee8d1cSJulian Grajkowski CpaFlatBuffer privateValueX; 14178ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the private value (x). This 14278ee8d1cSJulian Grajkowski * value may have been used in a call to the cpaCyDhKeyGenPhase1 function. 14378ee8d1cSJulian Grajkowski * This is a random value which MUST satisfy the following condition: 14478ee8d1cSJulian Grajkowski * 0 < privateValueX < (primeP - 1). */ 14578ee8d1cSJulian Grajkowski } CpaCyDhPhase2SecretKeyGenOpData; 14678ee8d1cSJulian Grajkowski 14778ee8d1cSJulian Grajkowski /** 14878ee8d1cSJulian Grajkowski ***************************************************************************** 14978ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 15078ee8d1cSJulian Grajkowski * Diffie-Hellman Statistics. 15178ee8d1cSJulian Grajkowski * @deprecated 15278ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this structure has been deprecated, 15378ee8d1cSJulian Grajkowski * replaced by @ref CpaCyDhStats64. 15478ee8d1cSJulian Grajkowski * @description 15578ee8d1cSJulian Grajkowski * This structure contains statistics on the Diffie-Hellman operations. 15678ee8d1cSJulian Grajkowski * Statistics are set to zero when the component is initialized, and are 15778ee8d1cSJulian Grajkowski * collected per instance. 15878ee8d1cSJulian Grajkowski ****************************************************************************/ 15978ee8d1cSJulian Grajkowski typedef struct _CpaCyDhStats { 16078ee8d1cSJulian Grajkowski Cpa32U numDhPhase1KeyGenRequests; 16178ee8d1cSJulian Grajkowski /**< Total number of successful Diffie-Hellman phase 1 key 16278ee8d1cSJulian Grajkowski * generation requests. */ 16378ee8d1cSJulian Grajkowski Cpa32U numDhPhase1KeyGenRequestErrors; 16478ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation requests 16578ee8d1cSJulian Grajkowski * that had an error and could not be processed. */ 16678ee8d1cSJulian Grajkowski Cpa32U numDhPhase1KeyGenCompleted; 16778ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation operations 16878ee8d1cSJulian Grajkowski * that completed successfully. */ 16978ee8d1cSJulian Grajkowski Cpa32U numDhPhase1KeyGenCompletedErrors; 17078ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation operations 17178ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 17278ee8d1cSJulian Grajkowski Cpa32U numDhPhase2KeyGenRequests; 17378ee8d1cSJulian Grajkowski /**< Total number of successful Diffie-Hellman phase 2 key 17478ee8d1cSJulian Grajkowski * generation requests. */ 17578ee8d1cSJulian Grajkowski Cpa32U numDhPhase2KeyGenRequestErrors; 17678ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation requests 17778ee8d1cSJulian Grajkowski * that had an error and could not be processed. */ 17878ee8d1cSJulian Grajkowski Cpa32U numDhPhase2KeyGenCompleted; 17978ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation operations 18078ee8d1cSJulian Grajkowski * that completed successfully. */ 18178ee8d1cSJulian Grajkowski Cpa32U numDhPhase2KeyGenCompletedErrors; 18278ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation operations 18378ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 18478ee8d1cSJulian Grajkowski } CpaCyDhStats CPA_DEPRECATED; 18578ee8d1cSJulian Grajkowski 18678ee8d1cSJulian Grajkowski /** 18778ee8d1cSJulian Grajkowski ***************************************************************************** 18878ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 18978ee8d1cSJulian Grajkowski * Diffie-Hellman Statistics (64-bit version). 19078ee8d1cSJulian Grajkowski * @description 19178ee8d1cSJulian Grajkowski * This structure contains the 64-bit version of the statistics on the 19278ee8d1cSJulian Grajkowski * Diffie-Hellman operations. 19378ee8d1cSJulian Grajkowski * Statistics are set to zero when the component is initialized, and are 19478ee8d1cSJulian Grajkowski * collected per instance. 19578ee8d1cSJulian Grajkowski ****************************************************************************/ 19678ee8d1cSJulian Grajkowski typedef struct _CpaCyDhStats64 { 19778ee8d1cSJulian Grajkowski Cpa64U numDhPhase1KeyGenRequests; 19878ee8d1cSJulian Grajkowski /**< Total number of successful Diffie-Hellman phase 1 key 19978ee8d1cSJulian Grajkowski * generation requests. */ 20078ee8d1cSJulian Grajkowski Cpa64U numDhPhase1KeyGenRequestErrors; 20178ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation requests 20278ee8d1cSJulian Grajkowski * that had an error and could not be processed. */ 20378ee8d1cSJulian Grajkowski Cpa64U numDhPhase1KeyGenCompleted; 20478ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation operations 20578ee8d1cSJulian Grajkowski * that completed successfully. */ 20678ee8d1cSJulian Grajkowski Cpa64U numDhPhase1KeyGenCompletedErrors; 20778ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 1 key generation operations 20878ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 20978ee8d1cSJulian Grajkowski Cpa64U numDhPhase2KeyGenRequests; 21078ee8d1cSJulian Grajkowski /**< Total number of successful Diffie-Hellman phase 2 key 21178ee8d1cSJulian Grajkowski * generation requests. */ 21278ee8d1cSJulian Grajkowski Cpa64U numDhPhase2KeyGenRequestErrors; 21378ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation requests 21478ee8d1cSJulian Grajkowski * that had an error and could not be processed. */ 21578ee8d1cSJulian Grajkowski Cpa64U numDhPhase2KeyGenCompleted; 21678ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation operations 21778ee8d1cSJulian Grajkowski * that completed successfully. */ 21878ee8d1cSJulian Grajkowski Cpa64U numDhPhase2KeyGenCompletedErrors; 21978ee8d1cSJulian Grajkowski /**< Total number of Diffie-Hellman phase 2 key generation operations 22078ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 22178ee8d1cSJulian Grajkowski } CpaCyDhStats64; 22278ee8d1cSJulian Grajkowski 22378ee8d1cSJulian Grajkowski /** 22478ee8d1cSJulian Grajkowski ***************************************************************************** 22578ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 22678ee8d1cSJulian Grajkowski * Function to implement Diffie-Hellman phase 1 operations. 22778ee8d1cSJulian Grajkowski * 22878ee8d1cSJulian Grajkowski * @description 22978ee8d1cSJulian Grajkowski * This function may be used to implement the Diffie-Hellman phase 1 23078ee8d1cSJulian Grajkowski * operations as defined in the PKCS #3 standard. It may be used to 231b197d4b8SGordon Bergling * generate the (local) octet string public value (PV) key. 23278ee8d1cSJulian Grajkowski * The prime number sizes specified in RFC 2409, 4306, and part of 233266b0663SKrzysztof Zdziarski * RFC 3526 are supported (bit size 6144 from RFC 3536 is not 23478ee8d1cSJulian Grajkowski * supported). 23578ee8d1cSJulian Grajkowski * 23678ee8d1cSJulian Grajkowski * @context 23778ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 23878ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 23978ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 24078ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 24178ee8d1cSJulian Grajkowski * @assumptions 24278ee8d1cSJulian Grajkowski * None 24378ee8d1cSJulian Grajkowski * @sideEffects 24478ee8d1cSJulian Grajkowski * None 24578ee8d1cSJulian Grajkowski * @blocking 24678ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 24778ee8d1cSJulian Grajkowski * @reentrant 24878ee8d1cSJulian Grajkowski * No 24978ee8d1cSJulian Grajkowski * @threadSafe 25078ee8d1cSJulian Grajkowski * Yes 25178ee8d1cSJulian Grajkowski * 25278ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 25378ee8d1cSJulian Grajkowski * @param[in] pDhPhase1Cb Pointer to a callback function to be invoked 25478ee8d1cSJulian Grajkowski * when the operation is complete. If the 25578ee8d1cSJulian Grajkowski * pointer is set to a NULL value the function 25678ee8d1cSJulian Grajkowski * will operate synchronously. 25778ee8d1cSJulian Grajkowski * @param[in] pCallbackTag Opaque User Data for this specific call. 25878ee8d1cSJulian Grajkowski * Will be returned unchanged in the callback 25978ee8d1cSJulian Grajkowski * @param[in] pPhase1KeyGenData Structure containing all the data needed 26078ee8d1cSJulian Grajkowski * to perform the DH Phase 1 key generation 26178ee8d1cSJulian Grajkowski * operation. The client code allocates the 26278ee8d1cSJulian Grajkowski * memory for this structure. This component 26378ee8d1cSJulian Grajkowski * takes ownership of the memory until it is 26478ee8d1cSJulian Grajkowski * returned in the callback. 26578ee8d1cSJulian Grajkowski * @param[out] pLocalOctetStringPV Pointer to memory allocated by the client 26678ee8d1cSJulian Grajkowski * into which the (local) octet string Public 26778ee8d1cSJulian Grajkowski * Value (PV) will be written. This value 26878ee8d1cSJulian Grajkowski * needs to be sent to the remote entity with 26978ee8d1cSJulian Grajkowski * which Diffie-Hellman is negotiating. 27078ee8d1cSJulian Grajkowski * The size of this buffer in bytes (as 27178ee8d1cSJulian Grajkowski * represented by the dataLenInBytes field) 27278ee8d1cSJulian Grajkowski * MUST be at least big enough to store 27378ee8d1cSJulian Grajkowski * the public value, which may have a bit 27478ee8d1cSJulian Grajkowski * length up to that of pPrimeP. 27578ee8d1cSJulian Grajkowski * On invocation the callback function 27678ee8d1cSJulian Grajkowski * will contain this parameter in the 27778ee8d1cSJulian Grajkowski * pOut parameter. 27878ee8d1cSJulian Grajkowski * 27978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 28078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 28178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 28278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 28378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 28478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 28578ee8d1cSJulian Grajkowski * the request. 28678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 28778ee8d1cSJulian Grajkowski * 28878ee8d1cSJulian Grajkowski * @pre 28978ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 29078ee8d1cSJulian Grajkowski * @post 29178ee8d1cSJulian Grajkowski * None 29278ee8d1cSJulian Grajkowski * @note 29378ee8d1cSJulian Grajkowski * When pDhPhase1Cb is non-NULL an asynchronous callback of type 29478ee8d1cSJulian Grajkowski * CpaCyGenFlatBufCbFunc is generated in response to this function 29578ee8d1cSJulian Grajkowski * call. Any errors generated during processing are reported in the 29678ee8d1cSJulian Grajkowski * structure returned in the callback. 29778ee8d1cSJulian Grajkowski * 29878ee8d1cSJulian Grajkowski * @see 29978ee8d1cSJulian Grajkowski * CpaCyGenFlatBufCbFunc, 30078ee8d1cSJulian Grajkowski * CpaCyDhPhase1KeyGenOpData 30178ee8d1cSJulian Grajkowski * 30278ee8d1cSJulian Grajkowski *****************************************************************************/ 30378ee8d1cSJulian Grajkowski CpaStatus 30478ee8d1cSJulian Grajkowski cpaCyDhKeyGenPhase1(const CpaInstanceHandle instanceHandle, 30578ee8d1cSJulian Grajkowski const CpaCyGenFlatBufCbFunc pDhPhase1Cb, 30678ee8d1cSJulian Grajkowski void *pCallbackTag, 30778ee8d1cSJulian Grajkowski const CpaCyDhPhase1KeyGenOpData *pPhase1KeyGenData, 30878ee8d1cSJulian Grajkowski CpaFlatBuffer *pLocalOctetStringPV); 30978ee8d1cSJulian Grajkowski 31078ee8d1cSJulian Grajkowski /** 31178ee8d1cSJulian Grajkowski ***************************************************************************** 31278ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 31378ee8d1cSJulian Grajkowski * Function to implement Diffie-Hellman phase 2 operations. 31478ee8d1cSJulian Grajkowski * 31578ee8d1cSJulian Grajkowski * @description 31678ee8d1cSJulian Grajkowski * This function may be used to implement the Diffie-Hellman phase 2 31778ee8d1cSJulian Grajkowski * operation as defined in the PKCS #3 standard. It may be used to 31878ee8d1cSJulian Grajkowski * generate the Diffie-Hellman shared secret key. 31978ee8d1cSJulian Grajkowski * 32078ee8d1cSJulian Grajkowski * @context 32178ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 32278ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 32378ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 32478ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 32578ee8d1cSJulian Grajkowski * @assumptions 32678ee8d1cSJulian Grajkowski * None 32778ee8d1cSJulian Grajkowski * @sideEffects 32878ee8d1cSJulian Grajkowski * None 32978ee8d1cSJulian Grajkowski * @blocking 33078ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 33178ee8d1cSJulian Grajkowski * @reentrant 33278ee8d1cSJulian Grajkowski * No 33378ee8d1cSJulian Grajkowski * @threadSafe 33478ee8d1cSJulian Grajkowski * Yes 33578ee8d1cSJulian Grajkowski * 33678ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 33778ee8d1cSJulian Grajkowski * @param[in] pDhPhase2Cb Pointer to a callback function to be 33878ee8d1cSJulian Grajkowski * invoked when the operation is complete. 33978ee8d1cSJulian Grajkowski * If the pointer is set to a NULL value 34078ee8d1cSJulian Grajkowski * the function will operate synchronously. 34178ee8d1cSJulian Grajkowski * @param[in] pCallbackTag Opaque User Data for this specific 34278ee8d1cSJulian Grajkowski * call. Will be returned unchanged in 34378ee8d1cSJulian Grajkowski * the callback. 34478ee8d1cSJulian Grajkowski * @param[in] pPhase2SecretKeyGenData Structure containing all the data 34578ee8d1cSJulian Grajkowski * needed to perform the DH Phase 2 34678ee8d1cSJulian Grajkowski * secret key generation operation. The 34778ee8d1cSJulian Grajkowski * client code allocates the memory for 34878ee8d1cSJulian Grajkowski * this structure. This component takes 34978ee8d1cSJulian Grajkowski * ownership of the memory until it is 35078ee8d1cSJulian Grajkowski * returned in the callback. 35178ee8d1cSJulian Grajkowski * @param[out] pOctetStringSecretKey Pointer to memory allocated by the 35278ee8d1cSJulian Grajkowski * client into which the octet string 35378ee8d1cSJulian Grajkowski * secret key will be written. 35478ee8d1cSJulian Grajkowski * The size of this buffer in bytes (as 35578ee8d1cSJulian Grajkowski * represented by the dataLenInBytes field) 35678ee8d1cSJulian Grajkowski * MUST be at least big enough to store 35778ee8d1cSJulian Grajkowski * the public value, which may have a bit 35878ee8d1cSJulian Grajkowski * length up to that of pPrimeP. 35978ee8d1cSJulian Grajkowski * On invocation the callback function 36078ee8d1cSJulian Grajkowski * will contain this parameter in the 36178ee8d1cSJulian Grajkowski * pOut parameter. 36278ee8d1cSJulian Grajkowski * 36378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 36478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 36578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 36678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 36778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 36878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 36978ee8d1cSJulian Grajkowski * the request. 37078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 37178ee8d1cSJulian Grajkowski * 37278ee8d1cSJulian Grajkowski * @pre 37378ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 37478ee8d1cSJulian Grajkowski * @post 37578ee8d1cSJulian Grajkowski * None 37678ee8d1cSJulian Grajkowski * @note 37778ee8d1cSJulian Grajkowski * When pDhPhase2Cb is non-NULL an asynchronous callback of type 37878ee8d1cSJulian Grajkowski * CpaCyGenFlatBufCbFunc is generated in response to this function 37978ee8d1cSJulian Grajkowski * call. Any errors generated during processing are reported in the 38078ee8d1cSJulian Grajkowski * structure returned in the callback. 38178ee8d1cSJulian Grajkowski * 38278ee8d1cSJulian Grajkowski * @see 38378ee8d1cSJulian Grajkowski * CpaCyGenFlatBufCbFunc, 38478ee8d1cSJulian Grajkowski * CpaCyDhPhase2SecretKeyGenOpData 38578ee8d1cSJulian Grajkowski * 38678ee8d1cSJulian Grajkowski *****************************************************************************/ 38778ee8d1cSJulian Grajkowski CpaStatus 38878ee8d1cSJulian Grajkowski cpaCyDhKeyGenPhase2Secret(const CpaInstanceHandle instanceHandle, 38978ee8d1cSJulian Grajkowski const CpaCyGenFlatBufCbFunc pDhPhase2Cb, 39078ee8d1cSJulian Grajkowski void *pCallbackTag, 39178ee8d1cSJulian Grajkowski const CpaCyDhPhase2SecretKeyGenOpData *pPhase2SecretKeyGenData, 39278ee8d1cSJulian Grajkowski CpaFlatBuffer *pOctetStringSecretKey); 39378ee8d1cSJulian Grajkowski 39478ee8d1cSJulian Grajkowski /** 39578ee8d1cSJulian Grajkowski ***************************************************************************** 39678ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 39778ee8d1cSJulian Grajkowski * Query statistics for Diffie-Hellman operations 39878ee8d1cSJulian Grajkowski * 39978ee8d1cSJulian Grajkowski * @deprecated 40078ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this function has been deprecated, 40178ee8d1cSJulian Grajkowski * replaced by @ref cpaCyDhQueryStats64(). 40278ee8d1cSJulian Grajkowski * 40378ee8d1cSJulian Grajkowski * @description 40478ee8d1cSJulian Grajkowski * This function will query a specific Instance handle for Diffie- 40578ee8d1cSJulian Grajkowski * Hellman statistics. The user MUST allocate the CpaCyDhStats 40678ee8d1cSJulian Grajkowski * structure and pass the reference to that structure into this function 40778ee8d1cSJulian Grajkowski * call. This function writes the statistic results into the passed in 40878ee8d1cSJulian Grajkowski * CpaCyDhStats structure. 40978ee8d1cSJulian Grajkowski * 41078ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 41178ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 41278ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 41378ee8d1cSJulian Grajkowski * 41478ee8d1cSJulian Grajkowski * @context 41578ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 41678ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 41778ee8d1cSJulian Grajkowski * @assumptions 41878ee8d1cSJulian Grajkowski * None 41978ee8d1cSJulian Grajkowski * @sideEffects 42078ee8d1cSJulian Grajkowski * None 42178ee8d1cSJulian Grajkowski * @reentrant 42278ee8d1cSJulian Grajkowski * No 42378ee8d1cSJulian Grajkowski * @threadSafe 42478ee8d1cSJulian Grajkowski * Yes 42578ee8d1cSJulian Grajkowski * 42678ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 42778ee8d1cSJulian Grajkowski * @param[out] pDhStats Pointer to memory into which the statistics 42878ee8d1cSJulian Grajkowski * will be written. 42978ee8d1cSJulian Grajkowski * 43078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 43178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 43278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 43378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 43478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 43578ee8d1cSJulian Grajkowski * the request. 43678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 43778ee8d1cSJulian Grajkowski * 43878ee8d1cSJulian Grajkowski * @pre 43978ee8d1cSJulian Grajkowski * Component has been initialized. 44078ee8d1cSJulian Grajkowski * 44178ee8d1cSJulian Grajkowski * @post 44278ee8d1cSJulian Grajkowski * None 44378ee8d1cSJulian Grajkowski * @note 44478ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 44578ee8d1cSJulian Grajkowski * callback will be generated. 44678ee8d1cSJulian Grajkowski * @see 44778ee8d1cSJulian Grajkowski * CpaCyDhStats 44878ee8d1cSJulian Grajkowski *****************************************************************************/ 44978ee8d1cSJulian Grajkowski CpaStatus CPA_DEPRECATED 45078ee8d1cSJulian Grajkowski cpaCyDhQueryStats(const CpaInstanceHandle instanceHandle, 45178ee8d1cSJulian Grajkowski struct _CpaCyDhStats *pDhStats); 45278ee8d1cSJulian Grajkowski 45378ee8d1cSJulian Grajkowski /** 45478ee8d1cSJulian Grajkowski ***************************************************************************** 45578ee8d1cSJulian Grajkowski * @ingroup cpaCyDh 45678ee8d1cSJulian Grajkowski * Query statistics (64-bit version) for Diffie-Hellman operations 45778ee8d1cSJulian Grajkowski * 45878ee8d1cSJulian Grajkowski * @description 45978ee8d1cSJulian Grajkowski * This function will query a specific Instance handle for the 64-bit 46078ee8d1cSJulian Grajkowski * version of the Diffie-Hellman statistics. The user MUST allocate the 46178ee8d1cSJulian Grajkowski * CpaCyDhStats64 structure and pass the reference to that structure into 46278ee8d1cSJulian Grajkowski * this function call. This function writes the statistic results into 46378ee8d1cSJulian Grajkowski * the passed in CpaCyDhStats64 structure. 46478ee8d1cSJulian Grajkowski * 46578ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 46678ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 46778ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 46878ee8d1cSJulian Grajkowski * 46978ee8d1cSJulian Grajkowski * @context 47078ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 47178ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 47278ee8d1cSJulian Grajkowski * @assumptions 47378ee8d1cSJulian Grajkowski * None 47478ee8d1cSJulian Grajkowski * @sideEffects 47578ee8d1cSJulian Grajkowski * None 47678ee8d1cSJulian Grajkowski * @reentrant 47778ee8d1cSJulian Grajkowski * No 47878ee8d1cSJulian Grajkowski * @threadSafe 47978ee8d1cSJulian Grajkowski * Yes 48078ee8d1cSJulian Grajkowski * 48178ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 48278ee8d1cSJulian Grajkowski * @param[out] pDhStats Pointer to memory into which the statistics 48378ee8d1cSJulian Grajkowski * will be written. 48478ee8d1cSJulian Grajkowski * 48578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 48678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 48778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 48878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 48978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 49078ee8d1cSJulian Grajkowski * the request. 49178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 49278ee8d1cSJulian Grajkowski * 49378ee8d1cSJulian Grajkowski * @pre 49478ee8d1cSJulian Grajkowski * Component has been initialized. 49578ee8d1cSJulian Grajkowski * 49678ee8d1cSJulian Grajkowski * @post 49778ee8d1cSJulian Grajkowski * None 49878ee8d1cSJulian Grajkowski * @note 49978ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 50078ee8d1cSJulian Grajkowski * callback will be generated. 50178ee8d1cSJulian Grajkowski * @see 50278ee8d1cSJulian Grajkowski * CpaCyDhStats64 50378ee8d1cSJulian Grajkowski *****************************************************************************/ 50478ee8d1cSJulian Grajkowski CpaStatus 50578ee8d1cSJulian Grajkowski cpaCyDhQueryStats64(const CpaInstanceHandle instanceHandle, 50678ee8d1cSJulian Grajkowski CpaCyDhStats64 *pDhStats); 50778ee8d1cSJulian Grajkowski 50878ee8d1cSJulian Grajkowski /*****************************************************************************/ 50978ee8d1cSJulian Grajkowski 51078ee8d1cSJulian Grajkowski #ifdef __cplusplus 51178ee8d1cSJulian Grajkowski } /* close the extern "C" { */ 51278ee8d1cSJulian Grajkowski #endif 51378ee8d1cSJulian Grajkowski 51478ee8d1cSJulian Grajkowski #endif /* CPA_CY_DH_H */ 515