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