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_sym_dp.h 45 * 46 * @defgroup cpaCySymDp Symmetric cryptographic Data Plane API 47 * 48 * @ingroup cpaCySym 49 * 50 * @description 51 * These data structures and functions specify the Data Plane API 52 * for symmetric cipher, hash, and combined cipher and hash 53 * operations. 54 * 55 * This API is recommended for data plane applications, in which the 56 * cost of offload - that is, the cycles consumed by the driver in 57 * sending requests to the hardware, and processing responses - needs 58 * to be minimized. In particular, use of this API is recommended 59 * if the following constraints are acceptable to your application: 60 * 61 * - Thread safety is not guaranteed. Each software thread should 62 * have access to its own unique instance (CpaInstanceHandle) to 63 * avoid contention. 64 * - Polling is used, rather than interrupts (which are expensive). 65 * Implementations of this API will provide a function (not 66 * defined as part of this API) to read responses from the hardware 67 * response queue and dispatch callback functions, as specified on 68 * this API. 69 * - Buffers and buffer lists are passed using physical addresses, 70 * to avoid virtual to physical address translation costs. 71 * - For GCM and CCM modes of AES, when performing decryption and 72 * verification, if verification fails, then the message buffer 73 * will NOT be zeroed. (This is a consequence of using physical 74 * addresses for the buffers.) 75 * - The ability to enqueue one or more requests without submitting 76 * them to the hardware allows for certain costs to be amortized 77 * across multiple requests. 78 * - Only asynchronous invocation is supported. 79 * - There is no support for partial packets. 80 * - Implementations may provide certain features as optional at 81 * build time, such as atomic counters. 82 * - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not 83 * supported on this API. The specific handle should be obtained 84 * using the instance discovery functions (@ref cpaCyGetNumInstances, 85 * @ref cpaCyGetInstances). 86 * 87 * @note Performance Trade-Offs 88 * Different implementations of this API may have different performance 89 * trade-offs; please refer to the documentation for your implementation 90 * for details. However, the following concepts informed the definition 91 * of this API. 92 * 93 * The API distinguishes between <i>enqueuing</i> a request and actually 94 * <i>submitting</i> that request to the cryptographic acceleration 95 * engine to be performed. This allows multiple requests to be enqueued 96 * (either individually or in batch), and then for all enqueued requests 97 * to be submitted in a single operation. The rationale is that in some 98 * (especially hardware-based) implementations, the submit operation 99 * is expensive; for example, it may incur an MMIO instruction. The 100 * API allows this cost to be amortized over a number of requests. The 101 * precise number of such requests can be tuned for optimal 102 * performance. 103 * 104 * Specifically: 105 * 106 * - The function @ref cpaCySymDpEnqueueOp allows one request to be 107 * enqueued, and optionally for that request (and all previously 108 * enqueued requests) to be submitted. 109 * - The function @ref cpaCySymDpEnqueueOpBatch allows multiple 110 * requests to be enqueued, and optionally for those requests (and all 111 * previously enqueued requests) to be submitted. 112 * - The function @ref cpaCySymDpPerformOpNow enqueues no requests, but 113 * submits all previously enqueued requests. 114 *****************************************************************************/ 115 116 #ifndef CPA_CY_SYM_DP_H 117 #define CPA_CY_SYM_DP_H 118 119 #ifdef __cplusplus 120 extern "C" { 121 #endif 122 123 #include "cpa_cy_common.h" 124 #include "cpa_cy_sym.h" 125 126 /** 127 ***************************************************************************** 128 * @ingroup cpaCySymDp 129 * Cryptographic component symmetric session context handle for the 130 * data plane API. 131 * @description 132 * Handle to a cryptographic data plane session context. The memory for 133 * this handle is allocated by the client. The size of the memory that 134 * the client needs to allocate is determined by a call to the @ref 135 * cpaCySymDpSessionCtxGetSize or @ref cpaCySymDpSessionCtxGetDynamicSize 136 * functions. The session context memory is initialized with a call to 137 * the @ref cpaCySymInitSession function. 138 * This memory MUST not be freed until a call to @ref 139 * cpaCySymDpRemoveSession has completed successfully. 140 * 141 *****************************************************************************/ 142 typedef void * CpaCySymDpSessionCtx; 143 144 /** 145 ***************************************************************************** 146 * @ingroup cpaCySymDp 147 * Operation Data for cryptographic data plane API. 148 * 149 * @description 150 * This structure contains data relating to a request to perform 151 * symmetric cryptographic processing on one or more data buffers. 152 * 153 * The physical memory to which this structure points needs to be 154 * at least 8-byte aligned. 155 * 156 * All reserved fields SHOULD NOT be written or read by the 157 * calling code. 158 * 159 * @see 160 * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch 161 ****************************************************************************/ 162 typedef struct _CpaCySymDpOpData { 163 Cpa64U reserved0; 164 /**< Reserved for internal usage. */ 165 Cpa32U cryptoStartSrcOffsetInBytes; 166 /**< Starting point for cipher processing, specified as number of bytes 167 * from start of data in the source buffer. The result of the cipher 168 * operation will be written back into the buffer starting at this 169 * location in the destination buffer. 170 */ 171 Cpa32U messageLenToCipherInBytes; 172 /**< The message length, in bytes, of the source buffer on which the 173 * cryptographic operation will be computed. This must be a multiple of 174 * the block size if a block cipher is being used. This is also the 175 * same as the result length. 176 * 177 * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value 178 * should not include the length of the padding or the length of the 179 * MAC; the driver will compute the actual number of bytes over which 180 * the encryption will occur, which will include these values. 181 * 182 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field 183 * should be set to 0. 184 * 185 * @note On some implementations, this length may be limited to a 16-bit 186 * value (65535 bytes). 187 */ 188 CpaPhysicalAddr iv; 189 /**< Initialization Vector or Counter. Specifically, this is the 190 * physical address of one of the following: 191 * 192 * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for 193 * SNOW3G in UEA2 mode, this is the Initialization Vector (IV) 194 * value. 195 * - For ARC4, this is reserved for internal usage. 196 * - For block ciphers in CTR mode, this is the counter. 197 * - For GCM mode, this is either the IV (if the length is 96 bits) or J0 198 * (for other sizes), where J0 is as defined by NIST SP800-38D. 199 * Regardless of the IV length, a full 16 bytes needs to be allocated. 200 * - For CCM mode, the first byte is reserved, and the nonce should be 201 * written starting at &pIv[1] (to allow space for the implementation 202 * to write in the flags in the first byte). Note that a full 16 bytes 203 * should be allocated, even though the ivLenInBytes field will have 204 * a value less than this. 205 * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. 206 */ 207 Cpa64U reserved1; 208 /**< Reserved for internal usage. */ 209 Cpa32U hashStartSrcOffsetInBytes; 210 /**< Starting point for hash processing, specified as number of bytes 211 * from start of packet in source buffer. 212 * 213 * @note For CCM and GCM modes of operation, this value in this field 214 * is ignored, and the field is reserved for internal usage. 215 * The fields @ref additionalAuthData and @ref pAdditionalAuthData 216 * should be set instead. 217 * 218 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 219 * operation, this field specifies the start of the AAD data in 220 * the source buffer. 221 */ 222 Cpa32U messageLenToHashInBytes; 223 /**< The message length, in bytes, of the source buffer that the hash 224 * will be computed on. 225 * 226 * @note For CCM and GCM modes of operation, this value in this field 227 * is ignored, and the field is reserved for internal usage. 228 * The fields @ref additionalAuthData and @ref pAdditionalAuthData 229 * should be set instead. 230 * 231 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 232 * operation, this field specifies the length of the AAD data in the 233 * source buffer. 234 * 235 * @note On some implementations, this length may be limited to a 16-bit 236 * value (65535 bytes). 237 */ 238 CpaPhysicalAddr additionalAuthData; 239 /**< Physical address of the Additional Authenticated Data (AAD), 240 * which is needed for authenticated cipher mechanisms (CCM and 241 * GCM), and to the IV for SNOW3G authentication (@ref 242 * CPA_CY_SYM_HASH_SNOW3G_UIA2). For other authentication 243 * mechanisms, this value is ignored, and the field is reserved for 244 * internal usage. 245 * 246 * The length of the data pointed to by this field is set up for 247 * the session in the @ref CpaCySymHashAuthModeSetupData structure 248 * as part of the @ref cpaCySymDpInitSession function call. This length 249 * must not exceed 240 bytes. 250 251 * If AAD is not used, this address must be set to zero. 252 * 253 * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM) and GCM (@ref 254 * CPA_CY_SYM_HASH_AES_GCM), the caller should be setup as described in 255 * the same way as the corresponding field, pAdditionalAuthData, on the 256 * "traditional" API (see the @ref CpaCySymOpData). 257 * 258 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 259 * operation, this field is not used and should be set to 0. Instead 260 * the AAD data should be placed in the source buffer. 261 * 262 */ 263 CpaPhysicalAddr digestResult; 264 /**< If the digestIsAppended member of the @ref CpaCySymSessionSetupData 265 * structure is NOT set then this is the physical address of the location 266 * where the digest result should be inserted (in the case of digest 267 * generation) or where the purported digest exists (in the case of digest 268 * verification). 269 * 270 * At session registration time, the client specified the digest result 271 * length with the digestResultLenInBytes member of the @ref 272 * CpaCySymHashSetupData structure. The client must allocate at least 273 * digestResultLenInBytes of physically contiguous memory at this location. 274 * 275 * For digest generation, the digest result will overwrite any data 276 * at this location. 277 * 278 * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result" 279 * read "authentication tag T". 280 * 281 * If the digestIsAppended member of the @ref CpaCySymSessionSetupData 282 * structure is set then this value is ignored and the digest result 283 * is understood to be in the destination buffer for digest generation, 284 * and in the source buffer for digest verification. The location of the 285 * digest result in this case is immediately following the region over 286 * which the digest is computed. 287 */ 288 289 CpaInstanceHandle instanceHandle; 290 /**< Instance to which the request is to be enqueued. 291 * @note A callback function must have been registered on the instance 292 * using @ref cpaCySymDpRegCbFunc. 293 */ 294 CpaCySymDpSessionCtx sessionCtx; 295 /**< Session context specifying the cryptographic parameters for this 296 * request. 297 * @note The session must have been created using @ref 298 * cpaCySymDpInitSession. 299 */ 300 Cpa32U ivLenInBytes; 301 /**< Length of valid IV data pointed to by the pIv parameter. 302 * 303 * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for 304 * SNOW3G in UEA2 mode, this is the length of the IV (which 305 * must be the same as the block length of the cipher). 306 * - For block ciphers in CTR mode, this is the length of the counter 307 * (which must be the same as the block length of the cipher). 308 * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which 309 * case pIv points to J0. 310 * - For CCM mode, this is the length of the nonce, which can be in the 311 * range 7 to 13 inclusive. 312 */ 313 CpaPhysicalAddr srcBuffer; 314 /**< Physical address of the source buffer on which to operate. 315 * This is either: 316 * 317 * - The location of the data, of length srcBufferLen; or, 318 * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 319 * srcBuffer contains the location where a @ref CpaPhysBufferList is 320 * stored. In this case, the CpaPhysBufferList MUST be aligned 321 * on an 8-byte boundary. 322 * - For optimum performance, the buffer should only contain the data 323 * region that the cryptographic operation(s) must be performed on. 324 * Any additional data in the source buffer may be copied to the 325 * destination buffer and this copy may degrade performance. 326 */ 327 Cpa32U srcBufferLen; 328 /**< Length of source buffer, or @ref CPA_DP_BUFLIST. */ 329 CpaPhysicalAddr dstBuffer; 330 /**< Physical address of the destination buffer on which to operate. 331 * This is either: 332 * 333 * - The location of the data, of length srcBufferLen; or, 334 * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 335 * srcBuffer contains the location where a @ref CpaPhysBufferList is 336 * stored. In this case, the CpaPhysBufferList MUST be aligned 337 * on an 8-byte boundary. 338 * 339 * For "in-place" operation, the dstBuffer may be identical to the 340 * srcBuffer. 341 */ 342 Cpa32U dstBufferLen; 343 /**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */ 344 345 CpaPhysicalAddr thisPhys; 346 /**< Physical address of this data structure */ 347 348 Cpa8U* pIv; 349 /**< Pointer to (and therefore, the virtual address of) the IV field 350 * above. 351 * Needed here because the driver in some cases writes to this field, 352 * in addition to sending it to the accelerator. 353 */ 354 Cpa8U *pAdditionalAuthData; 355 /**< Pointer to (and therefore, the virtual address of) the 356 * additionalAuthData field above. 357 * Needed here because the driver in some cases writes to this field, 358 * in addition to sending it to the accelerator. 359 */ 360 void* pCallbackTag; 361 /**< Opaque data that will be returned to the client in the function 362 * completion callback. 363 * 364 * This opaque data is not used by the implementation of the API, 365 * but is simply returned as part of the asynchronous response. 366 * It may be used to store information that might be useful when 367 * processing the response later. 368 */ 369 } CpaCySymDpOpData; 370 371 /** 372 ***************************************************************************** 373 * @ingroup cpaCySymDp 374 * Definition of callback function for cryptographic data plane API. 375 * 376 * @description 377 * This is the callback function prototype. The callback function is 378 * registered by the application using the @ref cpaCySymDpRegCbFunc 379 * function call, and called back on completion of asycnhronous 380 * requests made via calls to @ref cpaCySymDpEnqueueOp or @ref 381 * cpaCySymDpEnqueueOpBatch. 382 * 383 * @context 384 * This callback function can be executed in a context that DOES NOT 385 * permit sleeping to occur. 386 * @assumptions 387 * None 388 * @sideEffects 389 * None 390 * @reentrant 391 * No 392 * @threadSafe 393 * No 394 * 395 * @param[in] pOpData Pointer to the CpaCySymDpOpData object which 396 * was supplied as part of the original request. 397 * @param[in] status Status of the operation. Valid values are 398 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 399 * CPA_STATUS_UNSUPPORTED. 400 * @param[in] verifyResult This parameter is valid when the verifyDigest 401 * option is set in the CpaCySymSessionSetupData 402 * structure. A value of CPA_TRUE indicates that 403 * the compare succeeded. A value of CPA_FALSE 404 * indicates that the compare failed. 405 * 406 * @return 407 * None 408 * @pre 409 * Component has been initialized. 410 * Callback has been registered with @ref cpaCySymDpRegCbFunc. 411 * @post 412 * None 413 * @note 414 * None 415 * @see 416 * cpaCySymDpRegCbFunc 417 *****************************************************************************/ 418 typedef void (*CpaCySymDpCbFunc)(CpaCySymDpOpData *pOpData, 419 CpaStatus status, 420 CpaBoolean verifyResult); 421 422 423 /** 424 ***************************************************************************** 425 * @ingroup cpaCySymDp 426 * Registration of the operation completion callback function. 427 * 428 * @description 429 * This function allows a completion callback function to be registered. 430 * The registered callback function is invoked on completion of 431 * asycnhronous requests made via calls to @ref cpaCySymDpEnqueueOp 432 * or @ref cpaCySymDpEnqueueOpBatch. 433 * 434 * If a callback function was previously registered, it is overwritten. 435 * 436 * @context 437 * This is a synchronous function and it cannot sleep. It can be 438 * executed in a context that does not permit sleeping. 439 * @assumptions 440 * None 441 * @sideEffects 442 * None 443 * @reentrant 444 * No 445 * @threadSafe 446 * No 447 * 448 * @param[in] instanceHandle Instance on which the callback function is to be 449 * registered. 450 * @param[in] pSymNewCb Callback function for this instance. 451 452 * @retval CPA_STATUS_SUCCESS Function executed successfully. 453 * @retval CPA_STATUS_FAIL Function failed. 454 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 455 * the request. 456 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 457 * 458 * @pre 459 * Component has been initialized. 460 * @post 461 * None 462 * @note 463 * None 464 * @see 465 * CpaCySymDpCbFunc 466 *****************************************************************************/ 467 CpaStatus cpaCySymDpRegCbFunc(const CpaInstanceHandle instanceHandle, 468 const CpaCySymDpCbFunc pSymNewCb); 469 470 /** 471 ***************************************************************************** 472 * @ingroup cpaCySymDp 473 * Gets the size required to store a session context for the data plane 474 * API. 475 * 476 * @description 477 * This function is used by the client to determine the size of the memory 478 * it must allocate in order to store the session context. This MUST be 479 * called before the client allocates the memory for the session context 480 * and before the client calls the @ref cpaCySymDpInitSession function. 481 * 482 * For a given implementation of this API, it is safe to assume that 483 * cpaCySymDpSessionCtxGetSize() will always return the same size and that 484 * the size will not be different for different setup data parameters. 485 * However, it should be noted that the size may change: 486 * (1) between different implementations of the API (e.g. between software 487 * and hardware implementations or between different hardware 488 * implementations) 489 * (2) between different releases of the same API implementation. 490 * 491 * The size returned by this function is the smallest size needed to 492 * support all possible combinations of setup data parameters. Some 493 * setup data parameter combinations may fit within a smaller session 494 * context size. The alternate cpaCySymDpSessionCtxGetDynamicSize() 495 * function will return the smallest size needed to fit the 496 * provided setup data parameters. 497 * 498 * @context 499 * This is a synchronous function that cannot sleep. It can be 500 * executed in a context that does not permit sleeping. 501 * @assumptions 502 * None 503 * @sideEffects 504 * None 505 * @blocking 506 * No 507 * @reentrant 508 * No 509 * @threadSafe 510 * Yes 511 * 512 * @param[in] instanceHandle Instance handle. 513 * @param[in] pSessionSetupData Pointer to session setup data which 514 * contains parameters which are static 515 * for a given cryptographic session such 516 * as operation type, mechanisms, and keys 517 * for cipher and/or hash operations. 518 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 519 * to hold the Session Context. 520 * 521 * @retval CPA_STATUS_SUCCESS Function executed successfully. 522 * @retval CPA_STATUS_FAIL Function failed. 523 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 524 * @retval CPA_STATUS_RESOURCE Error related to system resources. 525 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 526 * 527 * @pre 528 * The component has been initialized. 529 * @post 530 * None 531 * @note 532 * This is a synchronous function and has no completion callback 533 * associated with it. 534 * @see 535 * CpaCySymSessionSetupData 536 * cpaCySymDpSessionCtxGetDynamicSize() 537 * cpaCySymDpInitSession() 538 *****************************************************************************/ 539 CpaStatus 540 cpaCySymDpSessionCtxGetSize(const CpaInstanceHandle instanceHandle, 541 const CpaCySymSessionSetupData *pSessionSetupData, 542 Cpa32U *pSessionCtxSizeInBytes); 543 544 /** 545 ***************************************************************************** 546 * @ingroup cpaCySymDp 547 * Gets the minimum size required to store a session context for the data 548 * plane API. 549 * 550 * @description 551 * This function is used by the client to determine the smallest size of 552 * the memory it must allocate in order to store the session context. 553 * This MUST be called before the client allocates the memory for the 554 * session context and before the client calls the 555 * @ref cpaCySymDpInitSession function. 556 * 557 * This function is an alternate to cpaCySymDpSessionGetSize(). 558 * cpaCySymDpSessionCtxGetSize() will return a fixed size which is the 559 * minimum memory size needed to support all possible setup data parameter 560 * combinations. cpaCySymDpSessionCtxGetDynamicSize() will return the 561 * minimum memory size needed to support the specific session setup 562 * data parameters provided. This size may be different for different setup 563 * data parameters. 564 * 565 * @context 566 * This is a synchronous function that cannot sleep. It can be 567 * executed in a context that does not permit sleeping. 568 * @assumptions 569 * None 570 * @sideEffects 571 * None 572 * @blocking 573 * No 574 * @reentrant 575 * No 576 * @threadSafe 577 * Yes 578 * 579 * @param[in] instanceHandle Instance handle. 580 * @param[in] pSessionSetupData Pointer to session setup data which 581 * contains parameters which are static 582 * for a given cryptographic session such 583 * as operation type, mechanisms, and keys 584 * for cipher and/or hash operations. 585 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 586 * to hold the Session Context. 587 * 588 * @retval CPA_STATUS_SUCCESS Function executed successfully. 589 * @retval CPA_STATUS_FAIL Function failed. 590 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 591 * @retval CPA_STATUS_RESOURCE Error related to system resources. 592 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 593 * 594 * @pre 595 * The component has been initialized. 596 * @post 597 * None 598 * @note 599 * This is a synchronous function and has no completion callback 600 * associated with it. 601 * @see 602 * CpaCySymSessionSetupData 603 * cpaCySymDpSessionCtxGetSize() 604 * cpaCySymDpInitSession() 605 *****************************************************************************/ 606 CpaStatus 607 cpaCySymDpSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle, 608 const CpaCySymSessionSetupData *pSessionSetupData, 609 Cpa32U *pSessionCtxSizeInBytes); 610 611 /** 612 ***************************************************************************** 613 * @ingroup cpaCySymDp 614 * Initialize a session for the symmetric cryptographic data plane API. 615 * 616 * @description 617 * This function is used by the client to initialize an asynchronous 618 * session context for symmetric cryptographic data plane operations. 619 * The returned session context is the handle to the session and needs to 620 * be passed when requesting cryptographic operations to be performed. 621 * 622 * Only sessions created using this function may be used when 623 * invoking functions on this API 624 * 625 * The session can be removed using @ref cpaCySymDpRemoveSession. 626 * 627 * @context 628 * This is a synchronous function and it cannot sleep. It can be 629 * executed in a context that does not permit sleeping. 630 * @assumptions 631 * None 632 * @sideEffects 633 * None 634 * @blocking 635 * No 636 * @reentrant 637 * No 638 * @threadSafe 639 * No 640 * 641 * @param[in] instanceHandle Instance to which the requests will be 642 * submitted. 643 * @param[in] pSessionSetupData Pointer to session setup data which 644 * contains parameters that are static 645 * for a given cryptographic session such 646 * as operation type, algorithm, and keys 647 * for cipher and/or hash operations. 648 * @param[out] sessionCtx Pointer to the memory allocated by the 649 * client to store the session context. This 650 * memory must be physically contiguous, and 651 * its length (in bytes) must be at least as 652 * big as specified by a call to @ref 653 * cpaCySymDpSessionCtxGetSize. This memory 654 * will be initialized with this function. This 655 * value needs to be passed to subsequent 656 * processing calls. 657 * 658 * @retval CPA_STATUS_SUCCESS Function executed successfully. 659 * @retval CPA_STATUS_FAIL Function failed. 660 * @retval CPA_STATUS_RETRY Resubmit the request. 661 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 662 * @retval CPA_STATUS_RESOURCE Error related to system resources. 663 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 664 * the request. 665 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 666 * 667 * @pre 668 * The component has been initialized. 669 * @post 670 * None 671 * @note 672 * This is a synchronous function and has no completion callback 673 * associated with it. 674 * @see 675 * cpaCySymDpSessionCtxGetSize, cpaCySymDpRemoveSession 676 *****************************************************************************/ 677 CpaStatus 678 cpaCySymDpInitSession(CpaInstanceHandle instanceHandle, 679 const CpaCySymSessionSetupData *pSessionSetupData, 680 CpaCySymDpSessionCtx sessionCtx); 681 682 /** 683 ***************************************************************************** 684 * @ingroup cpaCySymDp 685 * Remove (delete) a symmetric cryptographic session for the data plane 686 * API. 687 * 688 * @description 689 * This function will remove a previously initialized session context 690 * and the installed callback handler function. Removal will fail if 691 * outstanding calls still exist for the initialized session handle. 692 * The client needs to retry the remove function at a later time. 693 * The memory for the session context MUST not be freed until this call 694 * has completed successfully. 695 * 696 * @context 697 * This is a synchronous function that cannot sleep. It can be 698 * executed in a context that does not permit sleeping. 699 * @assumptions 700 * None 701 * @sideEffects 702 * None 703 * @blocking 704 * No 705 * @reentrant 706 * No 707 * @threadSafe 708 * No 709 * 710 * @param[in] instanceHandle Instance handle. 711 * @param[in,out] sessionCtx Session context to be removed. 712 * 713 * @retval CPA_STATUS_SUCCESS Function executed successfully. 714 * @retval CPA_STATUS_FAIL Function failed. 715 * @retval CPA_STATUS_RETRY Resubmit the request. 716 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 717 * @retval CPA_STATUS_RESOURCE Error related to system resources. 718 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 719 * the request. 720 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 721 * 722 * @pre 723 * The component has been initialized. 724 * @post 725 * None 726 * @note 727 * Note that this is a synchronous function and has no completion callback 728 * associated with it. 729 * 730 * @see 731 * CpaCySymDpSessionCtx, 732 * cpaCySymDpInitSession() 733 * 734 *****************************************************************************/ 735 CpaStatus 736 cpaCySymDpRemoveSession(const CpaInstanceHandle instanceHandle, 737 CpaCySymDpSessionCtx sessionCtx); 738 739 740 /** 741 ***************************************************************************** 742 * @ingroup cpaCySymDp 743 * Enqueue a single symmetric cryptographic request. 744 * 745 * @description 746 * This function enqueues a single request to perform a cipher, 747 * hash or combined (cipher and hash) operation. Optionally, the 748 * request is also submitted to the cryptographic engine to be 749 * performed. 750 * 751 * See note about performance trade-offs on the @ref cpaCySymDp API. 752 * 753 * The function is asynchronous; control is returned to the user once 754 * the request has been submitted. On completion of the request, the 755 * application may poll for responses, which will cause a callback 756 * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. 757 * Callbacks within a session are guaranteed to be in the same order 758 * in which they were submitted. 759 * 760 * The following restrictions apply to the pOpData parameter: 761 * 762 * - The memory MUST be aligned on an 8-byte boundary. 763 * - The structure MUST reside in physically contiguous memory. 764 * - The reserved fields of the structure SHOULD NOT be written 765 * or read by the calling code. 766 * 767 * @context 768 * This function will not sleep, and hence can be executed in a context 769 * that does not permit sleeping. 770 * 771 * @sideEffects 772 * None 773 * @blocking 774 * No 775 * @reentrant 776 * No 777 * @threadSafe 778 * No 779 * 780 * @param[in] pOpData Pointer to a structure containing the 781 * request parameters. The client code allocates 782 * the memory for this structure. This component 783 * takes ownership of the memory until it is 784 * returned in the callback, which was registered 785 * on the instance via @ref cpaCySymDpRegCbFunc. 786 * See the above Description for restrictions 787 * that apply to this parameter. 788 * @param[in] performOpNow Flag to specify whether the operation should be 789 * performed immediately (CPA_TRUE), or simply 790 * enqueued to be performed later (CPA_FALSE). 791 * In the latter case, the request is submitted 792 * to be performed either by calling this function 793 * again with this flag set to CPA_TRUE, or by 794 * invoking the function @ref 795 * cpaCySymDpPerformOpNow. 796 * 797 * @retval CPA_STATUS_SUCCESS Function executed successfully. 798 * @retval CPA_STATUS_FAIL Function failed. 799 * @retval CPA_STATUS_RETRY Resubmit the request. 800 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 801 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 802 * the request. 803 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 804 * 805 * @pre 806 * The session identified by pOpData->sessionCtx was setup using 807 * @ref cpaCySymDpInitSession. 808 * The instance identified by pOpData->instanceHandle has had a 809 * callback function registered via @ref cpaCySymDpRegCbFunc. 810 * 811 * @post 812 * None 813 * 814 * @note 815 * A callback of type @ref CpaCySymDpCbFunc is generated in response to 816 * this function call. Any errors generated during processing are 817 * reported as part of the callback status code. 818 * 819 * @see 820 * cpaCySymDpInitSession, 821 * cpaCySymDpPerformOpNow 822 *****************************************************************************/ 823 CpaStatus 824 cpaCySymDpEnqueueOp(CpaCySymDpOpData *pOpData, 825 const CpaBoolean performOpNow); 826 827 828 /** 829 ***************************************************************************** 830 * @ingroup cpaCySymDp 831 * Enqueue multiple requests to the symmetric cryptographic data plane 832 * API. 833 * 834 * @description 835 * This function enqueues multiple requests to perform cipher, hash 836 * or combined (cipher and hash) operations. 837 838 * See note about performance trade-offs on the @ref cpaCySymDp API. 839 * 840 * The function is asynchronous; control is returned to the user once 841 * the request has been submitted. On completion of the request, the 842 * application may poll for responses, which will cause a callback 843 * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. 844 * Separate callbacks will be invoked for each request. 845 * Callbacks within a session are guaranteed to be in the same order 846 * in which they were submitted. 847 * 848 * The following restrictions apply to each element of the pOpData 849 * array: 850 * 851 * - The memory MUST be aligned on an 8-byte boundary. 852 * - The structure MUST reside in physically contiguous memory. 853 * - The reserved fields of the structure SHOULD NOT be 854 * written or read by the calling code. 855 * 856 * @context 857 * This function will not sleep, and hence can be executed in a context 858 * that does not permit sleeping. 859 * 860 * @assumptions 861 * Client MUST allocate the request parameters to 8 byte alignment. 862 * Reserved elements of the CpaCySymDpOpData structure MUST be 0. 863 * The CpaCySymDpOpData structure MUST reside in physically 864 * contiguous memory. 865 * 866 * @sideEffects 867 * None 868 * @blocking 869 * No 870 * @reentrant 871 * No 872 * @threadSafe 873 * No 874 * 875 * @param[in] numberRequests The number of requests in the array of 876 * CpaCySymDpOpData structures. 877 * @param[in] pOpData An array of pointers to CpaCySymDpOpData 878 * structures. Each of the CpaCySymDpOpData 879 * structure contains the request parameters for 880 * that request. The client code allocates the 881 * memory for this structure. This component takes 882 * ownership of the memory until it is returned in 883 * the callback, which was registered on the 884 * instance via @ref cpaCySymDpRegCbFunc. 885 * See the above Description for restrictions 886 * that apply to this parameter. 887 * @param[in] performOpNow Flag to specify whether the operation should be 888 * performed immediately (CPA_TRUE), or simply 889 * enqueued to be performed later (CPA_FALSE). 890 * In the latter case, the request is submitted 891 * to be performed either by calling this function 892 * again with this flag set to CPA_TRUE, or by 893 * invoking the function @ref 894 * cpaCySymDpPerformOpNow. 895 * 896 * @retval CPA_STATUS_SUCCESS Function executed successfully. 897 * @retval CPA_STATUS_FAIL Function failed. 898 * @retval CPA_STATUS_RETRY Resubmit the request. 899 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 900 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 901 * the request. 902 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 903 * 904 * @pre 905 * The session identified by pOpData[i]->sessionCtx was setup using 906 * @ref cpaCySymDpInitSession. 907 * The instance identified by pOpData->instanceHandle[i] has had a 908 * callback function registered via @ref cpaCySymDpRegCbFunc. 909 * 910 * @post 911 * None 912 * 913 * @note 914 * Multiple callbacks of type @ref CpaCySymDpCbFunc are generated in 915 * response to this function call (one per request). Any errors 916 * generated during processing are reported as part of the callback 917 * status code. 918 * 919 * @see 920 * cpaCySymDpInitSession, 921 * cpaCySymDpEnqueueOp 922 *****************************************************************************/ 923 CpaStatus 924 cpaCySymDpEnqueueOpBatch(const Cpa32U numberRequests, 925 CpaCySymDpOpData *pOpData[], 926 const CpaBoolean performOpNow); 927 928 929 /** 930 ***************************************************************************** 931 * @ingroup cpaCySymDp 932 * Submit any previously enqueued requests to be performed now on the 933 * symmetric cryptographic data plane API. 934 * 935 * @description 936 * If any requests/operations were enqueued via calls to @ref 937 * cpaCySymDpEnqueueOp and/or @ref cpaCySymDpEnqueueOpBatch, but with 938 * the flag performOpNow set to @ref CPA_FALSE, then these operations 939 * will now be submitted to the accelerator to be performed. 940 * 941 * See note about performance trade-offs on the @ref cpaCySymDp API. 942 * 943 * @context 944 * Will not sleep. It can be executed in a context that does not 945 * permit sleeping. 946 * 947 * @sideEffects 948 * None 949 * @blocking 950 * No 951 * @reentrant 952 * No 953 * @threadSafe 954 * No 955 * 956 * @param[in] instanceHandle Instance to which the requests will be 957 * submitted. 958 * 959 * @retval CPA_STATUS_SUCCESS Function executed successfully. 960 * @retval CPA_STATUS_FAIL Function failed. 961 * @retval CPA_STATUS_RETRY Resubmit the request. 962 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 963 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 964 * the request. 965 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 966 * 967 * @pre 968 * The component has been initialized. 969 * A cryptographic session has been previously setup using the 970 * @ref cpaCySymDpInitSession function call. 971 * 972 * @post 973 * None 974 * 975 * @see 976 * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch 977 *****************************************************************************/ 978 CpaStatus 979 cpaCySymDpPerformOpNow(CpaInstanceHandle instanceHandle); 980 981 982 #ifdef __cplusplus 983 } /* close the extern "C" { */ 984 #endif 985 986 #endif /* CPA_CY_SYM_DP_H */ 987