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_prime.h 4578ee8d1cSJulian Grajkowski * 4678ee8d1cSJulian Grajkowski * @defgroup cpaCyPrime Prime Number Test API 4778ee8d1cSJulian Grajkowski * 4878ee8d1cSJulian Grajkowski * @ingroup cpaCy 4978ee8d1cSJulian Grajkowski * 5078ee8d1cSJulian Grajkowski * @description 5178ee8d1cSJulian Grajkowski * These functions specify the API for the prime number test operations. 5278ee8d1cSJulian Grajkowski * 5378ee8d1cSJulian Grajkowski * For prime number generation, this API SHOULD be used in conjunction 5478ee8d1cSJulian Grajkowski * with the Deterministic Random Bit Generation API (@ref cpaCyDrbg). 5578ee8d1cSJulian Grajkowski * 5678ee8d1cSJulian Grajkowski * @note 5778ee8d1cSJulian Grajkowski * Large numbers are represented on the QuickAssist API as described 5878ee8d1cSJulian Grajkowski * in the Large Number API (@ref cpaCyLn). 5978ee8d1cSJulian Grajkowski * 6078ee8d1cSJulian Grajkowski * In addition, the bit length of large numbers passed to the API 6178ee8d1cSJulian Grajkowski * MUST NOT exceed 576 bits for Elliptic Curve operations. 6278ee8d1cSJulian Grajkowski *****************************************************************************/ 6378ee8d1cSJulian Grajkowski 6478ee8d1cSJulian Grajkowski #ifndef CPA_CY_PRIME_H 6578ee8d1cSJulian Grajkowski #define CPA_CY_PRIME_H 6678ee8d1cSJulian Grajkowski 6778ee8d1cSJulian Grajkowski #ifdef __cplusplus 6878ee8d1cSJulian Grajkowski extern "C" { 6978ee8d1cSJulian Grajkowski #endif 7078ee8d1cSJulian Grajkowski 7178ee8d1cSJulian Grajkowski #include "cpa_cy_common.h" 7278ee8d1cSJulian Grajkowski 7378ee8d1cSJulian Grajkowski /** 7478ee8d1cSJulian Grajkowski ***************************************************************************** 7578ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 7678ee8d1cSJulian Grajkowski * Prime Test Operation Data. 7778ee8d1cSJulian Grajkowski * @description 7878ee8d1cSJulian Grajkowski * This structure contains the operation data for the cpaCyPrimeTest 7978ee8d1cSJulian Grajkowski * function. The client MUST allocate the memory for this structure and the 8078ee8d1cSJulian Grajkowski * items pointed to by this structure. When the structure is passed into 8178ee8d1cSJulian Grajkowski * the function, ownership of the memory passes to the function. Ownership 8278ee8d1cSJulian Grajkowski * of the memory returns to the client when this structure is returned in 8378ee8d1cSJulian Grajkowski * the callback function. 8478ee8d1cSJulian Grajkowski * 8578ee8d1cSJulian Grajkowski * All values in this structure are required to be in Most Significant Byte 8678ee8d1cSJulian Grajkowski * first order, e.g. primeCandidate.pData[0] = MSB. 8778ee8d1cSJulian Grajkowski * 8878ee8d1cSJulian Grajkowski * All numbers MUST be stored in big-endian order. 8978ee8d1cSJulian Grajkowski * 9078ee8d1cSJulian Grajkowski * @note 9178ee8d1cSJulian Grajkowski * If the client modifies or frees the memory referenced in this 9278ee8d1cSJulian Grajkowski * structure after it has been submitted to the cpaCyPrimeTest 9378ee8d1cSJulian Grajkowski * function, and before it has been returned in the callback, undefined 9478ee8d1cSJulian Grajkowski * behavior will result. 9578ee8d1cSJulian Grajkowski * 9678ee8d1cSJulian Grajkowski * @see 9778ee8d1cSJulian Grajkowski * cpaCyPrimeTest() 9878ee8d1cSJulian Grajkowski * 9978ee8d1cSJulian Grajkowski *****************************************************************************/ 10078ee8d1cSJulian Grajkowski typedef struct _CpaCyPrimeTestOpData { 10178ee8d1cSJulian Grajkowski CpaFlatBuffer primeCandidate; 10278ee8d1cSJulian Grajkowski /**< The prime number candidate to test */ 10378ee8d1cSJulian Grajkowski CpaBoolean performGcdTest; 10478ee8d1cSJulian Grajkowski /**< A value of CPA_TRUE means perform a GCD Primality Test */ 10578ee8d1cSJulian Grajkowski CpaBoolean performFermatTest; 10678ee8d1cSJulian Grajkowski /**< A value of CPA_TRUE means perform a Fermat Primality Test */ 10778ee8d1cSJulian Grajkowski Cpa32U numMillerRabinRounds; 10878ee8d1cSJulian Grajkowski /**< Number of Miller Rabin Primality Test rounds. Set to 0 to perform 10978ee8d1cSJulian Grajkowski * zero Miller Rabin tests. The maximum number of rounds supported is 50. 11078ee8d1cSJulian Grajkowski */ 11178ee8d1cSJulian Grajkowski CpaFlatBuffer millerRabinRandomInput; 11278ee8d1cSJulian Grajkowski /**< Flat buffer containing a pointer to an array of n random numbers 11378ee8d1cSJulian Grajkowski * for Miller Rabin Primality Tests. The size of the buffer MUST be 11478ee8d1cSJulian Grajkowski * 11578ee8d1cSJulian Grajkowski * n * (MAX(64,x)) 11678ee8d1cSJulian Grajkowski * 11778ee8d1cSJulian Grajkowski * where: 11878ee8d1cSJulian Grajkowski * 11978ee8d1cSJulian Grajkowski * - n is the requested number of rounds. 12078ee8d1cSJulian Grajkowski * - x is the minimum number of bytes required to represent the prime 12178ee8d1cSJulian Grajkowski * candidate, i.e. x = ceiling((ceiling(log2(p)))/8). 12278ee8d1cSJulian Grajkowski * 12378ee8d1cSJulian Grajkowski * Each random number MUST be greater than 1 and less than the prime 12478ee8d1cSJulian Grajkowski * candidate - 1, with leading zeroes as necessary. 12578ee8d1cSJulian Grajkowski */ 12678ee8d1cSJulian Grajkowski CpaBoolean performLucasTest; 12778ee8d1cSJulian Grajkowski /**< An CPA_TRUE value means perform a Lucas Primality Test */ 12878ee8d1cSJulian Grajkowski } CpaCyPrimeTestOpData; 12978ee8d1cSJulian Grajkowski 13078ee8d1cSJulian Grajkowski /** 13178ee8d1cSJulian Grajkowski ***************************************************************************** 13278ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 13378ee8d1cSJulian Grajkowski * Prime Number Test Statistics. 13478ee8d1cSJulian Grajkowski * @deprecated 13578ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this structure has been deprecated, 13678ee8d1cSJulian Grajkowski * replaced by @ref CpaCyPrimeStats64. 13778ee8d1cSJulian Grajkowski * @description 13878ee8d1cSJulian Grajkowski * This structure contains statistics on the prime number test operations. 13978ee8d1cSJulian Grajkowski * Statistics are set to zero when the component is initialized, and are 14078ee8d1cSJulian Grajkowski * collected per instance. 14178ee8d1cSJulian Grajkowski * 14278ee8d1cSJulian Grajkowski ****************************************************************************/ 14378ee8d1cSJulian Grajkowski typedef struct _CpaCyPrimeStats { 14478ee8d1cSJulian Grajkowski Cpa32U numPrimeTestRequests; 14578ee8d1cSJulian Grajkowski /**< Total number of successful prime number test requests.*/ 14678ee8d1cSJulian Grajkowski Cpa32U numPrimeTestRequestErrors; 14778ee8d1cSJulian Grajkowski /**< Total number of prime number test requests that had an 14878ee8d1cSJulian Grajkowski * error and could not be processed. */ 14978ee8d1cSJulian Grajkowski Cpa32U numPrimeTestCompleted; 15078ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that completed 15178ee8d1cSJulian Grajkowski * successfully. */ 15278ee8d1cSJulian Grajkowski Cpa32U numPrimeTestCompletedErrors; 15378ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that could not be 15478ee8d1cSJulian Grajkowski * completed successfully due to errors. */ 15578ee8d1cSJulian Grajkowski Cpa32U numPrimeTestFailures; 15678ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that executed 15778ee8d1cSJulian Grajkowski * successfully but the outcome of the test was that the number was not 15878ee8d1cSJulian Grajkowski * prime. */ 15978ee8d1cSJulian Grajkowski } CpaCyPrimeStats CPA_DEPRECATED; 16078ee8d1cSJulian Grajkowski 16178ee8d1cSJulian Grajkowski /** 16278ee8d1cSJulian Grajkowski ***************************************************************************** 16378ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 16478ee8d1cSJulian Grajkowski * Prime Number Test Statistics (64-bit version). 16578ee8d1cSJulian Grajkowski * @description 16678ee8d1cSJulian Grajkowski * This structure contains a 64-bit version of the statistics on the 16778ee8d1cSJulian Grajkowski * prime number test operations. 16878ee8d1cSJulian Grajkowski * Statistics are set to zero when the component is initialized, and are 16978ee8d1cSJulian Grajkowski * collected per instance. 17078ee8d1cSJulian Grajkowski ****************************************************************************/ 17178ee8d1cSJulian Grajkowski typedef struct _CpaCyPrimeStats64 { 17278ee8d1cSJulian Grajkowski Cpa64U numPrimeTestRequests; 17378ee8d1cSJulian Grajkowski /**< Total number of successful prime number test requests.*/ 17478ee8d1cSJulian Grajkowski Cpa64U numPrimeTestRequestErrors; 17578ee8d1cSJulian Grajkowski /**< Total number of prime number test requests that had an 17678ee8d1cSJulian Grajkowski * error and could not be processed. */ 17778ee8d1cSJulian Grajkowski Cpa64U numPrimeTestCompleted; 17878ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that completed 17978ee8d1cSJulian Grajkowski * successfully. */ 18078ee8d1cSJulian Grajkowski Cpa64U numPrimeTestCompletedErrors; 18178ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that could not be 18278ee8d1cSJulian Grajkowski * completed successfully due to errors. */ 18378ee8d1cSJulian Grajkowski Cpa64U numPrimeTestFailures; 18478ee8d1cSJulian Grajkowski /**< Total number of prime number test operations that executed 18578ee8d1cSJulian Grajkowski * successfully but the outcome of the test was that the number was not 18678ee8d1cSJulian Grajkowski * prime. */ 18778ee8d1cSJulian Grajkowski } CpaCyPrimeStats64; 18878ee8d1cSJulian Grajkowski 18978ee8d1cSJulian Grajkowski /** 19078ee8d1cSJulian Grajkowski ***************************************************************************** 19178ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 19278ee8d1cSJulian Grajkowski * Definition of callback function invoked for cpaCyPrimeTest 19378ee8d1cSJulian Grajkowski * requests. 19478ee8d1cSJulian Grajkowski * 19578ee8d1cSJulian Grajkowski * @description 19678ee8d1cSJulian Grajkowski * This is the prototype for the cpaCyPrimeTest callback function. 19778ee8d1cSJulian Grajkowski * 19878ee8d1cSJulian Grajkowski * @context 19978ee8d1cSJulian Grajkowski * This callback function can be executed in a context that DOES NOT 20078ee8d1cSJulian Grajkowski * permit sleeping to occur. 20178ee8d1cSJulian Grajkowski * @assumptions 20278ee8d1cSJulian Grajkowski * None 20378ee8d1cSJulian Grajkowski * @sideEffects 20478ee8d1cSJulian Grajkowski * None 20578ee8d1cSJulian Grajkowski * @reentrant 20678ee8d1cSJulian Grajkowski * No 20778ee8d1cSJulian Grajkowski * @threadSafe 20878ee8d1cSJulian Grajkowski * Yes 20978ee8d1cSJulian Grajkowski * 21078ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 21178ee8d1cSJulian Grajkowski * @param[in] status Status of the operation. Valid values are 21278ee8d1cSJulian Grajkowski * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 21378ee8d1cSJulian Grajkowski * CPA_STATUS_UNSUPPORTED. 21478ee8d1cSJulian Grajkowski * @param[in] pOpData Opaque pointer to the Operation data pointer 21578ee8d1cSJulian Grajkowski * supplied in request. 21678ee8d1cSJulian Grajkowski * @param[in] testPassed A value of CPA_TRUE means the prime candidate 21778ee8d1cSJulian Grajkowski * is probably prime. 21878ee8d1cSJulian Grajkowski * 21978ee8d1cSJulian Grajkowski * @retval 22078ee8d1cSJulian Grajkowski * None 22178ee8d1cSJulian Grajkowski * @pre 22278ee8d1cSJulian Grajkowski * Component has been initialized. 22378ee8d1cSJulian Grajkowski * @post 22478ee8d1cSJulian Grajkowski * None 22578ee8d1cSJulian Grajkowski * @note 22678ee8d1cSJulian Grajkowski * None 22778ee8d1cSJulian Grajkowski * @see 22878ee8d1cSJulian Grajkowski * cpaCyPrimeTest() 22978ee8d1cSJulian Grajkowski * 23078ee8d1cSJulian Grajkowski *****************************************************************************/ 23178ee8d1cSJulian Grajkowski typedef void (*CpaCyPrimeTestCbFunc)(void *pCallbackTag, 23278ee8d1cSJulian Grajkowski CpaStatus status, 23378ee8d1cSJulian Grajkowski void *pOpData, 23478ee8d1cSJulian Grajkowski CpaBoolean testPassed); 23578ee8d1cSJulian Grajkowski 23678ee8d1cSJulian Grajkowski /** 23778ee8d1cSJulian Grajkowski ***************************************************************************** 23878ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 23978ee8d1cSJulian Grajkowski * Prime Number Test Function. 24078ee8d1cSJulian Grajkowski * 24178ee8d1cSJulian Grajkowski * @description 24278ee8d1cSJulian Grajkowski * This function will test probabilistically if a number is prime. Refer 24378ee8d1cSJulian Grajkowski * to ANSI X9.80 2005 for details. The primality result will be returned 24478ee8d1cSJulian Grajkowski * in the asynchronous callback. 24578ee8d1cSJulian Grajkowski * 24678ee8d1cSJulian Grajkowski * The following combination of GCD, Fermat, Miller-Rabin, and Lucas 24778ee8d1cSJulian Grajkowski * testing is supported: 24878ee8d1cSJulian Grajkowski * (up to 1x GCD) + (up to 1x Fermat) + (up to 50x Miller-Rabin rounds) + 24978ee8d1cSJulian Grajkowski * (up to 1x Lucas) 25078ee8d1cSJulian Grajkowski * For example: 25178ee8d1cSJulian Grajkowski * (1x GCD) + (25x Miller-Rabin) + (1x Lucas); 25278ee8d1cSJulian Grajkowski * (1x GCD) + (1x Fermat); 25378ee8d1cSJulian Grajkowski * (50x Miller-rabin); 25478ee8d1cSJulian Grajkowski * 25578ee8d1cSJulian Grajkowski * Tests are always performed in order of increasing complexity, for 25678ee8d1cSJulian Grajkowski * example GCD first, then Fermat, then Miller-Rabin, and finally Lucas. 25778ee8d1cSJulian Grajkowski * 25878ee8d1cSJulian Grajkowski * For all of the primality tests, the following prime number "sizes" 25978ee8d1cSJulian Grajkowski * (length in bits) are supported: all sizes up to and including 512 26078ee8d1cSJulian Grajkowski * bits, as well as sizes 768, 1024, 1536, 2048, 3072 and 4096. 26178ee8d1cSJulian Grajkowski * 26278ee8d1cSJulian Grajkowski * Candidate prime numbers MUST match these sizes accordingly, with 26378ee8d1cSJulian Grajkowski * leading zeroes present where necessary. 26478ee8d1cSJulian Grajkowski * 26578ee8d1cSJulian Grajkowski * When this prime number test is used in conjunction with combined 26678ee8d1cSJulian Grajkowski * Miller-Rabin and Lucas tests, it may be used as a means of performing 26778ee8d1cSJulian Grajkowski * a self test operation on the random data generator. 26878ee8d1cSJulian Grajkowski * 26978ee8d1cSJulian Grajkowski * A response status of ok (pass == CPA_TRUE) means all requested 27078ee8d1cSJulian Grajkowski * primality tests passed, and the prime candidate is probably prime 27178ee8d1cSJulian Grajkowski * (the exact probability depends on the primality tests requested). 27278ee8d1cSJulian Grajkowski * A response status of not ok (pass == CPA_FALSE) means one of the 27378ee8d1cSJulian Grajkowski * requested primality tests failed (the prime candidate has been found 27478ee8d1cSJulian Grajkowski * to be composite). 27578ee8d1cSJulian Grajkowski * @context 27678ee8d1cSJulian Grajkowski * When called as an asynchronous function it cannot sleep. It can be 27778ee8d1cSJulian Grajkowski * executed in a context that does not permit sleeping. 27878ee8d1cSJulian Grajkowski * When called as a synchronous function it may sleep. It MUST NOT be 27978ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 28078ee8d1cSJulian Grajkowski * @assumptions 28178ee8d1cSJulian Grajkowski * None 28278ee8d1cSJulian Grajkowski * @sideEffects 28378ee8d1cSJulian Grajkowski * None 28478ee8d1cSJulian Grajkowski * @blocking 28578ee8d1cSJulian Grajkowski * Yes when configured to operate in synchronous mode. 28678ee8d1cSJulian Grajkowski * @reentrant 28778ee8d1cSJulian Grajkowski * No 28878ee8d1cSJulian Grajkowski * @threadSafe 28978ee8d1cSJulian Grajkowski * Yes 29078ee8d1cSJulian Grajkowski * 29178ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 29278ee8d1cSJulian Grajkowski * @param[in] pCb Callback function pointer. If this is set to 29378ee8d1cSJulian Grajkowski * a NULL value the function will operate 29478ee8d1cSJulian Grajkowski * synchronously. 29578ee8d1cSJulian Grajkowski * @param[in] pCallbackTag User-supplied value to help identify request. 29678ee8d1cSJulian Grajkowski * @param[in] pOpData Structure containing all the data needed to 29778ee8d1cSJulian Grajkowski * perform the operation. The client code 29878ee8d1cSJulian Grajkowski * allocates the memory for this structure. This 29978ee8d1cSJulian Grajkowski * component takes ownership of the memory until 30078ee8d1cSJulian Grajkowski * it is returned in the callback. 30178ee8d1cSJulian Grajkowski * @param[out] pTestPassed A value of CPA_TRUE means the prime candidate 30278ee8d1cSJulian Grajkowski * is probably prime. 30378ee8d1cSJulian Grajkowski * 30478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 30578ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 30678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RETRY Resubmit the request. 30778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 30878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 30978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 31078ee8d1cSJulian Grajkowski * the request. 31178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 31278ee8d1cSJulian Grajkowski * 31378ee8d1cSJulian Grajkowski * @pre 31478ee8d1cSJulian Grajkowski * The component has been initialized via cpaCyStartInstance function. 31578ee8d1cSJulian Grajkowski * @post 31678ee8d1cSJulian Grajkowski * None 31778ee8d1cSJulian Grajkowski * @note 31878ee8d1cSJulian Grajkowski * When pCb is non-NULL an asynchronous callback of type 31978ee8d1cSJulian Grajkowski * CpaCyPrimeTestCbFunc is generated in response to this function call. 32078ee8d1cSJulian Grajkowski * For optimal performance, data pointers SHOULD be 8-byte aligned. 32178ee8d1cSJulian Grajkowski * 32278ee8d1cSJulian Grajkowski * @see 32378ee8d1cSJulian Grajkowski * CpaCyPrimeTestOpData, CpaCyPrimeTestCbFunc 32478ee8d1cSJulian Grajkowski * 32578ee8d1cSJulian Grajkowski *****************************************************************************/ 32678ee8d1cSJulian Grajkowski CpaStatus 32778ee8d1cSJulian Grajkowski cpaCyPrimeTest(const CpaInstanceHandle instanceHandle, 32878ee8d1cSJulian Grajkowski const CpaCyPrimeTestCbFunc pCb, 32978ee8d1cSJulian Grajkowski void *pCallbackTag, 33078ee8d1cSJulian Grajkowski const CpaCyPrimeTestOpData *pOpData, 33178ee8d1cSJulian Grajkowski CpaBoolean *pTestPassed); 33278ee8d1cSJulian Grajkowski 33378ee8d1cSJulian Grajkowski /****************************************************************************** 33478ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 33578ee8d1cSJulian Grajkowski * Query prime number statistics specific to an instance. 33678ee8d1cSJulian Grajkowski * 33778ee8d1cSJulian Grajkowski * @deprecated 33878ee8d1cSJulian Grajkowski * As of v1.3 of the Crypto API, this function has been deprecated, 33978ee8d1cSJulian Grajkowski * replaced by @ref cpaCyPrimeQueryStats64(). 34078ee8d1cSJulian Grajkowski * 34178ee8d1cSJulian Grajkowski * @description 34278ee8d1cSJulian Grajkowski * This function will query a specific instance for prime number 34378ee8d1cSJulian Grajkowski * statistics. The user MUST allocate the CpaCyPrimeStats structure 34478ee8d1cSJulian Grajkowski * and pass the reference to that into this function call. This function 34578ee8d1cSJulian Grajkowski * will write the statistic results into the passed in 34678ee8d1cSJulian Grajkowski * CpaCyPrimeStats structure. 34778ee8d1cSJulian Grajkowski * 34878ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 34978ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 35078ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 35178ee8d1cSJulian Grajkowski * 35278ee8d1cSJulian Grajkowski * @context 35378ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 35478ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 35578ee8d1cSJulian Grajkowski * @assumptions 35678ee8d1cSJulian Grajkowski * None 35778ee8d1cSJulian Grajkowski * @sideEffects 35878ee8d1cSJulian Grajkowski * None 35978ee8d1cSJulian Grajkowski * @blocking 36078ee8d1cSJulian Grajkowski * This function is synchronous and blocking. 36178ee8d1cSJulian Grajkowski * @reentrant 36278ee8d1cSJulian Grajkowski * No 36378ee8d1cSJulian Grajkowski * @threadSafe 36478ee8d1cSJulian Grajkowski * Yes 36578ee8d1cSJulian Grajkowski * 36678ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 36778ee8d1cSJulian Grajkowski * @param[out] pPrimeStats Pointer to memory into which the statistics 36878ee8d1cSJulian Grajkowski * will be written. 36978ee8d1cSJulian Grajkowski * 37078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 37178ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 37278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 37378ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 37478ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 37578ee8d1cSJulian Grajkowski * the request. 37678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 37778ee8d1cSJulian Grajkowski * 37878ee8d1cSJulian Grajkowski * @pre 37978ee8d1cSJulian Grajkowski * Component has been initialized. 38078ee8d1cSJulian Grajkowski * @post 38178ee8d1cSJulian Grajkowski * None 38278ee8d1cSJulian Grajkowski * @note 38378ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 38478ee8d1cSJulian Grajkowski * callback will be generated. 38578ee8d1cSJulian Grajkowski * 38678ee8d1cSJulian Grajkowski *****************************************************************************/ 38778ee8d1cSJulian Grajkowski CpaStatus CPA_DEPRECATED 38878ee8d1cSJulian Grajkowski cpaCyPrimeQueryStats(const CpaInstanceHandle instanceHandle, 38978ee8d1cSJulian Grajkowski struct _CpaCyPrimeStats *pPrimeStats); 39078ee8d1cSJulian Grajkowski 39178ee8d1cSJulian Grajkowski 39278ee8d1cSJulian Grajkowski /****************************************************************************** 39378ee8d1cSJulian Grajkowski * @ingroup cpaCyPrime 39478ee8d1cSJulian Grajkowski * Query prime number statistics specific to an instance. 39578ee8d1cSJulian Grajkowski * 39678ee8d1cSJulian Grajkowski * @description 39778ee8d1cSJulian Grajkowski * This function will query a specific instance for the 64-bit 39878ee8d1cSJulian Grajkowski * version of the prime number statistics. 39978ee8d1cSJulian Grajkowski * The user MUST allocate the CpaCyPrimeStats64 structure 40078ee8d1cSJulian Grajkowski * and pass the reference to that into this function call. This function 40178ee8d1cSJulian Grajkowski * will write the statistic results into the passed in 40278ee8d1cSJulian Grajkowski * CpaCyPrimeStats64 structure. 40378ee8d1cSJulian Grajkowski * 40478ee8d1cSJulian Grajkowski * Note: statistics returned by this function do not interrupt current data 40578ee8d1cSJulian Grajkowski * processing and as such can be slightly out of sync with operations that 40678ee8d1cSJulian Grajkowski * are in progress during the statistics retrieval process. 40778ee8d1cSJulian Grajkowski * 40878ee8d1cSJulian Grajkowski * @context 40978ee8d1cSJulian Grajkowski * This is a synchronous function and it can sleep. It MUST NOT be 41078ee8d1cSJulian Grajkowski * executed in a context that DOES NOT permit sleeping. 41178ee8d1cSJulian Grajkowski * @assumptions 41278ee8d1cSJulian Grajkowski * None 41378ee8d1cSJulian Grajkowski * @sideEffects 41478ee8d1cSJulian Grajkowski * None 41578ee8d1cSJulian Grajkowski * @blocking 41678ee8d1cSJulian Grajkowski * This function is synchronous and blocking. 41778ee8d1cSJulian Grajkowski * @reentrant 41878ee8d1cSJulian Grajkowski * No 41978ee8d1cSJulian Grajkowski * @threadSafe 42078ee8d1cSJulian Grajkowski * Yes 42178ee8d1cSJulian Grajkowski * 42278ee8d1cSJulian Grajkowski * @param[in] instanceHandle Instance handle. 42378ee8d1cSJulian Grajkowski * @param[out] pPrimeStats Pointer to memory into which the statistics 42478ee8d1cSJulian Grajkowski * will be written. 42578ee8d1cSJulian Grajkowski * 42678ee8d1cSJulian Grajkowski * @retval CPA_STATUS_SUCCESS Function executed successfully. 42778ee8d1cSJulian Grajkowski * @retval CPA_STATUS_FAIL Function failed. 42878ee8d1cSJulian Grajkowski * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 42978ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESOURCE Error related to system resources. 43078ee8d1cSJulian Grajkowski * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 43178ee8d1cSJulian Grajkowski * the request. 43278ee8d1cSJulian Grajkowski * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 43378ee8d1cSJulian Grajkowski * 43478ee8d1cSJulian Grajkowski * @pre 43578ee8d1cSJulian Grajkowski * Component has been initialized. 43678ee8d1cSJulian Grajkowski * @post 43778ee8d1cSJulian Grajkowski * None 43878ee8d1cSJulian Grajkowski * @note 43978ee8d1cSJulian Grajkowski * This function operates in a synchronous manner and no asynchronous 44078ee8d1cSJulian Grajkowski * callback will be generated. 44178ee8d1cSJulian Grajkowski *****************************************************************************/ 44278ee8d1cSJulian Grajkowski CpaStatus 44378ee8d1cSJulian Grajkowski cpaCyPrimeQueryStats64(const CpaInstanceHandle instanceHandle, 44478ee8d1cSJulian Grajkowski CpaCyPrimeStats64 *pPrimeStats); 44578ee8d1cSJulian Grajkowski 44678ee8d1cSJulian Grajkowski #ifdef __cplusplus 44778ee8d1cSJulian Grajkowski } /* close the extern "C" { */ 44878ee8d1cSJulian Grajkowski #endif 44978ee8d1cSJulian Grajkowski 45078ee8d1cSJulian Grajkowski #endif /* CPA_CY_PRIME_H */ 451