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_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
67extern "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 *****************************************************************************/
100typedef 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 *****************************************************************************/
148typedef 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 *****************************************************************************/
191typedef 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 *****************************************************************************/
243typedef 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 * @ingroup cpaCyEcdsa
273 *      Cryptographic ECDSA Statistics.
274 * @description
275 *      This structure contains statistics on the Cryptographic ECDSA
276 *      operations. Statistics are set to zero when the component is
277 *      initialized, and are collected per instance.
278 *
279 ****************************************************************************/
280typedef struct _CpaCyEcdsaStats64 {
281    Cpa64U numEcdsaSignRRequests;
282    /**< Total number of ECDSA Sign R operation requests. */
283    Cpa64U numEcdsaSignRRequestErrors;
284    /**< Total number of ECDSA Sign R operation requests that had an error and
285     * could not be processed. */
286    Cpa64U numEcdsaSignRCompleted;
287    /**< Total number of ECDSA Sign R operation requests that completed
288     * successfully. */
289    Cpa64U numEcdsaSignRCompletedErrors;
290    /**< Total number of ECDSA Sign R operation requests that could
291     * not be completed successfully due to errors. */
292    Cpa64U numEcdsaSignRCompletedOutputInvalid;
293    /**< Total number of ECDSA Sign R operation requests could not be completed
294     * successfully due to an invalid output.
295     * Note that this does not indicate an error. */
296    Cpa64U numEcdsaSignSRequests;
297    /**< Total number of ECDSA Sign S operation requests. */
298    Cpa64U numEcdsaSignSRequestErrors;
299    /**< Total number of ECDSA Sign S operation requests that had an error and
300     * could not be processed. */
301    Cpa64U numEcdsaSignSCompleted;
302    /**< Total number of ECDSA Sign S operation requests that completed
303     * successfully. */
304    Cpa64U numEcdsaSignSCompletedErrors;
305    /**< Total number of ECDSA Sign S operation requests that could
306     * not be completed successfully due to errors. */
307    Cpa64U numEcdsaSignSCompletedOutputInvalid;
308    /**< Total number of ECDSA Sign S operation requests could not be completed
309     * successfully due to an invalid output.
310     * Note that this does not indicate an error. */
311    Cpa64U numEcdsaSignRSRequests;
312    /**< Total number of ECDSA Sign R & S operation requests. */
313    Cpa64U numEcdsaSignRSRequestErrors;
314    /**< Total number of ECDSA Sign R & S operation requests that had an
315     * error and could not be processed. */
316    Cpa64U numEcdsaSignRSCompleted;
317    /**< Total number of ECDSA Sign R & S operation requests that completed
318     * successfully. */
319    Cpa64U numEcdsaSignRSCompletedErrors;
320    /**< Total number of ECDSA Sign R & S operation requests that could
321     * not be completed successfully due to errors. */
322    Cpa64U numEcdsaSignRSCompletedOutputInvalid;
323    /**< Total number of ECDSA Sign R & S operation requests could not be
324     * completed successfully due to an invalid output.
325     * Note that this does not indicate an error. */
326    Cpa64U numEcdsaVerifyRequests;
327    /**< Total number of ECDSA Verification operation requests. */
328    Cpa64U numEcdsaVerifyRequestErrors;
329    /**< Total number of ECDSA Verification operation requests that had an
330     * error and could not be processed. */
331    Cpa64U numEcdsaVerifyCompleted;
332    /**< Total number of ECDSA Verification operation requests that completed
333     * successfully. */
334    Cpa64U numEcdsaVerifyCompletedErrors;
335    /**< Total number of ECDSA Verification operation requests that could
336     * not be completed successfully due to errors. */
337    Cpa64U numEcdsaVerifyCompletedOutputInvalid;
338    /**< Total number of ECDSA Verification operation requests that resulted
339     * in an invalid output.
340     * Note that this does not indicate an error. */
341    Cpa64U numKptEcdsaSignRSCompletedOutputInvalid;
342    /**< Total number of KPT ECDSA Sign R & S operation requests could not be
343     * completed successfully due to an invalid output.
344     * Note that this does not indicate an error. */
345    Cpa64U numKptEcdsaSignRSCompleted;
346    /**< Total number of KPT ECDSA Sign R & S operation requests that completed
347     * successfully. */
348    Cpa64U numKptEcdsaSignRSRequests;
349    /**< Total number of KPT ECDSA Sign R & S operation requests. */
350    Cpa64U numKptEcdsaSignRSRequestErrors;
351    /**< Total number of KPT ECDSA Sign R & S operation requests that had an
352     * error and could not be processed. */
353    Cpa64U numKptEcdsaSignRSCompletedErrors;
354    /**< Total number of KPT ECDSA Sign R & S operation requests that could
355     * not be completed successfully due to errors. */
356} CpaCyEcdsaStats64;
357
358
359/**
360 *****************************************************************************
361 * @ingroup cpaCyEcdsa
362 *      Definition of a generic callback function invoked for a number of the
363 *      ECDSA Sign API functions.
364 *
365 * @description
366 *      This is the prototype for the CpaCyEcdsaGenSignCbFunc callback function.
367 *
368 * @context
369 *      This callback function can be executed in a context that DOES NOT
370 *      permit sleeping to occur.
371 * @assumptions
372 *      None
373 * @sideEffects
374 *      None
375 * @reentrant
376 *      No
377 * @threadSafe
378 *      Yes
379 *
380 * @param[in] pCallbackTag      User-supplied value to help identify request.
381 * @param[in] status            Status of the operation. Valid values are
382 *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
383 *                              CPA_STATUS_UNSUPPORTED.
384 * @param[in] pOpData           Opaque pointer to Operation data supplied in
385 *                              request.
386 * @param[in] multiplyStatus    Status of the point multiplication.
387 * @param[in] pOut              Output data from the request.
388 *
389 * @retval
390 *      None
391 * @pre
392 *      Component has been initialized.
393 * @post
394 *      None
395 * @note
396 *      None
397 * @see
398 *      cpaCyEcdsaSignR()
399 *      cpaCyEcdsaSignS()
400 *
401 *****************************************************************************/
402typedef void (*CpaCyEcdsaGenSignCbFunc)(void *pCallbackTag,
403        CpaStatus status,
404        void *pOpData,
405        CpaBoolean multiplyStatus,
406        CpaFlatBuffer *pOut);
407
408
409/**
410 *****************************************************************************
411 * @ingroup cpaCyEcdsa
412 *      Definition of callback function invoked for cpaCyEcdsaSignRS
413 *      requests.
414 *
415 * @description
416 *      This is the prototype for the CpaCyEcdsaSignRSCbFunc callback function,
417 *      which will provide the ECDSA message signature r and s parameters.
418 *
419 * @context
420 *      This callback function can be executed in a context that DOES NOT
421 *      permit sleeping to occur.
422 * @assumptions
423 *      None
424 * @sideEffects
425 *      None
426 * @reentrant
427 *      No
428 * @threadSafe
429 *      Yes
430 *
431 * @param[in] pCallbackTag      User-supplied value to help identify request.
432 * @param[in] status            Status of the operation. Valid values are
433 *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
434 *                              CPA_STATUS_UNSUPPORTED.
435 * @param[in] pOpData           Operation data pointer supplied in request.
436 * @param[in] multiplyStatus    Status of the point multiplication.
437 * @param[in] pR                Ecdsa message signature r.
438 * @param[in] pS                Ecdsa message signature s.
439 *
440 *
441 * @retval
442 *      None
443 * @pre
444 *      Component has been initialized.
445 * @post
446 *      None
447 * @note
448 *      None
449 * @see
450 *      cpaCyEcdsaSignRS()
451 *
452 *****************************************************************************/
453typedef void (*CpaCyEcdsaSignRSCbFunc)(void *pCallbackTag,
454        CpaStatus status,
455        void *pOpData,
456        CpaBoolean multiplyStatus,
457        CpaFlatBuffer *pR,
458        CpaFlatBuffer *pS);
459
460
461/**
462 *****************************************************************************
463 * @ingroup cpaCyEcdsa
464 *      Definition of callback function invoked for cpaCyEcdsaVerify requests.
465 *
466 * @description
467 *      This is the prototype for the CpaCyEcdsaVerifyCbFunc callback function.
468 *
469 * @context
470 *      This callback function can be executed in a context that DOES NOT
471 *      permit sleeping to occur.
472 * @assumptions
473 *      None
474 * @sideEffects
475 *      None
476 * @reentrant
477 *      No
478 * @threadSafe
479 *      Yes
480 *
481 * @param[in] pCallbackTag      User-supplied value to help identify request.
482 * @param[in] status            Status of the operation. Valid values are
483 *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
484 *                              CPA_STATUS_UNSUPPORTED.
485 * @param[in] pOpData           Operation data pointer supplied in request.
486 * @param[in] verifyStatus      The verification status.
487 *
488 * @retval
489 *      None
490 * @pre
491 *      Component has been initialized.
492 * @post
493 *      None
494 * @note
495 *      None
496 * @see
497 *      cpaCyEcdsaVerify()
498 *
499 *****************************************************************************/
500typedef void (*CpaCyEcdsaVerifyCbFunc)(void *pCallbackTag,
501        CpaStatus status,
502        void *pOpData,
503        CpaBoolean verifyStatus);
504
505
506/**
507 *****************************************************************************
508 * @ingroup cpaCyEcdsa
509 *      Generate ECDSA Signature R.
510 *
511 * @description
512 *      This function generates ECDSA Signature R as per ANSI X9.62 2005
513 *      section 7.3.
514 *
515 * @context
516 *      When called as an asynchronous function it cannot sleep. It can be
517 *      executed in a context that does not permit sleeping.
518 *      When called as a synchronous function it may sleep. It MUST NOT be
519 *      executed in a context that DOES NOT permit sleeping.
520 * @assumptions
521 *      None
522 * @sideEffects
523 *      None
524 * @blocking
525 *      Yes when configured to operate in synchronous mode.
526 * @reentrant
527 *      No
528 * @threadSafe
529 *      Yes
530 *
531 * @param[in]  instanceHandle   Instance handle.
532 * @param[in]  pCb              Callback function pointer. If this is set to a
533 *                              NULL value the function will operate
534 *                              synchronously.
535 * @param[in]  pCallbackTag     User-supplied value to help identify request.
536 * @param[in]  pOpData          Structure containing all the data needed to
537 *                              perform the operation. The client code
538 *                              allocates the memory for this structure. This
539 *                              component takes ownership of the memory until
540 *                              it is returned in the callback.
541 * @param[out] pSignStatus      In synchronous mode, the multiply output is
542 *                              valid (CPA_TRUE) or the output is invalid
543 *                              (CPA_FALSE).
544 * @param[out] pR               ECDSA message signature r.
545 *
546 *
547 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
548 * @retval CPA_STATUS_FAIL          Function failed.
549 * @retval CPA_STATUS_RETRY         Resubmit the request.
550 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
551 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
552 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
553 *                                  the request.
554 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
555 *
556 * @pre
557 *      The component has been initialized via cpaCyStartInstance function.
558 * @post
559 *      None
560 * @note
561 *      When pCb is non-NULL an asynchronous callback is generated in response
562 *      to this function call.
563 *      For optimal performance, data pointers SHOULD be 8-byte aligned.
564 *
565 * @see
566 *      None
567 *****************************************************************************/
568CpaStatus
569cpaCyEcdsaSignR(const CpaInstanceHandle instanceHandle,
570        const CpaCyEcdsaGenSignCbFunc pCb,
571        void *pCallbackTag,
572        const CpaCyEcdsaSignROpData *pOpData,
573        CpaBoolean *pSignStatus,
574        CpaFlatBuffer *pR);
575
576
577/**
578 *****************************************************************************
579 * @ingroup cpaCyEcdsa
580 *      Generate ECDSA Signature S.
581 *
582 * @description
583 *      This function generates ECDSA Signature S as per ANSI X9.62 2005
584 *      section 7.3.
585 *
586 * @context
587 *      When called as an asynchronous function it cannot sleep. It can be
588 *      executed in a context that does not permit sleeping.
589 *      When called as a synchronous function it may sleep. It MUST NOT be
590 *      executed in a context that DOES NOT permit sleeping.
591 * @assumptions
592 *      None
593 * @sideEffects
594 *      None
595 * @blocking
596 *      Yes when configured to operate in synchronous mode.
597 * @reentrant
598 *      No
599 * @threadSafe
600 *      Yes
601 *
602 * @param[in]  instanceHandle   Instance handle.
603 * @param[in]  pCb              Callback function pointer. If this is set to a
604 *                              NULL value the function will operate
605 *                              synchronously.
606 * @param[in]  pCallbackTag     User-supplied value to help identify request.
607 * @param[in]  pOpData          Structure containing all the data needed to
608 *                              perform the operation. The client code
609 *                              allocates the memory for this structure. This
610 *                              component takes ownership of the memory until
611 *                              it is returned in the callback.
612 * @param[out] pSignStatus      In synchronous mode, the multiply output is
613 *                              valid (CPA_TRUE) or the output is invalid
614 *                              (CPA_FALSE).
615 * @param[out] pS               ECDSA message signature s.
616 *
617 *
618 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
619 * @retval CPA_STATUS_FAIL          Function failed.
620 * @retval CPA_STATUS_RETRY         Resubmit the request.
621 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
622 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
623 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
624 *                                  the request.
625 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
626 *
627 * @pre
628 *      The component has been initialized via cpaCyStartInstance function.
629 * @post
630 *      None
631 * @note
632 *      When pCb is non-NULL an asynchronous callback is generated in response
633 *      to this function call.
634 *      For optimal performance, data pointers SHOULD be 8-byte aligned.
635 *
636 * @see
637 *      None
638 *****************************************************************************/
639CpaStatus
640cpaCyEcdsaSignS(const CpaInstanceHandle instanceHandle,
641        const CpaCyEcdsaGenSignCbFunc pCb,
642        void *pCallbackTag,
643        const CpaCyEcdsaSignSOpData *pOpData,
644        CpaBoolean *pSignStatus,
645        CpaFlatBuffer *pS);
646
647
648/**
649 *****************************************************************************
650 * @ingroup cpaCyEcdsa
651 *      Generate ECDSA Signature R & S.
652 *
653 * @description
654 *      This function generates ECDSA Signature R & S as per ANSI X9.62 2005
655 *      section 7.3.
656 *
657 * @context
658 *      When called as an asynchronous function it cannot sleep. It can be
659 *      executed in a context that does not permit sleeping.
660 *      When called as a synchronous function it may sleep. It MUST NOT be
661 *      executed in a context that DOES NOT permit sleeping.
662 * @assumptions
663 *      None
664 * @sideEffects
665 *      None
666 * @blocking
667 *      Yes when configured to operate in synchronous mode.
668 * @reentrant
669 *      No
670 * @threadSafe
671 *      Yes
672 *
673 * @param[in]  instanceHandle   Instance handle.
674 * @param[in]  pCb              Callback function pointer. If this is set to a
675 *                              NULL value the function will operate
676 *                              synchronously.
677 * @param[in]  pCallbackTag     User-supplied value to help identify request.
678 * @param[in]  pOpData          Structure containing all the data needed to
679 *                              perform the operation. The client code
680 *                              allocates the memory for this structure. This
681 *                              component takes ownership of the memory until
682 *                              it is returned in the callback.
683 * @param[out] pSignStatus      In synchronous mode, the multiply output is
684 *                              valid (CPA_TRUE) or the output is invalid
685 *                              (CPA_FALSE).
686 * @param[out] pR               ECDSA message signature r.
687 * @param[out] pS               ECDSA message signature s.
688 *
689 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
690 * @retval CPA_STATUS_FAIL          Function failed.
691 * @retval CPA_STATUS_RETRY         Resubmit the request.
692 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
693 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
694 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
695 *                                  the request.
696 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
697 *
698 * @pre
699 *      The component has been initialized via cpaCyStartInstance function.
700 * @post
701 *      None
702 * @note
703 *      When pCb is non-NULL an asynchronous callback is generated in response
704 *      to this function call.
705 *      For optimal performance, data pointers SHOULD be 8-byte aligned.
706 *
707 * @see
708 *      None
709 *****************************************************************************/
710CpaStatus
711cpaCyEcdsaSignRS(const CpaInstanceHandle instanceHandle,
712        const CpaCyEcdsaSignRSCbFunc pCb,
713        void *pCallbackTag,
714        const CpaCyEcdsaSignRSOpData *pOpData,
715        CpaBoolean *pSignStatus,
716        CpaFlatBuffer *pR,
717        CpaFlatBuffer *pS);
718
719
720/**
721 *****************************************************************************
722 * @ingroup cpaCyEcdsa
723 *      Verify ECDSA Public Key.
724 *
725 * @description
726 *      This function performs ECDSA Verify as per ANSI X9.62 2005 section 7.4.
727 *
728 *      A response status of ok (verifyStatus == CPA_TRUE) means that the
729 *      signature was verified
730 *
731 * @context
732 *      When called as an asynchronous function it cannot sleep. It can be
733 *      executed in a context that does not permit sleeping.
734 *      When called as a synchronous function it may sleep. It MUST NOT be
735 *      executed in a context that DOES NOT permit sleeping.
736 * @assumptions
737 *      None
738 * @sideEffects
739 *      None
740 * @blocking
741 *      Yes when configured to operate in synchronous mode.
742 * @reentrant
743 *      No
744 * @threadSafe
745 *      Yes
746 *
747 * @param[in]  instanceHandle   Instance handle.
748 * @param[in]  pCb              Callback function pointer. If this is set to
749 *                              a NULL value the function will operate
750 *                              synchronously.
751 * @param[in]  pCallbackTag     User-supplied value to help identify request.
752 * @param[in]  pOpData          Structure containing all the data needed to
753 *                              perform the operation. The client code
754 *                              allocates the memory for this structure. This
755 *                              component takes ownership of the memory until
756 *                              it is returned in the callback.
757 * @param[out] pVerifyStatus    In synchronous mode, set to CPA_FALSE if the
758 *                              point is NOT on the curve or at infinity. Set
759 *                              to CPA_TRUE if the point is on the curve.
760 *
761 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
762 * @retval CPA_STATUS_FAIL          Function failed.
763 * @retval CPA_STATUS_RETRY         Resubmit the request.
764 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
765 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
766 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
767 *                                  the request.
768 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
769 *
770 * @pre
771 *      The component has been initialized via cpaCyStartInstance function.
772 * @post
773 *      None
774 * @note
775 *      When pCb is non-NULL an asynchronous callback of type
776 *      CpaCyEcdsaVerifyCbFunc is generated in response to this function
777 *      call.
778 *      For optimal performance, data pointers SHOULD be 8-byte aligned.
779 *
780 * @see
781 *      CpaCyEcdsaVerifyOpData,
782 *      CpaCyEcdsaVerifyCbFunc
783 *
784 *****************************************************************************/
785CpaStatus
786cpaCyEcdsaVerify(const CpaInstanceHandle instanceHandle,
787        const CpaCyEcdsaVerifyCbFunc pCb,
788        void *pCallbackTag,
789        const CpaCyEcdsaVerifyOpData *pOpData,
790        CpaBoolean *pVerifyStatus);
791
792/**
793 *****************************************************************************
794 * @ingroup cpaCyEcdsa
795 *      Query statistics for a specific ECDSA instance.
796 *
797 * @description
798 *      This function will query a specific instance of the ECDSA implementation
799 *      for statistics. The user MUST allocate the CpaCyEcdsaStats64 structure
800 *      and pass the reference to that structure into this function call. This
801 *      function writes the statistic results into the passed in
802 *      CpaCyEcdsaStats64 structure.
803 *
804 *      Note: statistics returned by this function do not interrupt current data
805 *      processing and as such can be slightly out of sync with operations that
806 *      are in progress during the statistics retrieval process.
807 *
808 * @context
809 *      This is a synchronous function and it can sleep. It MUST NOT be
810 *      executed in a context that DOES NOT permit sleeping.
811 * @assumptions
812 *      None
813 * @sideEffects
814 *      None
815 * @blocking
816 *      This function is synchronous and blocking.
817 * @reentrant
818 *      No
819 * @threadSafe
820 *      Yes
821 *
822 * @param[in]  instanceHandle       Instance handle.
823 * @param[out] pEcdsaStats          Pointer to memory into which the statistics
824 *                                  will be written.
825 *
826 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
827 * @retval CPA_STATUS_FAIL          Function failed.
828 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
829 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
830 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
831 *                                  the request.
832 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
833 *
834 * @pre
835 *      Component has been initialized.
836 * @post
837 *      None
838 * @note
839 *      This function operates in a synchronous manner and no asynchronous
840 *      callback will be generated.
841 * @see
842 *      CpaCyEcdsaStats64
843 *****************************************************************************/
844CpaStatus
845cpaCyEcdsaQueryStats64(const CpaInstanceHandle instanceHandle,
846        CpaCyEcdsaStats64 *pEcdsaStats);
847
848#ifdef __cplusplus
849} /* close the extern "C" { */
850#endif
851
852#endif /*CPA_CY_ECDSA_H_*/
853