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
88extern "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 *****************************************************************************/
120typedef 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 *****************************************************************************/
154typedef 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 *****************************************************************************/
190typedef 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 *****************************************************************************/
226typedef 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 *****************************************************************************/
264typedef 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 *****************************************************************************/
308typedef 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 *****************************************************************************/
354typedef 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 ****************************************************************************/
387typedef 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 ****************************************************************************/
481typedef 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 *****************************************************************************/
611typedef 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 *****************************************************************************/
662typedef 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 *****************************************************************************/
709typedef 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 *****************************************************************************/
800CpaStatus
801cpaCyDsaGenPParam(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 *****************************************************************************/
889CpaStatus
890cpaCyDsaGenGParam(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 *****************************************************************************/
964CpaStatus
965cpaCyDsaGenYParam(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 *****************************************************************************/
1053CpaStatus
1054cpaCyDsaSignR(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 *****************************************************************************/
1144CpaStatus
1145cpaCyDsaSignS(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 *****************************************************************************/
1234CpaStatus
1235cpaCyDsaSignRS(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 *****************************************************************************/
1314CpaStatus
1315cpaCyDsaVerify(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 *****************************************************************************/
1377CpaStatus CPA_DEPRECATED
1378cpaCyDsaQueryStats(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 *****************************************************************************/
1433CpaStatus
1434cpaCyDsaQueryStats64(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