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
72extern "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 *****************************************************************************/
147typedef 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 *****************************************************************************/
198typedef 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 *****************************************************************************/
247typedef 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 *****************************************************************************/
301CpaStatus
302cpaCyBufferListGetMetaSize(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 *****************************************************************************/
358CpaStatus
359cpaCyGetStatusText(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 *****************************************************************************/
412CpaStatus
413cpaCyGetNumInstances(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 *****************************************************************************/
469CpaStatus
470cpaCyGetInstances(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 *****************************************************************************/
523CpaStatus CPA_DEPRECATED
524cpaCyInstanceGetInfo(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 *****************************************************************************/
574CpaStatus
575cpaCyInstanceGetInfo2(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 *****************************************************************************/
624typedef 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 *****************************************************************************/
672CpaStatus
673cpaCyInstanceSetNotificationCb(
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