xref: /freebsd/sys/dev/qat/qat_api/include/lac/cpa_cy_ln.h (revision 266b0663)
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