xref: /freebsd/sys/dev/qat/qat_api/include/lac/cpa_cy_dsa.h (revision 2542189532b3025577fa4e782904494f3587008b)
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /* Copyright(c) 2007-2025 Intel Corporation */
3 
4 /*
5  *****************************************************************************
6  * Doxygen group definitions
7  ****************************************************************************/
8 
9 /**
10  *****************************************************************************
11  * @file cpa_cy_dsa.h
12  *
13  * @defgroup cpaCyDsa Digital Signature Algorithm (DSA) API
14  *
15  * @ingroup cpaCy
16  *
17  * @description
18  *      These functions specify the API for Public Key Encryption
19  *      (Cryptography) Digital Signature Algorithm (DSA) operations.
20  *
21  *      Support is provided for FIPS PUB 186-2 with Change Notice 1
22  *      specification, and optionally for FIPS PUB 186-3.  If an
23  *      implementation does not support FIPS PUB 186-3, then the
24  *      corresponding functions may return a status of @ref
25  *      CPA_STATUS_FAIL.
26  *
27  *      Support for FIPS PUB 186-2 with Change Notice 1 implies supporting
28  *      the following choice for the pair L and N:
29  *      - L = 1024, N = 160
30  *
31  *      Support for FIPS PUB 186-3 implies supporting the following choices
32  *      for the pair L and N:
33  *
34  *      - L = 1024, N = 160
35  *      - L = 2048, N = 224
36  *      - L = 2048, N = 256
37  *      - L = 3072, N = 256
38  *
39  *      Only the modular math aspects of DSA parameter generation and message
40  *      signature generation and verification are implemented here.  For full
41  *      DSA support, this DSA API SHOULD be used in conjunction with other
42  *      parts of this overall Cryptographic API. In particular the Symmetric
43  *      functions (for hashing), the Random Number Generation functions, and
44  *      the Prime Number Test functions will be required.
45  *
46  * @note
47  *      Large numbers are represented on the QuickAssist API as described
48  *      in the Large Number API (@ref cpaCyLn).
49  *****************************************************************************/
50 
51 #ifndef CPA_CY_DSA_H
52 #define CPA_CY_DSA_H
53 
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57 
58 #include "cpa_cy_common.h"
59 
60 /**
61  *****************************************************************************
62  * @ingroup cpaCyDsa
63  *      DSA P Parameter Generation Operation Data.
64  * @description
65  *      This structure contains the operation data for the cpaCyDsaGenPParam
66  *      function. The client MUST allocate the memory for this structure and the
67  *      items pointed to by this structure. When the structure is passed into
68  *      the function, ownership of the memory passes to the function. Ownership
69  *      of the memory returns to the client when this structure is returned in
70  *      the callback function.
71  *
72  *      For optimal performance all data buffers SHOULD be 8-byte aligned.
73  *
74  *      All values in this structure are required to be in Most Significant Byte
75  *      first order, e.g. X.pData[0] = MSB.
76  *
77  * @note
78  *      If the client modifies or frees the memory referenced in this
79  *      structure after it has been submitted to the cpaCyDsaGenPParam
80  *      function, and before it has been returned in the callback, undefined
81  *      behavior will result.
82  *
83  * @see
84  *      cpaCyDsaGenPParam()
85  *
86  *****************************************************************************/
87 typedef struct _CpaCyDsaPParamGenOpData {
88     CpaFlatBuffer X;
89     /**< 2^(L-1) <= X < 2^L (from FIPS 186-3) */
90     CpaFlatBuffer Q;
91     /**< DSA group parameter q */
92 } CpaCyDsaPParamGenOpData;
93 
94 /**
95  *****************************************************************************
96  * @ingroup cpaCyDsa
97  *      DSA G Parameter Generation Operation Data.
98  * @description
99  *      This structure contains the operation data for the cpaCyDsaGenGParam
100  *      function. The client MUST allocate the memory for this structure and the
101  *      items pointed to by this structure. When the structure is passed into
102  *      the function, ownership of the memory passes to the function. Ownership
103  *      of the memory returns to the client when this structure is returned in
104  *      the callback function.
105  *
106  *      All values in this structure are required to be in Most Significant Byte
107  *      first order, e.g. P.pData[0] = MSB.
108  *
109  *      All numbers MUST be stored in big-endian order.
110  *
111  * @note
112  *      If the client modifies or frees the memory referenced in this
113  *      structure after it has been submitted to the cpaCyDsaGenGParam
114  *      function, and before it has been returned in the callback, undefined
115  *      behavior will result.
116  *
117  * @see
118  *      cpaCyDsaGenGParam()
119  *
120  *****************************************************************************/
121 typedef struct _CpaCyDsaGParamGenOpData {
122     CpaFlatBuffer P;
123     /**< DSA group parameter p */
124     CpaFlatBuffer Q;
125     /**< DSA group parameter q */
126     CpaFlatBuffer H;
127     /**< any integer with 1 < h < p - 1 */
128 } CpaCyDsaGParamGenOpData;
129 
130 /**
131  *****************************************************************************
132  * @ingroup cpaCyDsa
133  *      DSA Y Parameter Generation Operation Data.
134  * @description
135  *      This structure contains the operation data for the cpaCyDsaGenYParam
136  *      function. The client MUST allocate the memory for this structure and the
137  *      items pointed to by this structure. When the structure is passed into
138  *      the function, ownership of the memory passes to the function. Ownership
139  *      of the memory returns to the client when this structure is returned in
140  *      the callback function.
141  *
142  *      For optimal performance all data SHOULD be 8-byte aligned.
143  *
144  *      All values in this structure are required to be in Most Significant Byte
145  *      first order, e.g. P.pData[0] = MSB.
146  *
147  * @note
148  *      If the client modifies or frees the memory referenced in this
149  *      structure after it has been submitted to the cpaCyDsaGenYParam
150  *      function, and before it has been returned in the callback, undefined
151  *      behavior will result.
152  *
153  * @see
154  *      cpaCyDsaGenYParam()
155  *
156  *****************************************************************************/
157 typedef struct _CpaCyDsaYParamGenOpData {
158     CpaFlatBuffer P;
159     /**< DSA group parameter p */
160     CpaFlatBuffer G;
161     /**< DSA group parameter g */
162     CpaFlatBuffer X;
163     /**< DSA private key x */
164 } CpaCyDsaYParamGenOpData;
165 
166 /**
167  *****************************************************************************
168  * @ingroup cpaCyDsa
169  *      DSA R Sign Operation Data.
170  * @description
171  *      This structure contains the operation data for the cpaCyDsaSignR
172  *      function. The client MUST allocate the memory for this structure and the
173  *      items pointed to by this structure. When the structure is passed into
174  *      the function, ownership of the memory passes to the function. Ownership
175  *      of the memory returns to the client when this structure is returned in
176  *      the callback function.
177  *
178  *      For optimal performance all data SHOULD be 8-byte aligned.
179  *
180  *      All values in this structure are required to be in Most Significant Byte
181  *      first order, e.g. P.pData[0] = MSB.
182  *
183  * @note
184  *      If the client modifies or frees the memory referenced in this
185  *      structure after it has been submitted to the cpaCyDsaSignR
186  *      function, and before it has been returned in the callback, undefined
187  *      behavior will result.
188  *
189  * @see
190  *      cpaCyDsaSignR()
191  *
192  *****************************************************************************/
193 typedef struct _CpaCyDsaRSignOpData {
194     CpaFlatBuffer P;
195     /**< DSA group parameter p */
196     CpaFlatBuffer Q;
197     /**< DSA group parameter q */
198     CpaFlatBuffer G;
199     /**< DSA group parameter g */
200     CpaFlatBuffer K;
201     /**< DSA secret parameter k for signing */
202 } CpaCyDsaRSignOpData;
203 
204 /**
205  *****************************************************************************
206  * @ingroup cpaCyDsa
207  *      DSA S Sign Operation Data.
208  * @description
209  *      This structure contains the operation data for the cpaCyDsaSignS
210  *      function. The client MUST allocate the memory for this structure and
211  *      the items pointed to by this structure. When the structure is passed
212  *      into the function, ownership of the memory passes to the function.
213  *      Ownership of the memory returns to the client when this structure is
214  *      returned in the callback function.
215  *
216  *      For optimal performance all data SHOULD be 8-byte aligned.
217  *
218  *      All values in this structure are required to be in Most Significant Byte
219  *      first order, e.g. Q.pData[0] = MSB.
220  *
221  * @note
222  *      If the client modifies or frees the memory referenced in this
223  *      structure after it has been submitted to the cpaCyDsaSignS
224  *      function, and before it has been returned in the callback, undefined
225  *      behavior will result.
226  *
227  * @see
228  *      cpaCyDsaSignS()
229  *
230  *****************************************************************************/
231 typedef struct _CpaCyDsaSSignOpData {
232     CpaFlatBuffer Q;
233     /**< DSA group parameter q */
234     CpaFlatBuffer X;
235     /**< DSA private key x */
236     CpaFlatBuffer K;
237     /**< DSA secret parameter k for signing */
238     CpaFlatBuffer R;
239     /**< DSA message signature r */
240     CpaFlatBuffer Z;
241     /**< The leftmost min(N, outlen) bits of Hash(M), where:
242      * - N is the bit length of q
243      * - outlen is the bit length of the hash function output block
244      * - M is the message to be signed
245      */
246 } CpaCyDsaSSignOpData;
247 
248 /**
249  *****************************************************************************
250  * @ingroup cpaCyDsa
251  *      DSA R & S Sign Operation Data.
252  * @description
253  *      This structure contains the operation data for the cpaCyDsaSignRS
254  *      function. The client MUST allocate the memory for this structure and the
255  *      items pointed to by this structure. When the structure is passed into
256  *      the function, ownership of the memory passes to the function. Ownership
257  *      of the memory returns to the client when this structure is returned in
258  *      the callback function.
259  *
260  *      For optimal performance all data SHOULD be 8-byte aligned.
261  *
262  *      All values in this structure are required to be in Most Significant Byte
263  *      first order, e.g. P.pData[0] = MSB.
264  *
265  * @note
266  *      If the client modifies or frees the memory referenced in this
267  *      structure after it has been submitted to the cpaCyDsaSignRS
268  *      function, and before it has been returned in the callback, undefined
269  *      behavior will result.
270  *
271  * @see
272  *      cpaCyDsaSignRS()
273  *
274  *****************************************************************************/
275 typedef struct _CpaCyDsaRSSignOpData {
276     CpaFlatBuffer P;
277     /**< DSA group parameter p */
278     CpaFlatBuffer Q;
279     /**< DSA group parameter q */
280     CpaFlatBuffer G;
281     /**< DSA group parameter g */
282     CpaFlatBuffer X;
283     /**< DSA private key x */
284     CpaFlatBuffer K;
285     /**< DSA secret parameter k for signing */
286     CpaFlatBuffer Z;
287     /**< The leftmost min(N, outlen) bits of Hash(M), where:
288      * - N is the bit length of q
289      * - outlen is the bit length of the hash function output block
290      * - M is the message to be signed
291      */
292 } CpaCyDsaRSSignOpData;
293 
294 /**
295  *****************************************************************************
296  * @ingroup cpaCyDsa
297  *      DSA Verify Operation Data.
298  * @description
299  *      This structure contains the operation data for the cpaCyDsaVerify
300  *      function. The client MUST allocate the memory for this structure and the
301  *      items pointed to by this structure. When the structure is passed into
302  *      the function, ownership of the memory passes to the function. Ownership
303  *      of the memory returns to the client when this structure is returned in
304  *      the callback function.
305  *
306  *      For optimal performance all data SHOULD be 8-byte aligned.
307  *
308  *      All values in this structure are required to be in Most Significant Byte
309  *      first order, e.g. P.pData[0] = MSB.
310  *
311  * @note
312  *      If the client modifies or frees the memory referenced in this
313  *      structure after it has been submitted to the cpaCyDsaVerify
314  *      function, and before it has been returned in the callback, undefined
315  *      behavior will result.
316  *
317  * @see
318  *      cpaCyDsaVerify()
319  *
320  *****************************************************************************/
321 typedef struct _CpaCyDsaVerifyOpData {
322     CpaFlatBuffer P;
323     /**< DSA group parameter p */
324     CpaFlatBuffer Q;
325     /**< DSA group parameter q */
326     CpaFlatBuffer G;
327     /**< DSA group parameter g */
328     CpaFlatBuffer Y;
329     /**< DSA public key y */
330     CpaFlatBuffer Z;
331     /**< The leftmost min(N, outlen) bits of Hash(M'), where:
332      * - N is the bit length of q
333      * - outlen is the bit length of the hash function output block
334      * - M is the message to be signed
335      */
336     CpaFlatBuffer R;
337     /**< DSA message signature r */
338     CpaFlatBuffer S;
339     /**< DSA message signature s */
340 } CpaCyDsaVerifyOpData;
341 
342 /**
343  *****************************************************************************
344  * @ingroup cpaCyDsa
345  *      Cryptographic DSA Statistics.
346  * @deprecated
347  *      As of v1.3 of the Crypto API, this structure has been deprecated,
348  *      replaced by @ref CpaCyDsaStats64.
349  * @description
350  *      This structure contains statistics on the Cryptographic DSA
351  *      operations. Statistics are set to zero when the component is
352  *      initialized, and are collected per instance.
353  ****************************************************************************/
354 typedef struct _CpaCyDsaStats {
355     Cpa32U numDsaPParamGenRequests;
356     /**< Total number of successful DSA P parameter generation requests. */
357     Cpa32U numDsaPParamGenRequestErrors;
358     /**< Total number of DSA P parameter generation requests that had an
359      * error and could not be processed. */
360     Cpa32U numDsaPParamGenCompleted;
361     /**< Total number of DSA P parameter generation operations that
362      * completed successfully. */
363     Cpa32U numDsaPParamGenCompletedErrors;
364     /**< Total number of DSA P parameter generation operations that could
365      * not be completed successfully due to errors. */
366     Cpa32U numDsaGParamGenRequests;
367     /**< Total number of successful DSA G parameter generation requests. */
368     Cpa32U numDsaGParamGenRequestErrors;
369     /**< Total number of DSA G parameter generation requests that had an
370      * error and could not be processed. */
371     Cpa32U numDsaGParamGenCompleted;
372     /**< Total number of DSA G parameter generation operations that
373      * completed successfully. */
374     Cpa32U numDsaGParamGenCompletedErrors;
375     /**< Total number of DSA G parameter generation operations that could
376      * not be completed successfully due to errors. */
377     Cpa32U numDsaYParamGenRequests;
378     /**< Total number of successful DSA Y parameter generation requests. */
379     Cpa32U numDsaYParamGenRequestErrors;
380     /**< Total number of DSA Y parameter generation requests that had an
381      * error and could not be processed. */
382     Cpa32U numDsaYParamGenCompleted;
383     /**< Total number of DSA Y parameter generation operations that
384      * completed successfully. */
385     Cpa32U numDsaYParamGenCompletedErrors;
386     /**< Total number of DSA Y parameter generation operations that could
387      * not be completed successfully due to errors. */
388     Cpa32U numDsaRSignRequests;
389     /**< Total number of successful DSA R sign generation requests. */
390     Cpa32U numDsaRSignRequestErrors;
391     /**< Total number of DSA R sign requests that had an error and could
392      * not be processed. */
393     Cpa32U numDsaRSignCompleted;
394     /**< Total number of DSA R sign operations that completed
395      * successfully. */
396     Cpa32U numDsaRSignCompletedErrors;
397     /**< Total number of DSA R sign operations that could not be completed
398      * successfully due to errors. */
399     Cpa32U numDsaSSignRequests;
400     /**< Total number of successful DSA S sign generation requests. */
401     Cpa32U numDsaSSignRequestErrors;
402     /**< Total number of DSA S sign requests that had an error and could
403      * not be processed. */
404     Cpa32U numDsaSSignCompleted;
405     /**< Total number of DSA S sign operations that completed
406      * successfully. */
407     Cpa32U numDsaSSignCompletedErrors;
408     /**< Total number of DSA S sign operations that could not be completed
409      * successfully due to errors. */
410     Cpa32U numDsaRSSignRequests;
411     /**< Total number of successful DSA RS sign generation requests. */
412     Cpa32U numDsaRSSignRequestErrors;
413     /**< Total number of DSA RS sign requests that had an error and could
414      * not be processed. */
415     Cpa32U numDsaRSSignCompleted;
416     /**< Total number of DSA RS sign operations that completed
417      * successfully. */
418     Cpa32U numDsaRSSignCompletedErrors;
419     /**< Total number of DSA RS sign operations that could not be completed
420      * successfully due to errors. */
421     Cpa32U numDsaVerifyRequests;
422     /**< Total number of successful DSA verify generation requests. */
423     Cpa32U numDsaVerifyRequestErrors;
424     /**< Total number of DSA verify requests that had an error and could
425      * not be processed. */
426     Cpa32U numDsaVerifyCompleted;
427     /**< Total number of DSA verify operations that completed
428      * successfully. */
429     Cpa32U numDsaVerifyCompletedErrors;
430     /**< Total number of DSA verify operations that could not be completed
431      * successfully due to errors. */
432     Cpa32U numDsaVerifyFailures;
433     /**< Total number of DSA verify operations that executed successfully
434      * but the outcome of the test was that the verification failed.
435      * Note that this does not indicate an error. */
436 } CpaCyDsaStats CPA_DEPRECATED;
437 
438 /**
439  *****************************************************************************
440  * @ingroup cpaCyDsa
441  *      Cryptographic DSA Statistics (64-bit version).
442  * @description
443  *      This structure contains 64-bit version of the statistics on the
444  *      Cryptographic DSA operations.
445  *      Statistics are set to zero when the component is
446  *      initialized, and are collected per instance.
447  ****************************************************************************/
448 typedef struct _CpaCyDsaStats64 {
449     Cpa64U numDsaPParamGenRequests;
450     /**< Total number of successful DSA P parameter generation requests. */
451     Cpa64U numDsaPParamGenRequestErrors;
452     /**< Total number of DSA P parameter generation requests that had an
453      * error and could not be processed. */
454     Cpa64U numDsaPParamGenCompleted;
455     /**< Total number of DSA P parameter generation operations that
456      * completed successfully. */
457     Cpa64U numDsaPParamGenCompletedErrors;
458     /**< Total number of DSA P parameter generation operations that could
459      * not be completed successfully due to errors. */
460     Cpa64U numDsaGParamGenRequests;
461     /**< Total number of successful DSA G parameter generation requests. */
462     Cpa64U numDsaGParamGenRequestErrors;
463     /**< Total number of DSA G parameter generation requests that had an
464      * error and could not be processed. */
465     Cpa64U numDsaGParamGenCompleted;
466     /**< Total number of DSA G parameter generation operations that
467      * completed successfully. */
468     Cpa64U numDsaGParamGenCompletedErrors;
469     /**< Total number of DSA G parameter generation operations that could
470      * not be completed successfully due to errors. */
471     Cpa64U numDsaYParamGenRequests;
472     /**< Total number of successful DSA Y parameter generation requests. */
473     Cpa64U numDsaYParamGenRequestErrors;
474     /**< Total number of DSA Y parameter generation requests that had an
475      * error and could not be processed. */
476     Cpa64U numDsaYParamGenCompleted;
477     /**< Total number of DSA Y parameter generation operations that
478      * completed successfully. */
479     Cpa64U numDsaYParamGenCompletedErrors;
480     /**< Total number of DSA Y parameter generation operations that could
481      * not be completed successfully due to errors. */
482     Cpa64U numDsaRSignRequests;
483     /**< Total number of successful DSA R sign generation requests. */
484     Cpa64U numDsaRSignRequestErrors;
485     /**< Total number of DSA R sign requests that had an error and could
486      * not be processed. */
487     Cpa64U numDsaRSignCompleted;
488     /**< Total number of DSA R sign operations that completed
489      * successfully. */
490     Cpa64U numDsaRSignCompletedErrors;
491     /**< Total number of DSA R sign operations that could not be completed
492      * successfully due to errors. */
493     Cpa64U numDsaSSignRequests;
494     /**< Total number of successful DSA S sign generation requests. */
495     Cpa64U numDsaSSignRequestErrors;
496     /**< Total number of DSA S sign requests that had an error and could
497      * not be processed. */
498     Cpa64U numDsaSSignCompleted;
499     /**< Total number of DSA S sign operations that completed
500      * successfully. */
501     Cpa64U numDsaSSignCompletedErrors;
502     /**< Total number of DSA S sign operations that could not be completed
503      * successfully due to errors. */
504     Cpa64U numDsaRSSignRequests;
505     /**< Total number of successful DSA RS sign generation requests. */
506     Cpa64U numDsaRSSignRequestErrors;
507     /**< Total number of DSA RS sign requests that had an error and could
508      * not be processed. */
509     Cpa64U numDsaRSSignCompleted;
510     /**< Total number of DSA RS sign operations that completed
511      * successfully. */
512     Cpa64U numDsaRSSignCompletedErrors;
513     /**< Total number of DSA RS sign operations that could not be completed
514      * successfully due to errors. */
515     Cpa64U numDsaVerifyRequests;
516     /**< Total number of successful DSA verify generation requests. */
517     Cpa64U numDsaVerifyRequestErrors;
518     /**< Total number of DSA verify requests that had an error and could
519      * not be processed. */
520     Cpa64U numDsaVerifyCompleted;
521     /**< Total number of DSA verify operations that completed
522      * successfully. */
523     Cpa64U numDsaVerifyCompletedErrors;
524     /**< Total number of DSA verify operations that could not be completed
525      * successfully due to errors. */
526     Cpa64U numDsaVerifyFailures;
527     /**< Total number of DSA verify operations that executed successfully
528      * but the outcome of the test was that the verification failed.
529      * Note that this does not indicate an error. */
530 } CpaCyDsaStats64;
531 
532 /**
533  *****************************************************************************
534  * @ingroup cpaCyDsa
535  *      Definition of a generic callback function invoked for a number of the
536  *      DSA API functions..
537  *
538  * @description
539  *      This is the prototype for the cpaCyDsaGenCbFunc callback function.
540  *
541  * @context
542  *      This callback function can be executed in a context that DOES NOT
543  *      permit sleeping to occur.
544  * @assumptions
545  *      None
546  * @sideEffects
547  *      None
548  * @reentrant
549  *      No
550  * @threadSafe
551  *      Yes
552  *
553  * @param[in] pCallbackTag     User-supplied value to help identify request.
554  * @param[in] status           Status of the operation. Valid values are
555  *                             CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
556  *                             CPA_STATUS_UNSUPPORTED.
557  * @param[in] pOpData          Opaque pointer to Operation data supplied in
558  *                             request.
559  * @param[in] protocolStatus   The result passes/fails the DSA protocol
560  *                             related checks.
561  * @param[in] pOut             Output data from the request.
562  *
563  * @retval
564  *      None
565  * @pre
566  *      Component has been initialized.
567  * @post
568  *      None
569  * @note
570  *      None
571  * @see
572  *      cpaCyDsaGenPParam()
573  *         cpaCyDsaGenGParam()
574  *         cpaCyDsaSignR()
575  *         cpaCyDsaSignS()
576  *
577  *****************************************************************************/
578 typedef void (*CpaCyDsaGenCbFunc)(void *pCallbackTag,
579         CpaStatus status,
580         void *pOpData,
581         CpaBoolean protocolStatus,
582         CpaFlatBuffer *pOut);
583 
584 /**
585  *****************************************************************************
586  * @ingroup cpaCyDsa
587  *      Definition of callback function invoked for cpaCyDsaSignRS
588  *      requests.
589  *
590  * @description
591  *      This is the prototype for the cpaCyDsaSignRS callback function, which
592  *      will provide the DSA message signature r and s parameters.
593  *
594  * @context
595  *      This callback function can be executed in a context that DOES NOT
596  *      permit sleeping to occur.
597  * @assumptions
598  *      None
599  * @sideEffects
600  *      None
601  * @reentrant
602  *      No
603  * @threadSafe
604  *      Yes
605  *
606  * @param[in] pCallbackTag     User-supplied value to help identify request.
607  * @param[in] status           Status of the operation. Valid values are
608  *                             CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
609  *                             CPA_STATUS_UNSUPPORTED.
610  * @param[in] pOpData          Operation data pointer supplied in request.
611  * @param[in] protocolStatus   The result passes/fails the DSA protocol
612  *                             related checks.
613  * @param[in] pR               DSA message signature r.
614  * @param[in] pS               DSA message signature s.
615  *
616  *
617  * @retval
618  *      None
619  * @pre
620  *      Component has been initialized.
621  * @post
622  *      None
623  * @note
624  *      None
625  * @see
626  *      cpaCyDsaSignRS()
627  *
628  *****************************************************************************/
629 typedef void (*CpaCyDsaRSSignCbFunc)(void *pCallbackTag,
630         CpaStatus status,
631         void *pOpData,
632         CpaBoolean protocolStatus,
633         CpaFlatBuffer *pR,
634         CpaFlatBuffer *pS);
635 
636 /**
637  *****************************************************************************
638  * @ingroup cpaCyDsa
639  *      Definition of callback function invoked for cpaCyDsaVerify
640  *      requests.
641  *
642  * @description
643  *      This is the prototype for the cpaCyDsaVerify callback function.
644  *
645  * @context
646  *      This callback function can be executed in a context that DOES NOT
647  *      permit sleeping to occur.
648  * @assumptions
649  *      None
650  * @sideEffects
651  *      None
652  * @reentrant
653  *      No
654  * @threadSafe
655  *      Yes
656  *
657  * @param[in] pCallbackTag     User-supplied value to help identify request.
658  * @param[in] status           Status of the operation. Valid values are
659  *                             CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
660  *                             CPA_STATUS_UNSUPPORTED.
661  * @param[in] pOpData          Operation data pointer supplied in request.
662  * @param[in] verifyStatus     The verification passed or failed.
663  *
664  * @retval
665  *      None
666  * @pre
667  *      Component has been initialized.
668  * @post
669  *      None
670  * @note
671  *      None
672  * @see
673  *      cpaCyDsaVerify()
674  *
675  *****************************************************************************/
676 typedef void (*CpaCyDsaVerifyCbFunc)(void *pCallbackTag,
677         CpaStatus status,
678         void *pOpData,
679         CpaBoolean verifyStatus);
680 
681 /**
682  *****************************************************************************
683  * @ingroup cpaCyDsa
684  *      Generate DSA P Parameter.
685  *
686  * @description
687  *
688  *     This function performs FIPS 186-3 Appendix A.1.1.2 steps 11.4 and 11.5,
689  *     and part of step 11.7:
690  *
691  *         11.4. c = X mod 2q.
692  *         11.5. p = X - (c - 1).
693  *         11.7. Test whether or not p is prime as specified in Appendix C.3.
694  *               [Note that a GCD test against ~1400 small primes is performed
695  *               on p to eliminate ~94% of composites - this is NOT a "robust"
696  *               primality test, as specified in Appendix C.3.]
697  *
698  *     The protocol status, returned in the callback function as parameter
699  *     protocolStatus (or, in the case of synchronous invocation, in the
700  *     parameter *pProtocolStatus) is used to indicate whether the value p is
701  *     in the right range and has passed the limited primality test.
702  *
703  *     Specifically, (protocolStatus == CPA_TRUE) means p is in the right range
704  *     and  SHOULD be subjected to a robust primality test as specified in
705  *     FIPS 186-3 Appendix C.3 (for example, 40 rounds of Miller-Rabin).
706  *     Meanwhile, (protocolStatus == CPA_FALSE) means p is either composite,
707  *     or p < 2^(L-1), in which case the value of p gets set to zero.
708  *
709  * @context
710  *      When called as an asynchronous function it cannot sleep. It can be
711  *      executed in a context that does not permit sleeping.
712  *      When called as a synchronous function it may sleep. It MUST NOT be
713  *      executed in a context that DOES NOT permit sleeping.
714  * @assumptions
715  *      None
716  * @sideEffects
717  *      None
718  * @blocking
719  *      Yes when configured to operate in synchronous mode.
720  * @reentrant
721  *      No
722  * @threadSafe
723  *      Yes
724  *
725  * @param[in]  instanceHandle     Instance handle.
726  * @param[in]  pCb                Callback function pointer. If this is
727  *                                set to a NULL value the function will
728  *                                operate synchronously.
729  * @param[in]  pCallbackTag       User-supplied value to help identify request.
730  * @param[in]  pOpData            Structure containing all the data needed to
731  *                                perform the operation. The client code
732  *                                allocates the memory for this structure. This
733  *                                component takes ownership of the memory until
734  *                                it is returned in the callback.
735  * @param[out] pProtocolStatus    The result passes/fails the DSA protocol
736  *                                related checks.
737  * @param[out] pP                 Candidate for DSA parameter p, p odd and
738  *                                2^(L-1) < p < X
739  *                                On invocation the callback function will
740  *                                contain this parameter in the pOut parameter.
741  *
742  *
743  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
744  * @retval CPA_STATUS_FAIL          Function failed.
745  * @retval CPA_STATUS_RETRY         Resubmit the request.
746  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
747  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
748  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
749  *                                  the request.
750  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
751  *
752  * @pre
753  *      The component has been initialized.
754  * @post
755  *      None
756  * @note
757  *      When pCb is non-NULL an asynchronous callback of type
758  *      CpaCyDsaPParamGenCbFunc is generated in response to this
759  *      function call.
760  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
761  *
762  * @see
763  *      CpaCyDsaPParamGenOpData,
764  *      CpaCyDsaGenCbFunc
765  *
766  *****************************************************************************/
767 CpaStatus
768 cpaCyDsaGenPParam(const CpaInstanceHandle instanceHandle,
769         const CpaCyDsaGenCbFunc pCb,
770         void * pCallbackTag,
771         const CpaCyDsaPParamGenOpData *pOpData,
772         CpaBoolean *pProtocolStatus,
773         CpaFlatBuffer *pP);
774 
775 /**
776  *****************************************************************************
777  * @ingroup cpaCyDsa
778  *      Generate DSA G Parameter.
779  *
780  * @description
781  *     This function performs FIPS 186-3 Appendix A.2.1, steps 1 and 3,
782  *     and part of step 4:
783  *
784  *         1. e = (p - 1)/q.
785  *         3. Set g = h^e mod p.
786  *         4. If (g = 1), then go to step 2.
787  *            Here, the implementation will check for g == 1, and return
788  *            status accordingly.
789  *
790  *
791  *     The protocol status, returned in the callback function as parameter
792  *     protocolStatus (or, in the case of synchronous invocation, in the
793  *     parameter *pProtocolStatus) is used to indicate whether the value g is
794  *     acceptable.
795  *
796  *     Specifically, (protocolStatus == CPA_TRUE) means g is acceptable.
797  *     Meanwhile, (protocolStatus == CPA_FALSE) means g == 1, so a
798  *     different value of h SHOULD be used to generate another value of g.
799  *
800  * @context
801  *      When called as an asynchronous function it cannot sleep. It can be
802  *      executed in a context that does not permit sleeping.
803  *      When called as a synchronous function it may sleep. It MUST NOT be
804  *      executed in a context that DOES NOT permit sleeping.
805  * @assumptions
806  *      None
807  * @sideEffects
808  *      None
809  * @blocking
810  *      Yes when configured to operate in synchronous mode.
811  * @reentrant
812  *      No
813  * @threadSafe
814  *      Yes
815  *
816  * @param[in]  instanceHandle   Instance handle.
817  * @param[in]  pCb              Callback function pointer. If this is set to a
818  *                              NULL value the function will operate
819  *                              synchronously.
820  * @param[in]  pCallbackTag     User-supplied value to help identify request.
821  * @param[in]  pOpData          Structure containing all the data needed to
822  *                              perform the operation. The client code
823  *                              allocates the memory for this structure. This
824  *                              component takes ownership of the memory until
825  *                              it is returned in the callback.
826  * @param[out] pProtocolStatus  The result passes/fails the DSA protocol
827  *                              related checks.
828  * @param[out] pG               g = h^((p-1)/q) mod p.
829  *                              On invocation the callback function will
830  *                              contain this parameter in the pOut parameter.
831  *
832  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
833  * @retval CPA_STATUS_FAIL           Function failed.
834  * @retval CPA_STATUS_RETRY          Resubmit the request.
835  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
836  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
837  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
838  *                                   the request.
839  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
840  *
841  * @pre
842  *      The component has been initialized via cpaCyStartInstance function.
843  * @post
844  *      None
845  * @note
846  *      When pCb is non-NULL an asynchronous callback of type
847  *      CpaCyDsaGParamGenCbFunc is generated in response to this
848  *      function call.
849  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
850  *
851  * @see
852  *      CpaCyDsaGParamGenOpData,
853  *      CpaCyDsaGenCbFunc
854  *
855  *****************************************************************************/
856 CpaStatus
857 cpaCyDsaGenGParam(const CpaInstanceHandle instanceHandle,
858         const CpaCyDsaGenCbFunc pCb,
859         void *pCallbackTag,
860         const CpaCyDsaGParamGenOpData *pOpData,
861         CpaBoolean *pProtocolStatus,
862         CpaFlatBuffer *pG);
863 
864 /**
865  *****************************************************************************
866  * @ingroup cpaCyDsa
867  *      Generate DSA Y Parameter.
868  *
869  * @description
870  *
871  *     This function performs modular exponentiation to generate y as
872  *     described in FIPS 186-3 section 4.1:
873  *         y = g^x mod p
874  *
875  * @context
876  *      When called as an asynchronous function it cannot sleep. It can be
877  *      executed in a context that does not permit sleeping.
878  *      When called as a synchronous function it may sleep. It MUST NOT be
879  *      executed in a context that DOES NOT permit sleeping.
880  * @assumptions
881  *      None
882  * @sideEffects
883  *      None
884  * @blocking
885  *      Yes when configured to operate in synchronous mode.
886  * @reentrant
887  *      No
888  * @threadSafe
889  *      Yes
890  *
891  * @param[in]  instanceHandle   Instance handle.
892  * @param[in]  pCb              Callback function pointer. If this is set to a
893  *                              NULL value the function will operate
894  *                              synchronously.
895  * @param[in]  pCallbackTag     User-supplied value to help identify request.
896  * @param[in]  pOpData          Structure containing all the data needed to
897  *                              perform the operation. The client code
898  *                              allocates the memory for this structure. This
899  *                              component takes ownership of the memory until
900  *                              it is returned in the callback.
901  * @param[out] pProtocolStatus  The result passes/fails the DSA protocol
902  *                              related checks.
903  * @param[out] pY               y = g^x mod p*
904  *                              On invocation the callback function will
905  *                              contain this parameter in the pOut parameter.
906  *
907  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
908  * @retval CPA_STATUS_FAIL           Function failed.
909  * @retval CPA_STATUS_RETRY          Resubmit the request.
910  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
911  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
912  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
913  *                                   the request.
914  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
915  *
916  * @pre
917  *      The component has been initialized via cpaCyStartInstance function.
918  * @post
919  *      None
920  * @note
921  *      When pCb is non-NULL an asynchronous callback of type
922  *      CpaCyDsaYParamGenCbFunc is generated in response to this
923  *      function call.
924  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
925  *
926  * @see
927  *      CpaCyDsaYParamGenOpData,
928  *      CpaCyDsaGenCbFunc
929  *
930  *****************************************************************************/
931 CpaStatus
932 cpaCyDsaGenYParam(const CpaInstanceHandle instanceHandle,
933         const CpaCyDsaGenCbFunc pCb,
934         void *pCallbackTag,
935         const CpaCyDsaYParamGenOpData *pOpData,
936         CpaBoolean *pProtocolStatus,
937         CpaFlatBuffer *pY);
938 
939 /**
940  *****************************************************************************
941  * @ingroup cpaCyDsa
942  *      Generate DSA R Signature.
943  *
944  * @description
945  *     This function generates the DSA R signature as described in FIPS 186-3
946  *     Section 4.6:
947  *         r = (g^k mod p) mod q
948  *
949  *     The protocol status, returned in the callback function as parameter
950  *     protocolStatus (or, in the case of synchronous invocation, in the
951  *     parameter *pProtocolStatus) is used to indicate whether the value r == 0.
952  *
953  *     Specifically, (protocolStatus == CPA_TRUE) means r != 0, while
954  *     (protocolStatus == CPA_FALSE) means r == 0.
955  *
956  *     Generation of signature r does not depend on the content of the message
957  *     being signed, so this operation can be done in advance for different
958  *     values of k.  Then once each message becomes available only the
959  *     signature s needs to be generated.
960  *
961  * @context
962  *      When called as an asynchronous function it cannot sleep. It can be
963  *      executed in a context that does not permit sleeping.
964  *      When called as a synchronous function it may sleep. It MUST NOT be
965  *      executed in a context that DOES NOT permit sleeping.
966  * @assumptions
967  *      None
968  * @sideEffects
969  *      None
970  * @blocking
971  *      Yes when configured to operate in synchronous mode.
972  * @reentrant
973  *      No
974  * @threadSafe
975  *      Yes
976  *
977  * @param[in]  instanceHandle   Instance handle.
978  * @param[in]  pCb              Callback function pointer. If this is set to a
979  *                              NULL value the function will operate
980  *                              synchronously.
981  * @param[in]  pCallbackTag     User-supplied value to help identify request.
982  * @param[in]  pOpData          Structure containing all the data needed to
983  *                              perform the operation. The client code
984  *                              allocates the memory for this structure. This
985  *                              component takes ownership of the memory until
986  *                              it is returned in the callback.
987  * @param[out] pProtocolStatus  The result passes/fails the DSA protocol
988  *                              related checks.
989  * @param[out] pR               DSA message signature r.
990  *                              On invocation the callback function will
991  *                              contain this parameter in the pOut parameter.
992  *
993  *
994  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
995  * @retval CPA_STATUS_FAIL           Function failed.
996  * @retval CPA_STATUS_RETRY          Resubmit the request.
997  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
998  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
999  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1000  *                                   the request.
1001  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1002  *
1003  * @pre
1004  *      The component has been initialized via cpaCyStartInstance function.
1005  * @post
1006  *      None
1007  * @note
1008  *      When pCb is non-NULL an asynchronous callback of type
1009  *      CpaCyDsaRSignCbFunc is generated in response to this function
1010  *      call.
1011  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
1012  *
1013  * @see
1014  *      CpaCyDsaRSignOpData,
1015  *      CpaCyDsaGenCbFunc,
1016  *      cpaCyDsaSignS(),
1017  *      cpaCyDsaSignRS()
1018  *
1019  *****************************************************************************/
1020 CpaStatus
1021 cpaCyDsaSignR(const CpaInstanceHandle instanceHandle,
1022         const CpaCyDsaGenCbFunc pCb,
1023         void *pCallbackTag,
1024         const CpaCyDsaRSignOpData *pOpData,
1025         CpaBoolean *pProtocolStatus,
1026         CpaFlatBuffer *pR);
1027 
1028 /**
1029  *****************************************************************************
1030  * @ingroup cpaCyDsa
1031  *      Generate DSA S Signature.
1032  *
1033  * @description
1034  *     This function generates the DSA S signature as described in FIPS 186-3
1035  *     Section 4.6:
1036  *          s = (k^-1(z + xr)) mod q
1037  *
1038  *     Here, z = the leftmost min(N, outlen) bits of Hash(M).  This function
1039  *     does not perform the SHA digest; z is computed by the caller and
1040  *     passed as a parameter in the pOpData field.
1041  *
1042  *     The protocol status, returned in the callback function as parameter
1043  *     protocolStatus (or, in the case of synchronous invocation, in the
1044  *     parameter *pProtocolStatus) is used to indicate whether the value s == 0.
1045  *
1046  *     Specifically, (protocolStatus == CPA_TRUE) means s != 0, while
1047  *     (protocolStatus == CPA_FALSE) means s == 0.
1048  *
1049  *     If signature r has been generated in advance, then this function can be
1050  *     used to generate the signature s once the message becomes available.
1051  *
1052  * @context
1053  *      When called as an asynchronous function it cannot sleep. It can be
1054  *      executed in a context that does not permit sleeping.
1055  *      When called as a synchronous function it may sleep. It MUST NOT be
1056  *      executed in a context that DOES NOT permit sleeping.
1057  * @assumptions
1058  *      None
1059  * @sideEffects
1060  *      None
1061  * @blocking
1062  *      Yes when configured to operate in synchronous mode.
1063  * @reentrant
1064  *      No
1065  * @threadSafe
1066  *      Yes
1067  *
1068  * @param[in]  instanceHandle   Instance handle.
1069  * @param[in]  pCb              Callback function pointer. If this is set to a
1070  *                              NULL value the function will operate
1071  *                              synchronously.
1072  * @param[in]  pCallbackTag     User-supplied value to help identify request.
1073  * @param[in]  pOpData          Structure containing all the data needed to
1074  *                              perform the operation. The client code
1075  *                              allocates the memory for this structure. This
1076  *                              component takes ownership of the memory until
1077  *                              it is returned in the callback.
1078  * @param[out] pProtocolStatus  The result passes/fails the DSA protocol
1079  *                              related checks.
1080  * @param[out] pS               DSA message signature s.
1081  *                              On invocation the callback function will
1082  *                              contain this parameter in the pOut parameter.
1083  *
1084  *
1085  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
1086  * @retval CPA_STATUS_FAIL           Function failed.
1087  * @retval CPA_STATUS_RETRY          Resubmit the request.
1088  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
1089  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
1090  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1091  *                                   the request.
1092  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1093  *
1094  * @pre
1095  *      The component has been initialized via cpaCyStartInstance function.
1096  * @post
1097  *      None
1098  * @note
1099  *      When pCb is non-NULL an asynchronous callback of type
1100  *      CpaCyDsaSSignCbFunc is generated in response to this function
1101  *      call.
1102  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
1103  *
1104  * @see
1105  *      CpaCyDsaSSignOpData,
1106  *      CpaCyDsaGenCbFunc,
1107  *      cpaCyDsaSignR(),
1108  *      cpaCyDsaSignRS()
1109  *
1110  *****************************************************************************/
1111 CpaStatus
1112 cpaCyDsaSignS(const CpaInstanceHandle instanceHandle,
1113         const CpaCyDsaGenCbFunc pCb,
1114         void *pCallbackTag,
1115         const CpaCyDsaSSignOpData *pOpData,
1116         CpaBoolean *pProtocolStatus,
1117         CpaFlatBuffer *pS);
1118 
1119 /**
1120  *****************************************************************************
1121  * @ingroup cpaCyDsa
1122  *      Generate DSA R and S Signatures.
1123  *
1124  * @description
1125  *     This function generates the DSA R and S signatures as described in
1126  *     FIPS 186-3 Section 4.6:
1127  *
1128  *         r = (g^k mod p) mod q
1129  *         s = (k^-1(z + xr)) mod q
1130  *
1131  *     Here, z = the leftmost min(N, outlen) bits of Hash(M).  This function
1132  *     does not perform the SHA digest; z is computed by the caller and
1133  *     passed as a parameter in the pOpData field.
1134  *
1135  *     The protocol status, returned in the callback function as parameter
1136  *     protocolStatus (or, in the case of synchronous invocation, in the
1137  *     parameter *pProtocolStatus) is used to indicate whether either of
1138  *     the values r or s are zero.
1139  *
1140  *     Specifically, (protocolStatus == CPA_TRUE) means neither is zero (i.e.
1141  *     (r != 0) && (s != 0)), while (protocolStatus == CPA_FALSE) means that at
1142  *     least one of r or s is zero (i.e. (r == 0) || (s == 0)).
1143  *
1144  * @context
1145  *      When called as an asynchronous function it cannot sleep. It can be
1146  *      executed in a context that does not permit sleeping.
1147  *      When called as a synchronous function it may sleep. It MUST NOT be
1148  *      executed in a context that DOES NOT permit sleeping.
1149  * @assumptions
1150  *      None
1151  * @sideEffects
1152  *      None
1153  * @blocking
1154  *      Yes when configured to operate in synchronous mode.
1155  * @reentrant
1156  *      No
1157  * @threadSafe
1158  *      Yes
1159  *
1160  * @param[in]  instanceHandle    Instance handle.
1161  * @param[in]  pCb               Callback function pointer. If this is  set to
1162  *                               a NULL value the function will operate
1163  *                               synchronously.
1164  * @param[in]  pCallbackTag      User-supplied value to help identify request.
1165  * @param[in]  pOpData           Structure containing all the data needed to
1166  *                               perform the operation. The client code
1167  *                               allocates the memory for this structure. This
1168  *                               component takes ownership of the memory until
1169  *                               it is returned in the callback.
1170  * @param[out] pProtocolStatus   The result passes/fails the DSA protocol
1171  *                               related checks.
1172  * @param[out] pR                DSA message signature r.
1173  * @param[out] pS                DSA message signature s.
1174  *
1175  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
1176  * @retval CPA_STATUS_FAIL           Function failed.
1177  * @retval CPA_STATUS_RETRY          Resubmit the request.
1178  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
1179  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
1180  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1181  *                                   the request.
1182  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1183  *
1184  * @pre
1185  *      The component has been initialized via cpaCyStartInstance function.
1186  * @post
1187  *      None
1188  * @note
1189  *      When pCb is non-NULL an asynchronous callback of type
1190  *      CpaCyDsaRSSignCbFunc is generated in response to this function
1191  *      call.
1192  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
1193  *
1194  * @see
1195  *      CpaCyDsaRSSignOpData,
1196  *      CpaCyDsaRSSignCbFunc,
1197  *      cpaCyDsaSignR(),
1198  *      cpaCyDsaSignS()
1199  *
1200  *****************************************************************************/
1201 CpaStatus
1202 cpaCyDsaSignRS(const CpaInstanceHandle instanceHandle,
1203         const CpaCyDsaRSSignCbFunc pCb,
1204         void *pCallbackTag,
1205         const CpaCyDsaRSSignOpData *pOpData,
1206         CpaBoolean *pProtocolStatus,
1207         CpaFlatBuffer *pR,
1208         CpaFlatBuffer *pS);
1209 
1210 /**
1211  *****************************************************************************
1212  * @ingroup cpaCyDsa
1213  *      Verify DSA R and S signatures.
1214  *
1215  * @description
1216  *     This function performs FIPS 186-3 Section 4.7:
1217  *         w = (s')^-1 mod q
1218  *         u1 = (zw) mod q
1219  *         u2 = ((r')w) mod q
1220  *         v = (((g)^u1 (y)^u2) mod p) mod q
1221  *
1222  *     Here, z = the leftmost min(N, outlen) bits of Hash(M').  This function
1223  *     does not perform the SHA digest; z is computed by the caller and
1224  *     passed as a parameter in the pOpData field.
1225  *
1226  *     A response status of ok (verifyStatus == CPA_TRUE) means v = r'.
1227  *     A response status of not ok (verifyStatus == CPA_FALSE) means v != r'.
1228  *
1229  * @context
1230  *      When called as an asynchronous function it cannot sleep. It can be
1231  *      executed in a context that does not permit sleeping.
1232  *      When called as a synchronous function it may sleep. It MUST NOT be
1233  *      executed in a context that DOES NOT permit sleeping.
1234  * @assumptions
1235  *      None
1236  * @sideEffects
1237  *      None
1238  * @blocking
1239  *      Yes when configured to operate in synchronous mode.
1240  * @reentrant
1241  *      No
1242  * @threadSafe
1243  *      Yes
1244  *
1245  * @param[in]  instanceHandle  Instance handle.
1246  * @param[in]  pCb             Callback function pointer. If this is set to
1247  *                             a NULL value the function will operate
1248  *                             synchronously.
1249  * @param[in]  pCallbackTag    User-supplied value to help identify request.
1250  * @param[in]  pOpData         Structure containing all the data needed to
1251  *                             perform the operation. The client code
1252  *                             allocates the memory for this structure. This
1253  *                             component takes ownership of the memory until
1254  *                             it is returned in the callback.
1255  * @param[out] pVerifyStatus   The verification passed or failed.
1256  *
1257  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
1258  * @retval CPA_STATUS_FAIL           Function failed.
1259  * @retval CPA_STATUS_RETRY          Resubmit the request.
1260  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
1261  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
1262  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1263  *                                   the request.
1264  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1265  *
1266  * @pre
1267  *      The component has been initialized via cpaCyStartInstance function.
1268  * @post
1269  *      None
1270  * @note
1271  *      When pCb is non-NULL an asynchronous callback of type
1272  *      CpaCyDsaVerifyCbFunc is generated in response to this function
1273  *      call.
1274  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
1275  *
1276  * @see
1277  *      CpaCyDsaVerifyOpData,
1278  *      CpaCyDsaVerifyCbFunc
1279  *
1280  *****************************************************************************/
1281 CpaStatus
1282 cpaCyDsaVerify(const CpaInstanceHandle instanceHandle,
1283         const CpaCyDsaVerifyCbFunc pCb,
1284         void *pCallbackTag,
1285         const CpaCyDsaVerifyOpData *pOpData,
1286         CpaBoolean *pVerifyStatus);
1287 
1288 /**
1289  *****************************************************************************
1290  * @ingroup cpaCyDsa
1291  *      Query statistics for a specific DSA instance.
1292  *
1293  * @deprecated
1294  *      As of v1.3 of the Crypto API, this function has been deprecated,
1295  *      replaced by @ref cpaCyDsaQueryStats64().
1296  *
1297  * @description
1298  *      This function will query a specific instance of the DSA implementation
1299  *      for statistics. The user MUST allocate the CpaCyDsaStats structure
1300  *      and pass the reference to that structure into this function call. This
1301  *      function writes the statistic results into the passed in
1302  *      CpaCyDsaStats structure.
1303  *
1304  *      Note: statistics returned by this function do not interrupt current data
1305  *      processing and as such can be slightly out of sync with operations that
1306  *      are in progress during the statistics retrieval process.
1307  *
1308  * @context
1309  *      This is a synchronous function and it can sleep. It MUST NOT be
1310  *      executed in a context that DOES NOT permit sleeping.
1311  * @assumptions
1312  *      None
1313  * @sideEffects
1314  *      None
1315  * @blocking
1316  *      This function is synchronous and blocking.
1317  * @reentrant
1318  *      No
1319  * @threadSafe
1320  *      Yes
1321  *
1322  * @param[in]  instanceHandle        Instance handle.
1323  * @param[out] pDsaStats             Pointer to memory into which the statistics
1324  *                                   will be written.
1325  *
1326  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
1327  * @retval CPA_STATUS_FAIL           Function failed.
1328  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
1329  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
1330  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1331  *                                   the request.
1332  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1333  *
1334  * @pre
1335  *      Component has been initialized.
1336  * @post
1337  *      None
1338  * @note
1339  *      This function operates in a synchronous manner and no asynchronous
1340  *      callback will be generated.
1341  * @see
1342  *      CpaCyDsaStats
1343  *****************************************************************************/
1344 CpaStatus CPA_DEPRECATED
1345 cpaCyDsaQueryStats(const CpaInstanceHandle instanceHandle,
1346         struct _CpaCyDsaStats *pDsaStats);
1347 
1348 /**
1349  *****************************************************************************
1350  * @ingroup cpaCyDsa
1351  *      Query 64-bit statistics for a specific DSA instance.
1352  *
1353  * @description
1354  *      This function will query a specific instance of the DSA implementation
1355  *      for 64-bit statistics. The user MUST allocate the CpaCyDsaStats64
1356  *      structure and pass the reference to that structure into this function.
1357  *      This function writes the statistic results into the passed in
1358  *      CpaCyDsaStats64 structure.
1359  *
1360  *      Note: statistics returned by this function do not interrupt current data
1361  *      processing and as such can be slightly out of sync with operations that
1362  *      are in progress during the statistics retrieval process.
1363  *
1364  * @context
1365  *      This is a synchronous function and it can sleep. It MUST NOT be
1366  *      executed in a context that DOES NOT permit sleeping.
1367  * @assumptions
1368  *      None
1369  * @sideEffects
1370  *      None
1371  * @blocking
1372  *      This function is synchronous and blocking.
1373  * @reentrant
1374  *      No
1375  * @threadSafe
1376  *      Yes
1377  *
1378  * @param[in]  instanceHandle        Instance handle.
1379  * @param[out] pDsaStats             Pointer to memory into which the statistics
1380  *                                   will be written.
1381  *
1382  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
1383  * @retval CPA_STATUS_FAIL           Function failed.
1384  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
1385  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
1386  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
1387  *                                   the request.
1388  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
1389  *
1390  * @pre
1391  *      Component has been initialized.
1392  * @post
1393  *      None
1394  * @note
1395  *      This function operates in a synchronous manner and no asynchronous
1396  *      callback will be generated.
1397  * @see
1398  *      CpaCyDsaStats
1399  *****************************************************************************/
1400 CpaStatus
1401 cpaCyDsaQueryStats64(const CpaInstanceHandle instanceHandle,
1402         CpaCyDsaStats64 *pDsaStats);
1403 
1404 /*****************************************************************************/
1405 
1406 #ifdef __cplusplus
1407 } /* close the extern "C" { */
1408 #endif
1409 
1410 #endif /* CPA_CY_DSA_H */
1411