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_common.h
45  *
46  * @defgroup cpaCy Cryptographic API
47  *
48  * @ingroup cpa
49  *
50  * @description
51  *      These functions specify the Cryptographic API.
52  *
53  *****************************************************************************/
54 
55 /**
56  *****************************************************************************
57  * @file cpa_cy_common.h
58  * @defgroup cpaCyCommon Cryptographic Common API
59  *
60  * @ingroup cpaCy
61  *
62  * @description
63  *      This file specifies items which are common for both the asymmetric
64  *      (public key cryptography) and the symmetric operations for the
65  *      Cryptographic API.
66  *
67  *****************************************************************************/
68 #ifndef CPA_CY_COMMON_H
69 #define CPA_CY_COMMON_H
70 
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 
75 #include "cpa.h"
76 
77 /**
78  *****************************************************************************
79  * @ingroup cpa_cyCommon
80  *      CPA CY Major Version Number
81  * @description
82  *      The CPA_CY API major version number. This number will be incremented
83  *      when significant churn to the API has occurred. The combination of the
84  *      major and minor number definitions represent the complete version number
85  *      for this interface.
86  *
87  *****************************************************************************/
88 #define CPA_CY_API_VERSION_NUM_MAJOR (3)
89 
90 /**
91  *****************************************************************************
92  * @ingroup cpa_cyCommon
93  *       CPA CY Minor Version Number
94  * @description
95  *      The CPA_CY API minor version number. This number will be incremented
96  *      when minor changes to the API has occurred. The combination of the major
97  *      and minor number definitions represent the complete version number for
98  *      this interface.
99  *
100  *****************************************************************************/
101 #define CPA_CY_API_VERSION_NUM_MINOR (0)
102 
103 /**
104  *****************************************************************************
105  * @file cpa_cy_common.h
106  * @ingroup cpa_cyCommon
107  *       CPA CY API version at least
108  * @description
109  *      The minimal supported CPA_CY API version. Allow to check if the API
110  *      version is equal or above some version to avoid compilation issues
111  *      with an older API version.
112  *
113  *****************************************************************************/
114 #define CPA_CY_API_VERSION_AT_LEAST(major, minor)                              \
115     (CPA_CY_API_VERSION_NUM_MAJOR > major ||                                   \
116      (CPA_CY_API_VERSION_NUM_MAJOR == major &&                                 \
117       CPA_CY_API_VERSION_NUM_MINOR >= minor))
118 
119 /**
120  *****************************************************************************
121  * @file cpa_cy_common.h
122  * @ingroup cpa_cyCommon
123  *       CPA CY API version less than
124  * @description
125  *      The maximum supported CPA_CY API version. Allow to check if the API
126  *      version is below some version to avoid compilation issues with a newer
127  *      API version.
128  *
129  *****************************************************************************/
130 #define CPA_CY_API_VERSION_LESS_THAN(major, minor)                             \
131     (CPA_CY_API_VERSION_NUM_MAJOR < major ||                                   \
132      (CPA_CY_API_VERSION_NUM_MAJOR == major &&                                 \
133       CPA_CY_API_VERSION_NUM_MINOR < minor))
134 
135 /**
136  *****************************************************************************
137  * @file cpa_cy_common.h
138  * @ingroup cpaCyCommon
139  *      Request priority
140  * @description
141  *      Enumeration of priority of the request to be given to the API.
142  *      Currently two levels - HIGH and NORMAL are supported. HIGH priority
143  *      requests will be prioritized on a "best-effort" basis over requests
144  *      that are marked with a NORMAL priority.
145  *
146  *****************************************************************************/
147 typedef enum _CpaCyPriority
148 {
149     CPA_CY_PRIORITY_NORMAL = 1, /**< Normal priority */
150     CPA_CY_PRIORITY_HIGH /**< High priority */
151 } CpaCyPriority;
152 
153 /*****************************************************************************/
154 /* Callback Definitions                                                      */
155 /*****************************************************************************/
156 /**
157  *****************************************************************************
158  * @ingroup cpaCyCommon
159  *      Definition of the crypto generic callback function
160  *
161  * @description
162  *      This data structure specifies the prototype for a generic callback
163  *      function
164  *
165  * @context
166  *      This callback function can be executed in a context that DOES NOT
167  *      permit sleeping to occur.
168  *
169  * @assumptions
170  *      None
171  * @sideEffects
172  *      None
173  * @reentrant
174  *      No
175  * @threadSafe
176  *      Yes
177  *
178  * @param[in] pCallbackTag Opaque value provided by user while making individual
179  *                         function call.
180  * @param[in] status       Status of the operation. Valid values are
181  *                         CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
182  *                         CPA_STATUS_UNSUPPORTED.
183  * @param[in] pOpData      Opaque Pointer to the operation data that was
184  *                         submitted in the request
185  *
186  * @retval
187  *      None
188  * @pre
189  *      Component has been initialized.
190  * @post
191  *      None
192  * @note
193  *      None
194  * @see
195  *      cpaCyKeyGenSsl()
196  *
197  *****************************************************************************/
198 typedef void (*CpaCyGenericCbFunc)(void *pCallbackTag,
199         CpaStatus status,
200         void *pOpData);
201 
202 /**
203  *****************************************************************************
204  * @ingroup cpaCyCommon
205  *      Definition of generic callback function with an additional output
206  *      CpaFlatBuffer parameter.
207  *
208  * @description
209  *      This data structure specifies the prototype for a generic callback
210  *      function which provides an output buffer (of type CpaFlatBuffer).
211  *
212  * @context
213  *      This callback function can be executed in a context that DOES NOT
214  *      permit sleeping to occur.
215  *
216  * @assumptions
217  *      None
218  * @sideEffects
219  *      None
220  * @reentrant
221  *      No
222  * @threadSafe
223  *      Yes
224  *
225  * @param[in] pCallbackTag Opaque value provided by user while making individual
226  *                         function call.
227  * @param[in] status       Status of the operation. Valid values are
228  *                         CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
229  *                         CPA_STATUS_UNSUPPORTED.
230  * @param[in] pOpData      Opaque Pointer to the operation data that was
231  *                         submitted in the request
232  * @param[in] pOut         Pointer to the output buffer provided in the request
233  *                         invoking this callback.
234  *
235  * @retval
236  *      None
237  * @pre
238  *      Component has been initialized.
239  * @post
240  *      None
241  * @note
242  *      None
243  * @see
244  *      None
245  *
246  *****************************************************************************/
247 typedef void (*CpaCyGenFlatBufCbFunc)(void *pCallbackTag,
248         CpaStatus status,
249         void *pOpdata,
250         CpaFlatBuffer *pOut);
251 
252 /**
253  *****************************************************************************
254  * @ingroup cpaCyCommon
255  *      Function to return the size of the memory which must be allocated for
256  *      the pPrivateMetaData member of CpaBufferList.
257  *
258  * @description
259  *      This function is used obtain the size (in bytes) required to allocate
260  *      a buffer descriptor for the pPrivateMetaData member in the
261  *      CpaBufferList the structure.
262  *      Should the function return zero then no meta data is required for the
263  *      buffer list.
264  *
265  * @context
266  *      This function may be called from any context.
267  * @assumptions
268  *      None
269  * @sideEffects
270  *      None
271  * @blocking
272  *      No
273  * @reentrant
274  *      No
275  * @threadSafe
276  *      Yes
277  *
278  * @param[in]  instanceHandle      Handle to an instance of this API.
279  * @param[in]  numBuffers          The number of pointers in the CpaBufferList.
280  *                                 this is the maximum number of CpaFlatBuffers
281  *                                 which may be contained in this CpaBufferList.
282  * @param[out] pSizeInBytes        Pointer to the size in bytes of memory to be
283  *                                 allocated when the client wishes to allocate
284  *                                 a cpaFlatBuffer
285  *
286  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
287  * @retval CPA_STATUS_FAIL           Function failed.
288  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
289  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
290  *
291  * @pre
292  *      None.
293  * @post
294  *      None
295  * @note
296  *      None
297  * @see
298  *      cpaCyGetInstances()
299  *
300  *****************************************************************************/
301 CpaStatus
302 cpaCyBufferListGetMetaSize(const CpaInstanceHandle instanceHandle,
303         Cpa32U numBuffers,
304         Cpa32U *pSizeInBytes);
305 
306 /**
307  *****************************************************************************
308  * @ingroup cpaCyCommon
309  *      Function to return a string indicating the specific error that occurred
310  *      for a particular instance.
311  *
312  * @description
313  *      When a function invocation on a particular instance returns an error,
314  *      the client can invoke this function to query the instance for a null
315  *      terminated string which describes the general error condition, and if
316  *      available additional text on the specific error.
317  *      The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for
318  *      the buffer string.
319  *
320  * @context
321  *      This function may be called from any context.
322  * @assumptions
323  *      None
324  * @sideEffects
325  *      None
326  * @blocking
327  *      No
328  * @reentrant
329  *      No
330  * @threadSafe
331  *      Yes
332  *
333  * @param[in]  instanceHandle   Handle to an instance of this API.
334  * @param[in]  errStatus        The error condition that occurred
335  * @param[out] pStatusText      Pointer to the string buffer that will be
336  *                              updated with a null terminated status text
337  *                              string.
338  *                              The invoking application MUST allocate this
339  *                              buffer to be CPA_STATUS_MAX_STR_LENGTH_IN_BYTES.
340  *
341  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
342  * @retval CPA_STATUS_FAIL           Function failed. Note, In this scenario it
343  *                                   is INVALID to call this function a further
344  *                                   time.
345  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
346  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
347  *
348  * @pre
349  *      None.
350  * @post
351  *      None
352  * @note
353  *      None
354  * @see
355  *      CpaStatus
356  *
357  *****************************************************************************/
358 CpaStatus
359 cpaCyGetStatusText(const CpaInstanceHandle instanceHandle,
360         CpaStatus errStatus,
361         Cpa8S *pStatusText);
362 
363 /*****************************************************************************/
364 /* Instance Discovery Functions                                              */
365 /*****************************************************************************/
366 /**
367  *****************************************************************************
368  * @ingroup cpaCyCommon
369  *      Get the number of instances that are supported by the API
370  *      implementation.
371  *
372  * @description
373  *     This function will get the number of instances that are supported
374  *     by an implementation of the Cryptographic API. This number is then
375  *     used to determine the size of the array that must be passed to
376  *     @ref cpaCyGetInstances().
377  *
378  * @context
379  *      This function MUST NOT be called from an interrupt context as it MAY
380  *      sleep.
381  * @assumptions
382  *      None
383  * @sideEffects
384  *      None
385  * @blocking
386  *      This function is synchronous and blocking.
387  * @reentrant
388  *      No
389  * @threadSafe
390  *      Yes
391  *
392  * @param[out] pNumInstances         Pointer to where the number of
393  *                                   instances will be written.
394  *
395  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
396  * @retval CPA_STATUS_FAIL           Function failed.
397  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
398  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
399  *
400  * @pre
401  *      None
402  * @post
403  *      None
404  * @note
405  *      This function operates in a synchronous manner and no asynchronous
406  *      callback will be generated
407  *
408  * @see
409  *      cpaCyGetInstances
410  *
411  *****************************************************************************/
412 CpaStatus
413 cpaCyGetNumInstances(Cpa16U *pNumInstances);
414 
415 /**
416  *****************************************************************************
417  * @ingroup cpaCyCommon
418  *      Get the handles to the instances that are supported by the
419  *      API implementation.
420  *
421  * @description
422  *      This function will return handles to the instances that are
423  *      supported by an implementation of the Cryptographic API. These
424  *      instance handles can then be used as input parameters with other
425  *      Cryptographic API functions.
426  *
427  *      This function will populate an array that has been allocated by the
428  *      caller. The size of this API will have been determined by the
429  *      cpaCyGetNumInstances() function.
430  *
431  * @context
432  *      This function MUST NOT be called from an interrupt context as it MAY
433  *      sleep.
434  * @assumptions
435  *      None
436  * @sideEffects
437  *      None
438  * @blocking
439  *      This function is synchronous and blocking.
440  * @reentrant
441  *      No
442  * @threadSafe
443  *      Yes
444  *
445  * @param[in]     numInstances       Size of the array.  If the value is not
446  *                                      the same as the number of instances
447  *                                      supported, then an error (@ref
448  *                                      CPA_STATUS_INVALID_PARAM) is returned.
449  * @param[in,out] cyInstances        Pointer to where the instance
450  *                                   handles will be written.
451  *
452  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
453  * @retval CPA_STATUS_FAIL           Function failed.
454  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
455  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
456  *
457  * @pre
458  *      None
459  * @post
460  *      None
461  * @note
462  *      This function operates in a synchronous manner and no asynchronous
463  *      callback will be generated
464  *
465  * @see
466  *      cpaCyGetNumInstances
467  *
468  *****************************************************************************/
469 CpaStatus
470 cpaCyGetInstances(Cpa16U numInstances,
471         CpaInstanceHandle *cyInstances);
472 
473 /**
474  *****************************************************************************
475  * @ingroup cpaCyCommon
476  *      Function to get information on a particular instance.
477  *
478  * @deprecated
479  *         As of v1.3 of the Crypto API, this function has been deprecated,
480  *         replaced by @ref cpaCyInstanceGetInfo2.
481  *
482  * @description
483  *      This function will provide instance specific information through a
484  *      @ref CpaInstanceInfo structure.
485  *
486  * @context
487  *      This function may be called from any context.
488  * @assumptions
489  *      None
490  * @sideEffects
491  *      None
492  * @blocking
493  *      No
494  * @reentrant
495  *      No
496  * @threadSafe
497  *      Yes
498  *
499  * @param[in]  instanceHandle       Handle to an instance of this API to be
500  *                                  initialized.
501  * @param[out] pInstanceInfo        Pointer to the memory location allocated by
502  *                                  the client into which the CpaInstanceInfo
503  *                                  structure will be written.
504  *
505  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
506  * @retval CPA_STATUS_FAIL           Function failed.
507  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
508  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
509  *
510  * @pre
511  *      The client has retrieved an instanceHandle from successive calls to
512  *      @ref cpaCyGetNumInstances and @ref cpaCyGetInstances.
513  * @post
514  *      None
515  * @note
516  *      None
517  * @see
518  *      cpaCyGetNumInstances,
519  *      cpaCyGetInstances,
520  *      CpaInstanceInfo
521  *
522  *****************************************************************************/
523 CpaStatus CPA_DEPRECATED
524 cpaCyInstanceGetInfo(const CpaInstanceHandle instanceHandle,
525         struct _CpaInstanceInfo * pInstanceInfo);
526 
527 /**
528  *****************************************************************************
529  * @ingroup cpaCyCommon
530  *      Function to get information on a particular instance.
531  *
532  * @description
533  *      This function will provide instance specific information through a
534  *      @ref CpaInstanceInfo2 structure.
535  *      Supersedes @ref cpaCyInstanceGetInfo.
536  *
537  * @context
538  *      This function may be called from any context.
539  * @assumptions
540  *      None
541  * @sideEffects
542  *      None
543  * @blocking
544  *      No
545  * @reentrant
546  *      No
547  * @threadSafe
548  *      Yes
549  *
550  * @param[in]  instanceHandle       Handle to an instance of this API to be
551  *                                  initialized.
552  * @param[out] pInstanceInfo2       Pointer to the memory location allocated by
553  *                                  the client into which the CpaInstanceInfo2
554  *                                  structure will be written.
555  *
556  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
557  * @retval CPA_STATUS_FAIL           Function failed.
558  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
559  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
560  *
561  * @pre
562  *      The client has retrieved an instanceHandle from successive calls to
563  *      @ref cpaCyGetNumInstances and @ref cpaCyGetInstances.
564  * @post
565  *      None
566  * @note
567  *      None
568  * @see
569  *      cpaCyGetNumInstances,
570  *      cpaCyGetInstances,
571  *      CpaInstanceInfo
572  *
573  *****************************************************************************/
574 CpaStatus
575 cpaCyInstanceGetInfo2(const CpaInstanceHandle instanceHandle,
576         CpaInstanceInfo2 * pInstanceInfo2);
577 
578 /*****************************************************************************/
579 /* Instance Notification Functions                                           */
580 /*****************************************************************************/
581 /**
582  *****************************************************************************
583  * @ingroup cpaCyCommon
584  *      Callback function for instance notification support.
585  *
586  * @description
587  *      This is the prototype for the instance notification callback function.
588  *      The callback function is passed in as a parameter to the
589  *      @ref cpaCyInstanceSetNotificationCb function.
590  *
591  * @context
592  *      This function will be executed in a context that requires that sleeping
593  *      MUST NOT be permitted.
594  * @assumptions
595  *      None
596  * @sideEffects
597  *      None
598  * @blocking
599  *      No
600  * @reentrant
601  *      No
602  * @threadSafe
603  *      Yes
604  *
605  * @param[in] instanceHandle   Instance handle.
606  * @param[in] pCallbackTag     Opaque value provided by user while making
607  *                             individual function calls.
608  * @param[in] instanceEvent    The event that will trigger this function to
609  *                             get invoked.
610  *
611  * @retval
612  *      None
613  * @pre
614  *      Component has been initialized and the notification function has been
615  *  set via the cpaCyInstanceSetNotificationCb function.
616  * @post
617  *      None
618  * @note
619  *      None
620  * @see
621  *      cpaCyInstanceSetNotificationCb(),
622  *
623  *****************************************************************************/
624 typedef void (*CpaCyInstanceNotificationCbFunc)(
625         const CpaInstanceHandle instanceHandle,
626         void * pCallbackTag,
627         const CpaInstanceEvent instanceEvent);
628 
629 /**
630  *****************************************************************************
631  * @ingroup cpaCyCommon
632  *      Subscribe for instance notifications.
633  *
634  * @description
635  *      Clients of the CpaCy interface can subscribe for instance notifications
636  *      by registering a @ref CpaCyInstanceNotificationCbFunc function.
637  *
638  * @context
639  *      This function may be called from any context.
640  * @assumptions
641  *      None
642  * @sideEffects
643  *      None
644  * @blocking
645  *      No
646  * @reentrant
647  *      No
648  * @threadSafe
649  *      Yes
650  *
651  * @param[in] instanceHandle           Instance handle.
652  * @param[in] pInstanceNotificationCb  Instance notification callback
653  *                                     function pointer.
654  * @param[in] pCallbackTag             Opaque value provided by user while
655  *                                     making individual function calls.
656  *
657  * @retval CPA_STATUS_SUCCESS          Function executed successfully.
658  * @retval CPA_STATUS_FAIL             Function failed.
659  * @retval CPA_STATUS_INVALID_PARAM    Invalid parameter passed in.
660  * @retval CPA_STATUS_UNSUPPORTED      Function is not supported.
661  *
662  * @pre
663  *      Instance has been initialized.
664  * @post
665  *      None
666  * @note
667  *      None
668  * @see
669  *      CpaCyInstanceNotificationCbFunc
670  *
671  *****************************************************************************/
672 CpaStatus
673 cpaCyInstanceSetNotificationCb(
674         const CpaInstanceHandle instanceHandle,
675         const CpaCyInstanceNotificationCbFunc pInstanceNotificationCb,
676         void *pCallbackTag);
677 
678 #ifdef __cplusplus
679 } /* close the extern "C" { */
680 #endif
681 
682 #endif /* CPA_CY_COMMON_H */
683