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