1 /***************************************************************************
2  *
3  *   BSD LICENSE
4  *
5  *   Copyright(c) 2007-2022 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_ecdsa.h
45  *
46  * @defgroup cpaCyEcdsa Elliptic Curve Digital Signature Algorithm (ECDSA) API
47  *
48  * @ingroup cpaCy
49  *
50  * @description
51  *      These functions specify the API for Public Key Encryption
52  *      (Cryptography) Elliptic Curve Digital Signature Algorithm (ECDSA)
53  *      operations.
54  *
55  * @note
56  *      Large numbers are represented on the QuickAssist API as described
57  *      in the Large Number API (@ref cpaCyLn).
58  *
59  *      In addition, the bit length of large numbers passed to the API
60  *      MUST NOT exceed 576 bits for Elliptic Curve operations.
61  *****************************************************************************/
62 
63 #ifndef CPA_CY_ECDSA_H_
64 #define CPA_CY_ECDSA_H_
65 
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69 
70 #include "cpa_cy_common.h"
71 #include "cpa_cy_ec.h"
72 
73 /**
74  *****************************************************************************
75  * @ingroup cpaCyEcdsa
76  *      ECDSA Sign R Operation Data.
77  * @description
78  *      This structure contains the operation data for the cpaCyEcdsaSignR
79  *      function. The client MUST allocate the memory for this structure and the
80  *      items pointed to by this structure. When the structure is passed into
81  *      the function, ownership of the memory passes to the function. Ownership
82  *      of the memory returns to the client when this structure is returned in
83  *      the callback function.
84  *
85  *      For optimal performance all data buffers SHOULD be 8-byte aligned.
86  *
87  *      All values in this structure are required to be in Most Significant Byte
88  *      first order, e.g. a.pData[0] = MSB.
89  *
90  * @note
91  *      If the client modifies or frees the memory referenced in this
92  *      structure after it has been submitted to the cpaCyEcdsaSignR
93  *      function, and before it has been returned in the callback, undefined
94  *      behavior will result.
95  *
96  * @see
97  *      cpaCyEcdsaSignR()
98  *
99  *****************************************************************************/
100 typedef struct _CpaCyEcdsaSignROpData {
101     CpaFlatBuffer xg;
102     /**< x coordinate of base point G */
103     CpaFlatBuffer yg;
104     /**< y coordinate of base point G */
105     CpaFlatBuffer n;
106     /**< order of the base point G, which shall be prime */
107     CpaFlatBuffer q;
108     /**< prime modulus or irreducible polynomial over GF(2^r) */
109     CpaFlatBuffer a;
110     /**< a elliptic curve coefficient */
111     CpaFlatBuffer b;
112     /**< b elliptic curve coefficient */
113     CpaFlatBuffer k;
114     /**< random value (k > 0 and k < n) */
115 
116     CpaCyEcFieldType fieldType;
117     /**< field type for the operation */
118 } CpaCyEcdsaSignROpData;
119 
120 
121 /**
122  *****************************************************************************
123  * @ingroup cpaCyEcdsa
124  *      ECDSA Sign S Operation Data.
125  * @description
126  *      This structure contains the operation data for the cpaCyEcdsaSignS
127  *      function. The client MUST allocate the memory for this structure and the
128  *      items pointed to by this structure. When the structure is passed into
129  *      the function, ownership of the memory passes to the function. Ownership
130  *      of the memory returns to the client when this structure is returned in
131  *      the callback function.
132  *
133  *      For optimal performance all data buffers SHOULD be 8-byte aligned.
134  *
135  *      All values in this structure are required to be in Most Significant Byte
136  *      first order, e.g. a.pData[0] = MSB.
137  *
138  * @note
139  *      If the client modifies or frees the memory referenced in this
140  *      structure after it has been submitted to the cpaCyEcdsaSignS
141  *      function, and before it has been returned in the callback, undefined
142  *      behavior will result.
143  *
144  * @see
145  *      cpaCyEcdsaSignS()
146  *
147  *****************************************************************************/
148 typedef struct _CpaCyEcdsaSignSOpData {
149     CpaFlatBuffer m;
150     /**< digest of the message to be signed */
151     CpaFlatBuffer d;
152     /**< private key */
153     CpaFlatBuffer r;
154     /**< Ecdsa r signature value  */
155     CpaFlatBuffer k;
156     /**< random value (k > 0 and k < n) */
157     CpaFlatBuffer n;
158     /**< order of the base point G, which shall be prime */
159     CpaCyEcFieldType fieldType;
160     /**< field type for the operation */
161 } CpaCyEcdsaSignSOpData;
162 
163 
164 /**
165  *****************************************************************************
166  * @ingroup cpaCyEcdsa
167  *      ECDSA Sign R & S Operation Data.
168  * @description
169  *      This structure contains the operation data for the cpaCyEcdsaSignRS
170  *      function. The client MUST allocate the memory for this structure and the
171  *      items pointed to by this structure. When the structure is passed into
172  *      the function, ownership of the memory passes to the function. Ownership
173  *      of the memory returns to the client when this structure is returned in
174  *      the callback function.
175  *
176  *      For optimal performance all data buffers SHOULD be 8-byte aligned.
177  *
178  *      All values in this structure are required to be in Most Significant Byte
179  *      first order, e.g. a.pData[0] = MSB.
180  *
181  * @note
182  *      If the client modifies or frees the memory referenced in this
183  *      structure after it has been submitted to the cpaCyEcdsaSignRS
184  *      function, and before it has been returned in the callback, undefined
185  *      behavior will result.
186  *
187  * @see
188  *      cpaCyEcdsaSignRS()
189  *
190  *****************************************************************************/
191 typedef struct _CpaCyEcdsaSignRSOpData {
192     CpaFlatBuffer xg;
193     /**< x coordinate of base point G */
194     CpaFlatBuffer yg;
195     /**< y coordinate of base point G */
196     CpaFlatBuffer n;
197     /**< order of the base point G, which shall be prime */
198     CpaFlatBuffer q;
199     /**< prime modulus or irreducible polynomial over GF(2^r) */
200     CpaFlatBuffer a;
201     /**< a elliptic curve coefficient */
202     CpaFlatBuffer b;
203     /**< b elliptic curve coefficient */
204     CpaFlatBuffer k;
205     /**< random value (k > 0 and k < n) */
206     CpaFlatBuffer m;
207     /**< digest of the message to be signed */
208     CpaFlatBuffer d;
209     /**< private key */
210     CpaCyEcFieldType fieldType;
211     /**< field type for the operation */
212 } CpaCyEcdsaSignRSOpData;
213 
214 
215 /**
216  *****************************************************************************
217  * @ingroup cpaCyEcdsa
218  *      ECDSA Verify Operation Data, for Public Key.
219 
220  * @description
221  *      This structure contains the operation data for the CpaCyEcdsaVerify
222  *      function. The client MUST allocate the memory for this structure and the
223  *      items pointed to by this structure. When the structure is passed into
224  *      the function, ownership of the memory passes to the function. Ownership
225  *      of the memory returns to the client when this structure is returned in
226  *      the callback function.
227  *
228  *      For optimal performance all data buffers SHOULD be 8-byte aligned.
229  *
230  *      All values in this structure are required to be in Most Significant Byte
231  *      first order, e.g. a.pData[0] = MSB.
232  *
233  * @note
234  *      If the client modifies or frees the memory referenced in this
235  *      structure after it has been submitted to the cpaCyEcdsaVerify
236  *      function, and before it has been returned in the callback, undefined
237  *      behavior will result.
238  *
239  * @see
240  *      CpaCyEcdsaVerify()
241  *
242  *****************************************************************************/
243 typedef struct _CpaCyEcdsaVerifyOpData {
244     CpaFlatBuffer xg;
245     /**< x coordinate of base point G */
246     CpaFlatBuffer yg;
247     /**< y coordinate of base point G */
248     CpaFlatBuffer n;
249     /**< order of the base point G, which shall be prime */
250     CpaFlatBuffer q;
251     /**< prime modulus or irreducible polynomial over GF(2^r) */
252     CpaFlatBuffer a;
253     /**< a elliptic curve coefficient */
254     CpaFlatBuffer b;
255     /**< b elliptic curve coefficient */
256     CpaFlatBuffer m;
257     /**< digest of the message to be signed */
258     CpaFlatBuffer r;
259     /**< ECDSA r signature value (r > 0 and r < n) */
260     CpaFlatBuffer s;
261     /**< ECDSA s signature value (s > 0 and s < n) */
262     CpaFlatBuffer xp;
263     /**< x coordinate of point P (public key) */
264     CpaFlatBuffer yp;
265     /**< y coordinate of point P (public key) */
266     CpaCyEcFieldType fieldType;
267     /**< field type for the operation */
268 } CpaCyEcdsaVerifyOpData;
269 
270 
271 /**
272  *****************************************************************************
273  * @ingroup cpaCyEcdsa
274  *      Cryptographic ECDSA Statistics.
275  * @description
276  *      This structure contains statistics on the Cryptographic ECDSA
277  *      operations. Statistics are set to zero when the component is
278  *      initialized, and are collected per instance.
279  *
280  ****************************************************************************/
281 typedef struct _CpaCyEcdsaStats64 {
282     Cpa64U numEcdsaSignRRequests;
283     /**< Total number of ECDSA Sign R operation requests. */
284     Cpa64U numEcdsaSignRRequestErrors;
285     /**< Total number of ECDSA Sign R operation requests that had an error and
286      * could not be processed. */
287     Cpa64U numEcdsaSignRCompleted;
288     /**< Total number of ECDSA Sign R operation requests that completed
289      * successfully. */
290     Cpa64U numEcdsaSignRCompletedErrors;
291     /**< Total number of ECDSA Sign R operation requests that could
292      * not be completed successfully due to errors. */
293     Cpa64U numEcdsaSignRCompletedOutputInvalid;
294     /**< Total number of ECDSA Sign R operation requests could not be completed
295      * successfully due to an invalid output.
296      * Note that this does not indicate an error. */
297     Cpa64U numEcdsaSignSRequests;
298     /**< Total number of ECDSA Sign S operation requests. */
299     Cpa64U numEcdsaSignSRequestErrors;
300     /**< Total number of ECDSA Sign S operation requests that had an error and
301      * could not be processed. */
302     Cpa64U numEcdsaSignSCompleted;
303     /**< Total number of ECDSA Sign S operation requests that completed
304      * successfully. */
305     Cpa64U numEcdsaSignSCompletedErrors;
306     /**< Total number of ECDSA Sign S operation requests that could
307      * not be completed successfully due to errors. */
308     Cpa64U numEcdsaSignSCompletedOutputInvalid;
309     /**< Total number of ECDSA Sign S operation requests could not be completed
310      * successfully due to an invalid output.
311      * Note that this does not indicate an error. */
312     Cpa64U numEcdsaSignRSRequests;
313     /**< Total number of ECDSA Sign R & S operation requests. */
314     Cpa64U numEcdsaSignRSRequestErrors;
315     /**< Total number of ECDSA Sign R & S operation requests that had an
316      * error and could not be processed. */
317     Cpa64U numEcdsaSignRSCompleted;
318     /**< Total number of ECDSA Sign R & S operation requests that completed
319      * successfully. */
320     Cpa64U numEcdsaSignRSCompletedErrors;
321     /**< Total number of ECDSA Sign R & S operation requests that could
322      * not be completed successfully due to errors. */
323     Cpa64U numEcdsaSignRSCompletedOutputInvalid;
324     /**< Total number of ECDSA Sign R & S operation requests could not be
325      * completed successfully due to an invalid output.
326      * Note that this does not indicate an error. */
327     Cpa64U numEcdsaVerifyRequests;
328     /**< Total number of ECDSA Verification operation requests. */
329     Cpa64U numEcdsaVerifyRequestErrors;
330     /**< Total number of ECDSA Verification operation requests that had an
331      * error and could not be processed. */
332     Cpa64U numEcdsaVerifyCompleted;
333     /**< Total number of ECDSA Verification operation requests that completed
334      * successfully. */
335     Cpa64U numEcdsaVerifyCompletedErrors;
336     /**< Total number of ECDSA Verification operation requests that could
337      * not be completed successfully due to errors. */
338     Cpa64U numEcdsaVerifyCompletedOutputInvalid;
339     /**< Total number of ECDSA Verification operation requests that resulted
340      * in an invalid output.
341      * Note that this does not indicate an error. */
342 } CpaCyEcdsaStats64;
343 
344 
345 /**
346  *****************************************************************************
347  * @ingroup cpaCyEcdsa
348  *      Definition of a generic callback function invoked for a number of the
349  *      ECDSA Sign API functions.
350  *
351  * @description
352  *      This is the prototype for the CpaCyEcdsaGenSignCbFunc callback function.
353  *
354  * @context
355  *      This callback function can be executed in a context that DOES NOT
356  *      permit sleeping to occur.
357  * @assumptions
358  *      None
359  * @sideEffects
360  *      None
361  * @reentrant
362  *      No
363  * @threadSafe
364  *      Yes
365  *
366  * @param[in] pCallbackTag      User-supplied value to help identify request.
367  * @param[in] status            Status of the operation. Valid values are
368  *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
369  *                              CPA_STATUS_UNSUPPORTED.
370  * @param[in] pOpData           Opaque pointer to Operation data supplied in
371  *                              request.
372  * @param[in] multiplyStatus    Status of the point multiplication.
373  * @param[in] pOut              Output data from the request.
374  *
375  * @retval
376  *      None
377  * @pre
378  *      Component has been initialized.
379  * @post
380  *      None
381  * @note
382  *      None
383  * @see
384  *      cpaCyEcdsaSignR()
385  *      cpaCyEcdsaSignS()
386  *
387  *****************************************************************************/
388 typedef void (*CpaCyEcdsaGenSignCbFunc)(void *pCallbackTag,
389         CpaStatus status,
390         void *pOpData,
391         CpaBoolean multiplyStatus,
392         CpaFlatBuffer *pOut);
393 
394 
395 /**
396  *****************************************************************************
397  * @ingroup cpaCyEcdsa
398  *      Definition of callback function invoked for cpaCyEcdsaSignRS
399  *      requests.
400  *
401  * @description
402  *      This is the prototype for the CpaCyEcdsaSignRSCbFunc callback function,
403  *      which will provide the ECDSA message signature r and s parameters.
404  *
405  * @context
406  *      This callback function can be executed in a context that DOES NOT
407  *      permit sleeping to occur.
408  * @assumptions
409  *      None
410  * @sideEffects
411  *      None
412  * @reentrant
413  *      No
414  * @threadSafe
415  *      Yes
416  *
417  * @param[in] pCallbackTag      User-supplied value to help identify request.
418  * @param[in] status            Status of the operation. Valid values are
419  *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
420  *                              CPA_STATUS_UNSUPPORTED.
421  * @param[in] pOpData           Operation data pointer supplied in request.
422  * @param[in] multiplyStatus    Status of the point multiplication.
423  * @param[in] pR                Ecdsa message signature r.
424  * @param[in] pS                Ecdsa message signature s.
425  *
426  *
427  * @retval
428  *      None
429  * @pre
430  *      Component has been initialized.
431  * @post
432  *      None
433  * @note
434  *      None
435  * @see
436  *      cpaCyEcdsaSignRS()
437  *
438  *****************************************************************************/
439 typedef void (*CpaCyEcdsaSignRSCbFunc)(void *pCallbackTag,
440         CpaStatus status,
441         void *pOpData,
442         CpaBoolean multiplyStatus,
443         CpaFlatBuffer *pR,
444         CpaFlatBuffer *pS);
445 
446 
447 /**
448  *****************************************************************************
449  * @ingroup cpaCyEcdsa
450  *      Definition of callback function invoked for cpaCyEcdsaVerify requests.
451  *
452  * @description
453  *      This is the prototype for the CpaCyEcdsaVerifyCbFunc callback function.
454  *
455  * @context
456  *      This callback function can be executed in a context that DOES NOT
457  *      permit sleeping to occur.
458  * @assumptions
459  *      None
460  * @sideEffects
461  *      None
462  * @reentrant
463  *      No
464  * @threadSafe
465  *      Yes
466  *
467  * @param[in] pCallbackTag      User-supplied value to help identify request.
468  * @param[in] status            Status of the operation. Valid values are
469  *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
470  *                              CPA_STATUS_UNSUPPORTED.
471  * @param[in] pOpData           Operation data pointer supplied in request.
472  * @param[in] verifyStatus      The verification status.
473  *
474  * @retval
475  *      None
476  * @pre
477  *      Component has been initialized.
478  * @post
479  *      None
480  * @note
481  *      None
482  * @see
483  *      cpaCyEcdsaVerify()
484  *
485  *****************************************************************************/
486 typedef void (*CpaCyEcdsaVerifyCbFunc)(void *pCallbackTag,
487         CpaStatus status,
488         void *pOpData,
489         CpaBoolean verifyStatus);
490 
491 
492 /**
493  *****************************************************************************
494  * @ingroup cpaCyEcdsa
495  *      Generate ECDSA Signature R.
496  *
497  * @description
498  *      This function generates ECDSA Signature R as per ANSI X9.62 2005
499  *      section 7.3.
500  *
501  * @context
502  *      When called as an asynchronous function it cannot sleep. It can be
503  *      executed in a context that does not permit sleeping.
504  *      When called as a synchronous function it may sleep. It MUST NOT be
505  *      executed in a context that DOES NOT permit sleeping.
506  * @assumptions
507  *      None
508  * @sideEffects
509  *      None
510  * @blocking
511  *      Yes when configured to operate in synchronous mode.
512  * @reentrant
513  *      No
514  * @threadSafe
515  *      Yes
516  *
517  * @param[in]  instanceHandle   Instance handle.
518  * @param[in]  pCb              Callback function pointer. If this is set to a
519  *                              NULL value the function will operate
520  *                              synchronously.
521  * @param[in]  pCallbackTag     User-supplied value to help identify request.
522  * @param[in]  pOpData          Structure containing all the data needed to
523  *                              perform the operation. The client code
524  *                              allocates the memory for this structure. This
525  *                              component takes ownership of the memory until
526  *                              it is returned in the callback.
527  * @param[out] pSignStatus      In synchronous mode, the multiply output is
528  *                              valid (CPA_TRUE) or the output is invalid
529  *                              (CPA_FALSE).
530  * @param[out] pR               ECDSA message signature r.
531  *
532  *
533  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
534  * @retval CPA_STATUS_FAIL          Function failed.
535  * @retval CPA_STATUS_RETRY         Resubmit the request.
536  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
537  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
538  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
539  *                                  the request.
540  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
541  *
542  * @pre
543  *      The component has been initialized via cpaCyStartInstance function.
544  * @post
545  *      None
546  * @note
547  *      When pCb is non-NULL an asynchronous callback is generated in response
548  *      to this function call.
549  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
550  *
551  * @see
552  *      None
553  *****************************************************************************/
554 CpaStatus
555 cpaCyEcdsaSignR(const CpaInstanceHandle instanceHandle,
556         const CpaCyEcdsaGenSignCbFunc pCb,
557         void *pCallbackTag,
558         const CpaCyEcdsaSignROpData *pOpData,
559         CpaBoolean *pSignStatus,
560         CpaFlatBuffer *pR);
561 
562 
563 /**
564  *****************************************************************************
565  * @ingroup cpaCyEcdsa
566  *      Generate ECDSA Signature S.
567  *
568  * @description
569  *      This function generates ECDSA Signature S as per ANSI X9.62 2005
570  *      section 7.3.
571  *
572  * @context
573  *      When called as an asynchronous function it cannot sleep. It can be
574  *      executed in a context that does not permit sleeping.
575  *      When called as a synchronous function it may sleep. It MUST NOT be
576  *      executed in a context that DOES NOT permit sleeping.
577  * @assumptions
578  *      None
579  * @sideEffects
580  *      None
581  * @blocking
582  *      Yes when configured to operate in synchronous mode.
583  * @reentrant
584  *      No
585  * @threadSafe
586  *      Yes
587  *
588  * @param[in]  instanceHandle   Instance handle.
589  * @param[in]  pCb              Callback function pointer. If this is set to a
590  *                              NULL value the function will operate
591  *                              synchronously.
592  * @param[in]  pCallbackTag     User-supplied value to help identify request.
593  * @param[in]  pOpData          Structure containing all the data needed to
594  *                              perform the operation. The client code
595  *                              allocates the memory for this structure. This
596  *                              component takes ownership of the memory until
597  *                              it is returned in the callback.
598  * @param[out] pSignStatus      In synchronous mode, the multiply output is
599  *                              valid (CPA_TRUE) or the output is invalid
600  *                              (CPA_FALSE).
601  * @param[out] pS               ECDSA message signature s.
602  *
603  *
604  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
605  * @retval CPA_STATUS_FAIL          Function failed.
606  * @retval CPA_STATUS_RETRY         Resubmit the request.
607  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
608  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
609  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
610  *                                  the request.
611  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
612  *
613  * @pre
614  *      The component has been initialized via cpaCyStartInstance function.
615  * @post
616  *      None
617  * @note
618  *      When pCb is non-NULL an asynchronous callback is generated in response
619  *      to this function call.
620  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
621  *
622  * @see
623  *      None
624  *****************************************************************************/
625 CpaStatus
626 cpaCyEcdsaSignS(const CpaInstanceHandle instanceHandle,
627         const CpaCyEcdsaGenSignCbFunc pCb,
628         void *pCallbackTag,
629         const CpaCyEcdsaSignSOpData *pOpData,
630         CpaBoolean *pSignStatus,
631         CpaFlatBuffer *pS);
632 
633 
634 /**
635  *****************************************************************************
636  * @ingroup cpaCyEcdsa
637  *      Generate ECDSA Signature R & S.
638  *
639  * @description
640  *      This function generates ECDSA Signature R & S as per ANSI X9.62 2005
641  *      section 7.3.
642  *
643  * @context
644  *      When called as an asynchronous function it cannot sleep. It can be
645  *      executed in a context that does not permit sleeping.
646  *      When called as a synchronous function it may sleep. It MUST NOT be
647  *      executed in a context that DOES NOT permit sleeping.
648  * @assumptions
649  *      None
650  * @sideEffects
651  *      None
652  * @blocking
653  *      Yes when configured to operate in synchronous mode.
654  * @reentrant
655  *      No
656  * @threadSafe
657  *      Yes
658  *
659  * @param[in]  instanceHandle   Instance handle.
660  * @param[in]  pCb              Callback function pointer. If this is set to a
661  *                              NULL value the function will operate
662  *                              synchronously.
663  * @param[in]  pCallbackTag     User-supplied value to help identify request.
664  * @param[in]  pOpData          Structure containing all the data needed to
665  *                              perform the operation. The client code
666  *                              allocates the memory for this structure. This
667  *                              component takes ownership of the memory until
668  *                              it is returned in the callback.
669  * @param[out] pSignStatus      In synchronous mode, the multiply output is
670  *                              valid (CPA_TRUE) or the output is invalid
671  *                              (CPA_FALSE).
672  * @param[out] pR               ECDSA message signature r.
673  * @param[out] pS               ECDSA message signature s.
674  *
675  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
676  * @retval CPA_STATUS_FAIL          Function failed.
677  * @retval CPA_STATUS_RETRY         Resubmit the request.
678  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
679  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
680  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
681  *                                  the request.
682  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
683  *
684  * @pre
685  *      The component has been initialized via cpaCyStartInstance function.
686  * @post
687  *      None
688  * @note
689  *      When pCb is non-NULL an asynchronous callback is generated in response
690  *      to this function call.
691  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
692  *
693  * @see
694  *      None
695  *****************************************************************************/
696 CpaStatus
697 cpaCyEcdsaSignRS(const CpaInstanceHandle instanceHandle,
698         const CpaCyEcdsaSignRSCbFunc pCb,
699         void *pCallbackTag,
700         const CpaCyEcdsaSignRSOpData *pOpData,
701         CpaBoolean *pSignStatus,
702         CpaFlatBuffer *pR,
703         CpaFlatBuffer *pS);
704 
705 
706 /**
707  *****************************************************************************
708  * @ingroup cpaCyEcdsa
709  *      Verify ECDSA Public Key.
710  *
711  * @description
712  *      This function performs ECDSA Verify as per ANSI X9.62 2005 section 7.4.
713  *
714  *      A response status of ok (verifyStatus == CPA_TRUE) means that the
715  *      signature was verified
716  *
717  * @context
718  *      When called as an asynchronous function it cannot sleep. It can be
719  *      executed in a context that does not permit sleeping.
720  *      When called as a synchronous function it may sleep. It MUST NOT be
721  *      executed in a context that DOES NOT permit sleeping.
722  * @assumptions
723  *      None
724  * @sideEffects
725  *      None
726  * @blocking
727  *      Yes when configured to operate in synchronous mode.
728  * @reentrant
729  *      No
730  * @threadSafe
731  *      Yes
732  *
733  * @param[in]  instanceHandle   Instance handle.
734  * @param[in]  pCb              Callback function pointer. If this is set to
735  *                              a NULL value the function will operate
736  *                              synchronously.
737  * @param[in]  pCallbackTag     User-supplied value to help identify request.
738  * @param[in]  pOpData          Structure containing all the data needed to
739  *                              perform the operation. The client code
740  *                              allocates the memory for this structure. This
741  *                              component takes ownership of the memory until
742  *                              it is returned in the callback.
743  * @param[out] pVerifyStatus    In synchronous mode, set to CPA_FALSE if the
744  *                              point is NOT on the curve or at infinity. Set
745  *                              to CPA_TRUE if the point is on the curve.
746  *
747  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
748  * @retval CPA_STATUS_FAIL          Function failed.
749  * @retval CPA_STATUS_RETRY         Resubmit the request.
750  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
751  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
752  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
753  *                                  the request.
754  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
755  *
756  * @pre
757  *      The component has been initialized via cpaCyStartInstance function.
758  * @post
759  *      None
760  * @note
761  *      When pCb is non-NULL an asynchronous callback of type
762  *      CpaCyEcdsaVerifyCbFunc is generated in response to this function
763  *      call.
764  *      For optimal performance, data pointers SHOULD be 8-byte aligned.
765  *
766  * @see
767  *      CpaCyEcdsaVerifyOpData,
768  *      CpaCyEcdsaVerifyCbFunc
769  *
770  *****************************************************************************/
771 CpaStatus
772 cpaCyEcdsaVerify(const CpaInstanceHandle instanceHandle,
773         const CpaCyEcdsaVerifyCbFunc pCb,
774         void *pCallbackTag,
775         const CpaCyEcdsaVerifyOpData *pOpData,
776         CpaBoolean *pVerifyStatus);
777 
778 
779 /**
780  *****************************************************************************
781  * @ingroup cpaCyEcdsa
782  *      Query statistics for a specific ECDSA instance.
783  *
784  * @description
785  *      This function will query a specific instance of the ECDSA implementation
786  *      for statistics. The user MUST allocate the CpaCyEcdsaStats64 structure
787  *      and pass the reference to that structure into this function call. This
788  *      function writes the statistic results into the passed in
789  *      CpaCyEcdsaStats64 structure.
790  *
791  *      Note: statistics returned by this function do not interrupt current data
792  *      processing and as such can be slightly out of sync with operations that
793  *      are in progress during the statistics retrieval process.
794  *
795  * @context
796  *      This is a synchronous function and it can sleep. It MUST NOT be
797  *      executed in a context that DOES NOT permit sleeping.
798  * @assumptions
799  *      None
800  * @sideEffects
801  *      None
802  * @blocking
803  *      This function is synchronous and blocking.
804  * @reentrant
805  *      No
806  * @threadSafe
807  *      Yes
808  *
809  * @param[in]  instanceHandle       Instance handle.
810  * @param[out] pEcdsaStats          Pointer to memory into which the statistics
811  *                                  will be written.
812  *
813  * @retval CPA_STATUS_SUCCESS       Function executed successfully.
814  * @retval CPA_STATUS_FAIL          Function failed.
815  * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
816  * @retval CPA_STATUS_RESOURCE      Error related to system resources.
817  * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
818  *                                  the request.
819  * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
820  *
821  * @pre
822  *      Component has been initialized.
823  * @post
824  *      None
825  * @note
826  *      This function operates in a synchronous manner and no asynchronous
827  *      callback will be generated.
828  * @see
829  *      CpaCyEcdsaStats64
830  *****************************************************************************/
831 CpaStatus
832 cpaCyEcdsaQueryStats64(const CpaInstanceHandle instanceHandle,
833         CpaCyEcdsaStats64 *pEcdsaStats);
834 
835 #ifdef __cplusplus
836 } /* close the extern "C" { */
837 #endif
838 
839 #endif /*CPA_CY_ECDSA_H_*/
840