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_ln.h 4578ee8d1cSJulian Grajkowski * 4678ee8d1cSJulian Grajkowski * @defgroup cpaCyLn Cryptographic Large Number API 4778ee8d1cSJulian Grajkowski * 4878ee8d1cSJulian Grajkowski * @ingroup cpaCy 4978ee8d1cSJulian Grajkowski * 5078ee8d1cSJulian Grajkowski * @description 5178ee8d1cSJulian Grajkowski * These functions specify the Cryptographic API for Large Number 5278ee8d1cSJulian Grajkowski * Operations. 5378ee8d1cSJulian Grajkowski * 5478ee8d1cSJulian Grajkowski * @note 5578ee8d1cSJulian Grajkowski * Large numbers are represented on the QuickAssist API using octet 5678ee8d1cSJulian Grajkowski * strings, stored in structures of type @ref CpaFlatBuffer. These 5778ee8d1cSJulian Grajkowski * octet strings are encoded as described by PKCS#1 v2.1, section 4, 5878ee8d1cSJulian Grajkowski * which is consistent with ASN.1 syntax. The following text 5978ee8d1cSJulian Grajkowski * summarizes this. Any exceptions to this encoding are specified 6078ee8d1cSJulian Grajkowski * on the specific data structure or function to which the exception 6178ee8d1cSJulian Grajkowski * applies. 6278ee8d1cSJulian Grajkowski * 6378ee8d1cSJulian Grajkowski * An n-bit number, N, has a value in the range 2^(n-1) through 2^(n)-1. 6478ee8d1cSJulian Grajkowski * In other words, its most significant bit, bit n-1 (where bit-counting 6578ee8d1cSJulian Grajkowski * starts from zero) MUST be set to 1. We can also state that the 6678ee8d1cSJulian Grajkowski * bit-length n of a number N is defined by n = floor(log2(N))+1. 6778ee8d1cSJulian Grajkowski * 6878ee8d1cSJulian Grajkowski * The buffer, b, in which an n-bit number N is stored, must be "large 6978ee8d1cSJulian Grajkowski * enough". In other words, b.dataLenInBytes must be at least 7078ee8d1cSJulian Grajkowski * minLenInBytes = ceiling(n/8). 7178ee8d1cSJulian Grajkowski * 7278ee8d1cSJulian Grajkowski * The number is stored in a "big endian" format. This means that the 7378ee8d1cSJulian Grajkowski * least significant byte (LSB) is b[b.dataLenInBytes-1], while the 7478ee8d1cSJulian Grajkowski * most significant byte (MSB) is b[b.dataLenInBytes-minLenInBytes]. 7578ee8d1cSJulian Grajkowski * In the case where the buffer is "exactly" the right size, then the 7678ee8d1cSJulian Grajkowski * MSB is b[0]. Otherwise, all bytes from b[0] up to the MSB MUST be 7778ee8d1cSJulian Grajkowski * set to 0x00. 7878ee8d1cSJulian Grajkowski * 79266b0663SKrzysztof Zdziarski * The largest bit-length we support today is 8192 bits. In other 80266b0663SKrzysztof Zdziarski * words, we can deal with numbers up to a value of (2^8192)-1. 8178ee8d1cSJulian Grajkowski * 8278ee8d1cSJulian Grajkowski *****************************************************************************/ 8378ee8d1cSJulian Grajkowski 8478ee8d1cSJulian Grajkowski #ifndef CPA_CY_LN_H 8578ee8d1cSJulian Grajkowski #define CPA_CY_LN_H 8678ee8d1cSJulian Grajkowski 8778ee8d1cSJulian Grajkowski #ifdef __cplusplus 8878ee8d1cSJulian Grajkowski extern "C" { 8978ee8d1cSJulian Grajkowski #endif 9078ee8d1cSJulian Grajkowski 9178ee8d1cSJulian Grajkowski #include "cpa_cy_common.h" 9278ee8d1cSJulian Grajkowski 9378ee8d1cSJulian Grajkowski /** 9478ee8d1cSJulian Grajkowski ***************************************************************************** 9578ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 9678ee8d1cSJulian Grajkowski * Modular Exponentiation Function Operation Data. 9778ee8d1cSJulian Grajkowski * @description 9878ee8d1cSJulian Grajkowski * This structure lists the different items that are required in the 9978ee8d1cSJulian Grajkowski * cpaCyLnModExp function. The client MUST allocate the memory for 10078ee8d1cSJulian Grajkowski * this structure. When the structure is passed into the function, 10178ee8d1cSJulian Grajkowski * ownership of the memory passes to the function. Ownership of the memory 10278ee8d1cSJulian Grajkowski * returns to the client when this structure is returned in the callback. 10378ee8d1cSJulian Grajkowski * The operation size in bits is equal to the size of whichever of the 10478ee8d1cSJulian Grajkowski * following is largest: the modulus, the base or the exponent. 10578ee8d1cSJulian Grajkowski * 10678ee8d1cSJulian Grajkowski * @note 10778ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this structure 10878ee8d1cSJulian Grajkowski * after it has been submitted to the cpaCyLnModExp function, and 10978ee8d1cSJulian Grajkowski * before it has been returned in the callback, undefined behavior will 11078ee8d1cSJulian Grajkowski * result. 11178ee8d1cSJulian Grajkowski 11278ee8d1cSJulian Grajkowski * The values of the base, the exponent and the modulus MUST all be less 113266b0663SKrzysztof Zdziarski * than 2^8192, and the modulus must not be equal to zero. 11478ee8d1cSJulian Grajkowski *****************************************************************************/ 11578ee8d1cSJulian Grajkowski typedef struct _CpaCyLnModExpOpData { 11678ee8d1cSJulian Grajkowski CpaFlatBuffer modulus; 11778ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the modulus. 118266b0663SKrzysztof Zdziarski * This number may be up to 8192 bits in length, and MUST be greater 11978ee8d1cSJulian Grajkowski * than zero. 12078ee8d1cSJulian Grajkowski */ 12178ee8d1cSJulian Grajkowski CpaFlatBuffer base; 12278ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the base. 123266b0663SKrzysztof Zdziarski * This number may be up to 8192 bits in length. 12478ee8d1cSJulian Grajkowski */ 12578ee8d1cSJulian Grajkowski CpaFlatBuffer exponent; 12678ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the exponent. 127266b0663SKrzysztof Zdziarski * This number may be up to 8192 bits in length. 12878ee8d1cSJulian Grajkowski */ 12978ee8d1cSJulian Grajkowski } CpaCyLnModExpOpData; 13078ee8d1cSJulian Grajkowski 13178ee8d1cSJulian Grajkowski /** 13278ee8d1cSJulian Grajkowski ***************************************************************************** 13378ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 13478ee8d1cSJulian Grajkowski * Modular Inversion Function Operation Data. 13578ee8d1cSJulian Grajkowski * @description 13678ee8d1cSJulian Grajkowski * This structure lists the different items that are required in the 13778ee8d1cSJulian Grajkowski * function @ref cpaCyLnModInv. The client MUST allocate the memory for 13878ee8d1cSJulian Grajkowski * this structure. When the structure is passed into the function, 13978ee8d1cSJulian Grajkowski * ownership of the memory passes to the function. Ownership of the 14078ee8d1cSJulian Grajkowski * memory returns to the client when this structure is returned in the 14178ee8d1cSJulian Grajkowski * callback. 14278ee8d1cSJulian Grajkowski * @note 14378ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this structure 14478ee8d1cSJulian Grajkowski * after it has been submitted to the cpaCyLnModInv function, and 14578ee8d1cSJulian Grajkowski * before it has been returned in the callback, undefined behavior will 14678ee8d1cSJulian Grajkowski * result. 14778ee8d1cSJulian Grajkowski * 14878ee8d1cSJulian Grajkowski * Note that the values of A and B MUST NOT both be even numbers, and 149266b0663SKrzysztof Zdziarski * both MUST be less than 2^8192. 15078ee8d1cSJulian Grajkowski *****************************************************************************/ 15178ee8d1cSJulian Grajkowski typedef struct _CpaCyLnModInvOpData { 15278ee8d1cSJulian Grajkowski CpaFlatBuffer A; 15378ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the value that will be 15478ee8d1cSJulian Grajkowski * inverted. 155266b0663SKrzysztof Zdziarski * This number may be up to 8192 bits in length, it MUST NOT be zero, 15678ee8d1cSJulian Grajkowski * and it MUST be co-prime with B. 15778ee8d1cSJulian Grajkowski */ 15878ee8d1cSJulian Grajkowski CpaFlatBuffer B; 15978ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to the value that will be used as 16078ee8d1cSJulian Grajkowski * the modulus. 161266b0663SKrzysztof Zdziarski * This number may be up to 8192 bits in length, it MUST NOT be zero, 16278ee8d1cSJulian Grajkowski * and it MUST be co-prime with A. 16378ee8d1cSJulian Grajkowski */ 16478ee8d1cSJulian Grajkowski } CpaCyLnModInvOpData; 16578ee8d1cSJulian Grajkowski 16678ee8d1cSJulian Grajkowski /** 16778ee8d1cSJulian Grajkowski ***************************************************************************** 16878ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 16978ee8d1cSJulian Grajkowski * Look Aside Cryptographic large number Statistics. 17078ee8d1cSJulian Grajkowski * @deprecated 17178ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this structure has been deprecated, 17278ee8d1cSJulian Grajkowski * replaced by @ref CpaCyLnStats64. 17378ee8d1cSJulian Grajkowski * @description 17478ee8d1cSJulian Grajkowski * This structure contains statistics on the Look Aside Cryptographic 17578ee8d1cSJulian Grajkowski * large number operations. Statistics are set to zero when the component 17678ee8d1cSJulian Grajkowski * is initialized, and are collected per instance. 17778ee8d1cSJulian Grajkowski * 17878ee8d1cSJulian Grajkowski ****************************************************************************/ 17978ee8d1cSJulian Grajkowski typedef struct _CpaCyLnStats { 18078ee8d1cSJulian Grajkowski Cpa32U numLnModExpRequests; 18178ee8d1cSJulian Grajkowski /**< Total number of successful large number modular exponentiation 18278ee8d1cSJulian Grajkowski * requests.*/ 18378ee8d1cSJulian Grajkowski Cpa32U numLnModExpRequestErrors; 18478ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation requests that 18578ee8d1cSJulian Grajkowski * had an error and could not be processed. */ 18678ee8d1cSJulian Grajkowski Cpa32U numLnModExpCompleted; 18778ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation operations 18878ee8d1cSJulian Grajkowski * that completed successfully. */ 18978ee8d1cSJulian Grajkowski Cpa32U numLnModExpCompletedErrors; 19078ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation operations 19178ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 19278ee8d1cSJulian Grajkowski Cpa32U numLnModInvRequests; 19378ee8d1cSJulian Grajkowski /**< Total number of successful large number modular inversion 19478ee8d1cSJulian Grajkowski * requests.*/ 19578ee8d1cSJulian Grajkowski Cpa32U numLnModInvRequestErrors; 19678ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion requests that 19778ee8d1cSJulian Grajkowski * had an error and could not be processed. */ 19878ee8d1cSJulian Grajkowski Cpa32U numLnModInvCompleted; 19978ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion operations 20078ee8d1cSJulian Grajkowski * that completed successfully. */ 20178ee8d1cSJulian Grajkowski Cpa32U numLnModInvCompletedErrors; 20278ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion operations 20378ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 20478ee8d1cSJulian Grajkowski } CpaCyLnStats CPA_DEPRECATED; 20578ee8d1cSJulian Grajkowski 20678ee8d1cSJulian Grajkowski /** 20778ee8d1cSJulian Grajkowski ***************************************************************************** 20878ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 20978ee8d1cSJulian Grajkowski * Look Aside Cryptographic large number Statistics. 21078ee8d1cSJulian Grajkowski * @description 21178ee8d1cSJulian Grajkowski * This structure contains statistics on the Look Aside Cryptographic 21278ee8d1cSJulian Grajkowski * large number operations. Statistics are set to zero when the component 21378ee8d1cSJulian Grajkowski * is initialized, and are collected per instance. 21478ee8d1cSJulian Grajkowski * 21578ee8d1cSJulian Grajkowski ****************************************************************************/ 21678ee8d1cSJulian Grajkowski typedef struct _CpaCyLnStats64 { 21778ee8d1cSJulian Grajkowski Cpa64U numLnModExpRequests; 21878ee8d1cSJulian Grajkowski /**< Total number of successful large number modular exponentiation 21978ee8d1cSJulian Grajkowski * requests.*/ 22078ee8d1cSJulian Grajkowski Cpa64U numLnModExpRequestErrors; 22178ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation requests that 22278ee8d1cSJulian Grajkowski * had an error and could not be processed. */ 22378ee8d1cSJulian Grajkowski Cpa64U numLnModExpCompleted; 22478ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation operations 22578ee8d1cSJulian Grajkowski * that completed successfully. */ 22678ee8d1cSJulian Grajkowski Cpa64U numLnModExpCompletedErrors; 22778ee8d1cSJulian Grajkowski /**< Total number of large number modular exponentiation operations 22878ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 22978ee8d1cSJulian Grajkowski Cpa64U numLnModInvRequests; 23078ee8d1cSJulian Grajkowski /**< Total number of successful large number modular inversion 23178ee8d1cSJulian Grajkowski * requests.*/ 23278ee8d1cSJulian Grajkowski Cpa64U numLnModInvRequestErrors; 23378ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion requests that 23478ee8d1cSJulian Grajkowski * had an error and could not be processed. */ 23578ee8d1cSJulian Grajkowski Cpa64U numLnModInvCompleted; 23678ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion operations 23778ee8d1cSJulian Grajkowski * that completed successfully. */ 23878ee8d1cSJulian Grajkowski Cpa64U numLnModInvCompletedErrors; 23978ee8d1cSJulian Grajkowski /**< Total number of large number modular inversion operations 24078ee8d1cSJulian Grajkowski * that could not be completed successfully due to errors. */ 24178ee8d1cSJulian Grajkowski } CpaCyLnStats64; 24278ee8d1cSJulian Grajkowski 24378ee8d1cSJulian Grajkowski /** 24478ee8d1cSJulian Grajkowski ***************************************************************************** 24578ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 24678ee8d1cSJulian Grajkowski * Perform modular exponentiation operation. 24778ee8d1cSJulian Grajkowski * 24878ee8d1cSJulian Grajkowski * @description 24978ee8d1cSJulian Grajkowski * This function performs modular exponentiation. It computes the 25078ee8d1cSJulian Grajkowski * following result based on the inputs: 25178ee8d1cSJulian Grajkowski * 25278ee8d1cSJulian Grajkowski * result = (base ^ exponent) mod modulus 25378ee8d1cSJulian Grajkowski * 25478ee8d1cSJulian Grajkowski * @context 25578ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 25678ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 25778ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 25878ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 25978ee8d1cSJulian Grajkowski * @assumptions 26078ee8d1cSJulian Grajkowski * None 26178ee8d1cSJulian Grajkowski * @sideEffects 26278ee8d1cSJulian Grajkowski * None 26378ee8d1cSJulian Grajkowski * @reentrant 26478ee8d1cSJulian Grajkowski * No 26578ee8d1cSJulian Grajkowski * @threadSafe 26678ee8d1cSJulian Grajkowski * Yes 26778ee8d1cSJulian Grajkowski * 26878ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 26978ee8d1cSJulian Grajkowski * @param[in] pLnModExpCb Pointer to callback function to be 27078ee8d1cSJulian Grajkowski * invoked when the operation is complete. 27178ee8d1cSJulian Grajkowski * @param[in] pCallbackTag Opaque User Data for this specific call. 27278ee8d1cSJulian Grajkowski * Will be returned unchanged in the callback. 27378ee8d1cSJulian Grajkowski * @param[in] pLnModExpOpData Structure containing all the data needed 27478ee8d1cSJulian Grajkowski * to perform the LN modular exponentiation 27578ee8d1cSJulian Grajkowski * operation. The client code allocates 27678ee8d1cSJulian Grajkowski * the memory for this structure. This 27778ee8d1cSJulian Grajkowski * component takes ownership of the memory 27878ee8d1cSJulian Grajkowski * until it is returned in the callback. 27978ee8d1cSJulian Grajkowski * @param[out] pResult Pointer to a flat buffer containing a 28078ee8d1cSJulian Grajkowski * pointer to memory allocated by the client 28178ee8d1cSJulian Grajkowski * into which the result will be written. 28278ee8d1cSJulian Grajkowski * The size of the memory required MUST be 28378ee8d1cSJulian Grajkowski * larger than or equal to the size 28478ee8d1cSJulian Grajkowski * required to store the modulus. 28578ee8d1cSJulian Grajkowski * On invocation the callback function 28678ee8d1cSJulian Grajkowski * will contain this parameter in the 28778ee8d1cSJulian Grajkowski * pOut parameter. 28878ee8d1cSJulian Grajkowski * 28978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 29078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 29178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 29278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 29378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 29478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 29578ee8d1cSJulian Grajkowski * the request. 29678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 29778ee8d1cSJulian Grajkowski * 29878ee8d1cSJulian Grajkowski * @pre 29978ee8d1cSJulian Grajkowski * The component has been initialized. 30078ee8d1cSJulian Grajkowski * @post 30178ee8d1cSJulian Grajkowski * None 30278ee8d1cSJulian Grajkowski * @note 30378ee8d1cSJulian Grajkowski * When pLnModExpCb is non null, an asynchronous callback of type 30478ee8d1cSJulian Grajkowski * CpaCyLnModExpCbFunc is generated in response to this function call. 30578ee8d1cSJulian Grajkowski * Any errors generated during processing are reported in the structure 30678ee8d1cSJulian Grajkowski * returned in the callback. 30778ee8d1cSJulian Grajkowski * 30878ee8d1cSJulian Grajkowski * @see 30978ee8d1cSJulian Grajkowski * CpaCyLnModExpOpData, CpaCyGenFlatBufCbFunc 31078ee8d1cSJulian Grajkowski * 31178ee8d1cSJulian Grajkowski *****************************************************************************/ 31278ee8d1cSJulian Grajkowski CpaStatus 31378ee8d1cSJulian Grajkowski cpaCyLnModExp(const CpaInstanceHandle instanceHandle, 31478ee8d1cSJulian Grajkowski const CpaCyGenFlatBufCbFunc pLnModExpCb, 31578ee8d1cSJulian Grajkowski void *pCallbackTag, 31678ee8d1cSJulian Grajkowski const CpaCyLnModExpOpData *pLnModExpOpData, 31778ee8d1cSJulian Grajkowski CpaFlatBuffer *pResult); 31878ee8d1cSJulian Grajkowski 31978ee8d1cSJulian Grajkowski /** 32078ee8d1cSJulian Grajkowski ***************************************************************************** 32178ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 32278ee8d1cSJulian Grajkowski * Perform modular inversion operation. 32378ee8d1cSJulian Grajkowski * 32478ee8d1cSJulian Grajkowski * @description 32578ee8d1cSJulian Grajkowski * This function performs modular inversion. It computes the following 32678ee8d1cSJulian Grajkowski * result based on the inputs: 32778ee8d1cSJulian Grajkowski * 32878ee8d1cSJulian Grajkowski * result = (1/A) mod B. 32978ee8d1cSJulian Grajkowski * 33078ee8d1cSJulian Grajkowski * @context 33178ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 33278ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 33378ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 33478ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 33578ee8d1cSJulian Grajkowski * @assumptions 33678ee8d1cSJulian Grajkowski * None 33778ee8d1cSJulian Grajkowski * @sideEffects 33878ee8d1cSJulian Grajkowski * None 33978ee8d1cSJulian Grajkowski * @reentrant 34078ee8d1cSJulian Grajkowski * No 34178ee8d1cSJulian Grajkowski * @threadSafe 34278ee8d1cSJulian Grajkowski * Yes 34378ee8d1cSJulian Grajkowski * 34478ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 34578ee8d1cSJulian Grajkowski * @param[in] pLnModInvCb Pointer to callback function to be 34678ee8d1cSJulian Grajkowski * invoked when the operation is complete. 34778ee8d1cSJulian Grajkowski * @param[in] pCallbackTag Opaque User Data for this specific call. 34878ee8d1cSJulian Grajkowski * Will be returned unchanged in the 34978ee8d1cSJulian Grajkowski * callback. 35078ee8d1cSJulian Grajkowski * @param[in] pLnModInvOpData Structure containing all the data 35178ee8d1cSJulian Grajkowski * needed to perform the LN modular 35278ee8d1cSJulian Grajkowski * inversion operation. The client code 35378ee8d1cSJulian Grajkowski * allocates the memory for this structure. 35478ee8d1cSJulian Grajkowski * This component takes ownership of the 35578ee8d1cSJulian Grajkowski * memory until it is returned in the 35678ee8d1cSJulian Grajkowski * callback. 35778ee8d1cSJulian Grajkowski * @param[out] pResult Pointer to a flat buffer containing a 35878ee8d1cSJulian Grajkowski * pointer to memory allocated by the client 35978ee8d1cSJulian Grajkowski * into which the result will be written. 36078ee8d1cSJulian Grajkowski * The size of the memory required MUST be 36178ee8d1cSJulian Grajkowski * larger than or equal to the size 36278ee8d1cSJulian Grajkowski * required to store the modulus. 36378ee8d1cSJulian Grajkowski * On invocation the callback function 36478ee8d1cSJulian Grajkowski * will contain this parameter in the 36578ee8d1cSJulian Grajkowski * pOut parameter. 36678ee8d1cSJulian Grajkowski * 36778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 36878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 36978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 37078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 37178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 37278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 37378ee8d1cSJulian Grajkowski * the request. 37478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 37578ee8d1cSJulian Grajkowski * 37678ee8d1cSJulian Grajkowski * @pre 37778ee8d1cSJulian Grajkowski * The component has been initialized. 37878ee8d1cSJulian Grajkowski * @post 37978ee8d1cSJulian Grajkowski * None 38078ee8d1cSJulian Grajkowski * @note 38178ee8d1cSJulian Grajkowski * When pLnModInvCb is non null, an asynchronous callback of type 38278ee8d1cSJulian Grajkowski * CpaCyLnModInvCbFunc is generated in response to this function call. 38378ee8d1cSJulian Grajkowski * Any errors generated during processing are reported in the structure 38478ee8d1cSJulian Grajkowski * returned in the callback. 38578ee8d1cSJulian Grajkowski * 38678ee8d1cSJulian Grajkowski * @see 38778ee8d1cSJulian Grajkowski * CpaCyLnModInvOpData, 38878ee8d1cSJulian Grajkowski * CpaCyGenFlatBufCbFunc 38978ee8d1cSJulian Grajkowski * 39078ee8d1cSJulian Grajkowski *****************************************************************************/ 39178ee8d1cSJulian Grajkowski CpaStatus 39278ee8d1cSJulian Grajkowski cpaCyLnModInv(const CpaInstanceHandle instanceHandle, 39378ee8d1cSJulian Grajkowski const CpaCyGenFlatBufCbFunc pLnModInvCb, 39478ee8d1cSJulian Grajkowski void *pCallbackTag, 39578ee8d1cSJulian Grajkowski const CpaCyLnModInvOpData *pLnModInvOpData, 39678ee8d1cSJulian Grajkowski CpaFlatBuffer *pResult); 39778ee8d1cSJulian Grajkowski 39878ee8d1cSJulian Grajkowski /** 39978ee8d1cSJulian Grajkowski ***************************************************************************** 40078ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 40178ee8d1cSJulian Grajkowski * Query statistics for large number operations 40278ee8d1cSJulian Grajkowski * 40378ee8d1cSJulian Grajkowski * @deprecated 40478ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this function has been deprecated, 40578ee8d1cSJulian Grajkowski * replaced by @ref cpaCyLnStatsQuery64(). 40678ee8d1cSJulian Grajkowski * 40778ee8d1cSJulian Grajkowski * @description 40878ee8d1cSJulian Grajkowski * This function will query a specific instance handle for large number 40978ee8d1cSJulian Grajkowski * statistics. The user MUST allocate the CpaCyLnStats structure and pass 41078ee8d1cSJulian Grajkowski * the reference to that structure into this function call. This function 41178ee8d1cSJulian Grajkowski * writes the statistic results into the passed in CpaCyLnStats structure. 41278ee8d1cSJulian Grajkowski * 41378ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 41478ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 41578ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 41678ee8d1cSJulian Grajkowski * 41778ee8d1cSJulian Grajkowski * @context 41878ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 41978ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 42078ee8d1cSJulian Grajkowski * @assumptions 42178ee8d1cSJulian Grajkowski * None 42278ee8d1cSJulian Grajkowski * @sideEffects 42378ee8d1cSJulian Grajkowski * None 42478ee8d1cSJulian Grajkowski * @reentrant 42578ee8d1cSJulian Grajkowski * No 42678ee8d1cSJulian Grajkowski * @threadSafe 42778ee8d1cSJulian Grajkowski * Yes 42878ee8d1cSJulian Grajkowski * 42978ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 43078ee8d1cSJulian Grajkowski * @param[out] pLnStats Pointer to memory into which the 43178ee8d1cSJulian Grajkowski * statistics will be written. 43278ee8d1cSJulian Grajkowski * 43378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 43478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 43578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 43678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 43778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 43878ee8d1cSJulian Grajkowski * the request. 43978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 44078ee8d1cSJulian Grajkowski * 44178ee8d1cSJulian Grajkowski * @pre 44278ee8d1cSJulian Grajkowski * Acceleration Services unit has been initialized. 44378ee8d1cSJulian Grajkowski * 44478ee8d1cSJulian Grajkowski * @post 44578ee8d1cSJulian Grajkowski * None 44678ee8d1cSJulian Grajkowski * @note 44778ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 44878ee8d1cSJulian Grajkowski * callback will be generated. 44978ee8d1cSJulian Grajkowski * 45078ee8d1cSJulian Grajkowski * @see 45178ee8d1cSJulian Grajkowski * CpaCyLnStats 45278ee8d1cSJulian Grajkowski * 45378ee8d1cSJulian Grajkowski *****************************************************************************/ 45478ee8d1cSJulian Grajkowski CpaStatus CPA_DEPRECATED 45578ee8d1cSJulian Grajkowski cpaCyLnStatsQuery(const CpaInstanceHandle instanceHandle, 45678ee8d1cSJulian Grajkowski struct _CpaCyLnStats *pLnStats); 45778ee8d1cSJulian Grajkowski 45878ee8d1cSJulian Grajkowski /** 45978ee8d1cSJulian Grajkowski ***************************************************************************** 46078ee8d1cSJulian Grajkowski * @ingroup cpaCyLn 46178ee8d1cSJulian Grajkowski * Query statistics (64-bit version) for large number operations 46278ee8d1cSJulian Grajkowski * 46378ee8d1cSJulian Grajkowski * @description 46478ee8d1cSJulian Grajkowski * This function will query a specific instance handle for the 64-bit 46578ee8d1cSJulian Grajkowski * version of the large number statistics. 46678ee8d1cSJulian Grajkowski * The user MUST allocate the CpaCyLnStats64 structure and pass 46778ee8d1cSJulian Grajkowski * the reference to that structure into this function call. This function 46878ee8d1cSJulian Grajkowski * writes the statistic results into the passed in CpaCyLnStats64 46978ee8d1cSJulian Grajkowski * structure. 47078ee8d1cSJulian Grajkowski * 47178ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 47278ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 47378ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 47478ee8d1cSJulian Grajkowski * 47578ee8d1cSJulian Grajkowski * @context 47678ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 47778ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 47878ee8d1cSJulian Grajkowski * @assumptions 47978ee8d1cSJulian Grajkowski * None 48078ee8d1cSJulian Grajkowski * @sideEffects 48178ee8d1cSJulian Grajkowski * None 48278ee8d1cSJulian Grajkowski * @reentrant 48378ee8d1cSJulian Grajkowski * No 48478ee8d1cSJulian Grajkowski * @threadSafe 48578ee8d1cSJulian Grajkowski * Yes 48678ee8d1cSJulian Grajkowski * 48778ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 48878ee8d1cSJulian Grajkowski * @param[out] pLnStats Pointer to memory into which the 48978ee8d1cSJulian Grajkowski * statistics will be written. 49078ee8d1cSJulian Grajkowski * 49178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 49278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 49378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 49478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 49578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 49678ee8d1cSJulian Grajkowski * the request. 49778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 49878ee8d1cSJulian Grajkowski * 49978ee8d1cSJulian Grajkowski * @pre 50078ee8d1cSJulian Grajkowski * Acceleration Services unit has been initialized. 50178ee8d1cSJulian Grajkowski * 50278ee8d1cSJulian Grajkowski * @post 50378ee8d1cSJulian Grajkowski * None 50478ee8d1cSJulian Grajkowski * @note 50578ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 50678ee8d1cSJulian Grajkowski * callback will be generated. 50778ee8d1cSJulian Grajkowski * 50878ee8d1cSJulian Grajkowski * @see 50978ee8d1cSJulian Grajkowski * CpaCyLnStats 51078ee8d1cSJulian Grajkowski *****************************************************************************/ 51178ee8d1cSJulian Grajkowski CpaStatus 51278ee8d1cSJulian Grajkowski cpaCyLnStatsQuery64(const CpaInstanceHandle instanceHandle, 51378ee8d1cSJulian Grajkowski CpaCyLnStats64 *pLnStats); 51478ee8d1cSJulian Grajkowski 51578ee8d1cSJulian Grajkowski #ifdef __cplusplus 51678ee8d1cSJulian Grajkowski } /* close the extern "C" { */ 51778ee8d1cSJulian Grajkowski #endif 51878ee8d1cSJulian Grajkowski 51978ee8d1cSJulian Grajkowski #endif /* CPA_CY_LN_H */ 520