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.h 45 * 46 * @defgroup cpaCySym Symmetric Cipher and Hash Cryptographic API 47 * 48 * @ingroup cpaCy 49 * 50 * @description 51 * These functions specify the Cryptographic API for symmetric cipher, 52 * hash, and combined cipher and hash operations. 53 * 54 *****************************************************************************/ 55 56 #ifndef CPA_CY_SYM_H 57 #define CPA_CY_SYM_H 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 #include "cpa_cy_common.h" 64 65 /** 66 ***************************************************************************** 67 * @ingroup cpaCySym 68 * Cryptographic component symmetric session context handle. 69 * @description 70 * Handle to a cryptographic session context. The memory for this handle 71 * is allocated by the client. The size of the memory that the client needs 72 * to allocate is determined by a call to the @ref 73 * cpaCySymSessionCtxGetSize or @ref cpaCySymSessionCtxGetDynamicSize 74 * functions. The session context memory is initialized with a call to 75 * the @ref cpaCySymInitSession function. 76 * This memory MUST not be freed until a call to @ref 77 * cpaCySymRemoveSession has completed successfully. 78 * 79 *****************************************************************************/ 80 typedef void * CpaCySymSessionCtx; 81 82 /** 83 ***************************************************************************** 84 * @ingroup cpaCySym 85 * Packet type for the cpaCySymPerformOp function 86 * 87 * @description 88 * Enumeration which is used to indicate to the symmetric cryptographic 89 * perform function on which type of packet the operation is required to 90 * be invoked. Multi-part cipher and hash operations are useful when 91 * processing needs to be performed on a message which is available to 92 * the client in multiple parts (for example due to network fragmentation 93 * of the packet). 94 * 95 * @note 96 * There are some restrictions regarding the operations on which 97 * partial packet processing is supported. For details, see the 98 * function @ref cpaCySymPerformOp. 99 * 100 * @see 101 * cpaCySymPerformOp() 102 * 103 *****************************************************************************/ 104 typedef enum _CpaCySymPacketType 105 { 106 CPA_CY_SYM_PACKET_TYPE_FULL = 1, 107 /**< Perform an operation on a full packet*/ 108 CPA_CY_SYM_PACKET_TYPE_PARTIAL, 109 /**< Perform a partial operation and maintain the state of the partial 110 * operation within the session. This is used for either the first or 111 * subsequent packets within a partial packet flow. */ 112 CPA_CY_SYM_PACKET_TYPE_LAST_PARTIAL 113 /**< Complete the last part of a multi-part operation */ 114 } CpaCySymPacketType; 115 116 /** 117 ***************************************************************************** 118 * @ingroup cpaCySym 119 * Types of operations supported by the cpaCySymPerformOp function. 120 * @description 121 * This enumeration lists different types of operations supported by the 122 * cpaCySymPerformOp function. The operation type is defined during 123 * session registration and cannot be changed for a session once it has 124 * been setup. 125 * @see 126 * cpaCySymPerformOp 127 *****************************************************************************/ 128 typedef enum _CpaCySymOp 129 { 130 CPA_CY_SYM_OP_NONE=0, 131 /**< No operation */ 132 CPA_CY_SYM_OP_CIPHER, 133 /**< Cipher only operation on the data */ 134 CPA_CY_SYM_OP_HASH, 135 /**< Hash only operation on the data */ 136 CPA_CY_SYM_OP_ALGORITHM_CHAINING 137 /**< Chain any cipher with any hash operation. The order depends on 138 * the value in the CpaCySymAlgChainOrder enum. 139 * 140 * This value is also used for authenticated ciphers (GCM and CCM), in 141 * which case the cipherAlgorithm should take one of the values @ref 142 * CPA_CY_SYM_CIPHER_AES_CCM or @ref CPA_CY_SYM_CIPHER_AES_GCM, while the 143 * hashAlgorithm should take the corresponding value @ref 144 * CPA_CY_SYM_HASH_AES_CCM or @ref CPA_CY_SYM_HASH_AES_GCM. 145 */ 146 } CpaCySymOp; 147 148 /** 149 ***************************************************************************** 150 * @ingroup cpaCySym 151 * Cipher algorithms. 152 * @description 153 * This enumeration lists supported cipher algorithms and modes. 154 * 155 *****************************************************************************/ 156 typedef enum _CpaCySymCipherAlgorithm 157 { 158 CPA_CY_SYM_CIPHER_NULL = 1, 159 /**< NULL cipher algorithm. No mode applies to the NULL algorithm. */ 160 CPA_CY_SYM_CIPHER_ARC4, 161 /**< (A)RC4 cipher algorithm */ 162 CPA_CY_SYM_CIPHER_AES_ECB, 163 /**< AES algorithm in ECB mode */ 164 CPA_CY_SYM_CIPHER_AES_CBC, 165 /**< AES algorithm in CBC mode */ 166 CPA_CY_SYM_CIPHER_AES_CTR, 167 /**< AES algorithm in Counter mode */ 168 CPA_CY_SYM_CIPHER_AES_CCM, 169 /**< AES algorithm in CCM mode. This authenticated cipher is only supported 170 * when the hash mode is also set to CPA_CY_SYM_HASH_MODE_AUTH. When this 171 * cipher algorithm is used the CPA_CY_SYM_HASH_AES_CCM element of the 172 * CpaCySymHashAlgorithm enum MUST be used to set up the related 173 * CpaCySymHashSetupData structure in the session context. */ 174 CPA_CY_SYM_CIPHER_AES_GCM, 175 /**< AES algorithm in GCM mode. This authenticated cipher is only supported 176 * when the hash mode is also set to CPA_CY_SYM_HASH_MODE_AUTH. When this 177 * cipher algorithm is used the CPA_CY_SYM_HASH_AES_GCM element of the 178 * CpaCySymHashAlgorithm enum MUST be used to set up the related 179 * CpaCySymHashSetupData structure in the session context. */ 180 CPA_CY_SYM_CIPHER_DES_ECB, 181 /**< DES algorithm in ECB mode */ 182 CPA_CY_SYM_CIPHER_DES_CBC, 183 /**< DES algorithm in CBC mode */ 184 CPA_CY_SYM_CIPHER_3DES_ECB, 185 /**< Triple DES algorithm in ECB mode */ 186 CPA_CY_SYM_CIPHER_3DES_CBC, 187 /**< Triple DES algorithm in CBC mode */ 188 CPA_CY_SYM_CIPHER_3DES_CTR, 189 /**< Triple DES algorithm in CTR mode */ 190 CPA_CY_SYM_CIPHER_KASUMI_F8, 191 /**< Kasumi algorithm in F8 mode */ 192 CPA_CY_SYM_CIPHER_SNOW3G_UEA2, 193 /**< SNOW3G algorithm in UEA2 mode */ 194 CPA_CY_SYM_CIPHER_AES_F8, 195 /**< AES algorithm in F8 mode */ 196 CPA_CY_SYM_CIPHER_AES_XTS, 197 /**< AES algorithm in XTS mode */ 198 CPA_CY_SYM_CIPHER_ZUC_EEA3, 199 /**< ZUC algorithm in EEA3 mode */ 200 CPA_CY_SYM_CIPHER_CHACHA, 201 /**< ChaCha20 Cipher Algorithm. This cipher is only supported for 202 * algorithm chaining. When selected, the hash algorithm must be set to 203 * CPA_CY_SYM_HASH_POLY and the hash mode must be set to 204 * CPA_CY_SYM_HASH_MODE_AUTH. */ 205 CPA_CY_SYM_CIPHER_SM4_ECB, 206 /**< SM4 algorithm in ECB mode This cipher supports 128 bit keys only and 207 * does not support partial processing. */ 208 CPA_CY_SYM_CIPHER_SM4_CBC, 209 /**< SM4 algorithm in CBC mode This cipher supports 128 bit keys only and 210 * does not support partial processing. */ 211 CPA_CY_SYM_CIPHER_SM4_CTR 212 /**< SM4 algorithm in CTR mode This cipher supports 128 bit keys only and 213 * does not support partial processing. */ 214 } CpaCySymCipherAlgorithm; 215 216 /** 217 * @ingroup cpaCySym 218 * Size of bitmap needed for cipher "capabilities" type. 219 * 220 * @description 221 * Defines the number of bits in the bitmap to represent supported 222 * ciphers in the type @ref CpaCySymCapabilitiesInfo. Should be set to 223 * at least one greater than the largest value in the enumerated type 224 * @ref CpaCySymHashAlgorithm, so that the value of the enum constant 225 * can also be used as the bit position in the bitmap. 226 * 227 * A larger value was chosen to allow for extensibility without the need 228 * to change the size of the bitmap (to ease backwards compatibility in 229 * future versions of the API). 230 */ 231 #define CPA_CY_SYM_CIPHER_CAP_BITMAP_SIZE (32) 232 233 234 /** 235 ***************************************************************************** 236 * @ingroup cpaCySym 237 * Symmetric Cipher Direction 238 * @description 239 * This enum indicates the cipher direction (encryption or decryption). 240 * 241 *****************************************************************************/ 242 typedef enum _CpaCySymCipherDirection 243 { 244 CPA_CY_SYM_CIPHER_DIRECTION_ENCRYPT = 1, 245 /**< Encrypt Data */ 246 CPA_CY_SYM_CIPHER_DIRECTION_DECRYPT 247 /**< Decrypt Data */ 248 } CpaCySymCipherDirection; 249 250 /** 251 ***************************************************************************** 252 * @ingroup cpaCySym 253 * Symmetric Cipher Setup Data. 254 * @description 255 * This structure contains data relating to Cipher (Encryption and 256 * Decryption) to set up a session. 257 * 258 *****************************************************************************/ 259 typedef struct _CpaCySymCipherSetupData { 260 CpaCySymCipherAlgorithm cipherAlgorithm; 261 /**< Cipher algorithm and mode */ 262 Cpa32U cipherKeyLenInBytes; 263 /**< Cipher key length in bytes. For AES it can be 128 bits (16 bytes), 264 * 192 bits (24 bytes) or 256 bits (32 bytes). 265 * For the CCM mode of operation, the only supported key length is 128 bits 266 * (16 bytes). 267 * For the CPA_CY_SYM_CIPHER_AES_F8 mode of operation, cipherKeyLenInBytes 268 * should be set to the combined length of the encryption key and the 269 * keymask. Since the keymask and the encryption key are the same size, 270 * cipherKeyLenInBytes should be set to 2 x the AES encryption key length. 271 * For the AES-XTS mode of operation: 272 * - Two keys must be provided and cipherKeyLenInBytes refers to total 273 * length of the two keys. 274 * - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes). 275 * - Both keys must have the same size. */ 276 Cpa8U *pCipherKey; 277 /**< Cipher key 278 * For the CPA_CY_SYM_CIPHER_AES_F8 mode of operation, pCipherKey will 279 * point to a concatenation of the AES encryption key followed by a 280 * keymask. As per RFC3711, the keymask should be padded with trailing 281 * bytes to match the length of the encryption key used. 282 * For AES-XTS mode of operation, two keys must be provided and pCipherKey 283 * must point to the two keys concatenated together (Key1 || Key2). 284 * cipherKeyLenInBytes will contain the total size of both keys. */ 285 CpaCySymCipherDirection cipherDirection; 286 /**< This parameter determines if the cipher operation is an encrypt or 287 * a decrypt operation. 288 * For the RC4 algorithm and the F8/CTR modes, only encrypt operations 289 * are valid. */ 290 } CpaCySymCipherSetupData; 291 292 /** 293 ***************************************************************************** 294 * @ingroup cpaCySym 295 * Symmetric Hash mode 296 * @description 297 * This enum indicates the Hash Mode. 298 * 299 *****************************************************************************/ 300 typedef enum _CpaCySymHashMode 301 { 302 CPA_CY_SYM_HASH_MODE_PLAIN = 1, 303 /**< Plain hash. Can be specified for MD5 and the SHA family of 304 * hash algorithms. */ 305 CPA_CY_SYM_HASH_MODE_AUTH, 306 /**< Authenticated hash. This mode may be used in conjunction with the 307 * MD5 and SHA family of algorithms to specify HMAC. It MUST also be 308 * specified with all of the remaining algorithms, all of which are in 309 * fact authentication algorithms. 310 */ 311 CPA_CY_SYM_HASH_MODE_NESTED 312 /**< Nested hash. Can be specified for MD5 and the SHA family of 313 * hash algorithms. */ 314 } CpaCySymHashMode; 315 316 /** 317 ***************************************************************************** 318 * @ingroup cpaCySym 319 * Hash algorithms. 320 * @description 321 * This enumeration lists supported hash algorithms. 322 * 323 *****************************************************************************/ 324 typedef enum _CpaCySymHashAlgorithm 325 { 326 CPA_CY_SYM_HASH_NONE = 0, 327 /**< No hash algorithm. */ 328 CPA_CY_SYM_HASH_MD5, 329 /**< MD5 algorithm. Supported in all 3 hash modes */ 330 CPA_CY_SYM_HASH_SHA1, 331 /**< 128 bit SHA algorithm. Supported in all 3 hash modes */ 332 CPA_CY_SYM_HASH_SHA224, 333 /**< 224 bit SHA algorithm. Supported in all 3 hash modes */ 334 CPA_CY_SYM_HASH_SHA256, 335 /**< 256 bit SHA algorithm. Supported in all 3 hash modes */ 336 CPA_CY_SYM_HASH_SHA384, 337 /**< 384 bit SHA algorithm. Supported in all 3 hash modes */ 338 CPA_CY_SYM_HASH_SHA512, 339 /**< 512 bit SHA algorithm. Supported in all 3 hash modes */ 340 CPA_CY_SYM_HASH_AES_XCBC, 341 /**< AES XCBC algorithm. This is only supported in the hash mode 342 * CPA_CY_SYM_HASH_MODE_AUTH. */ 343 CPA_CY_SYM_HASH_AES_CCM, 344 /**< AES algorithm in CCM mode. This authenticated cipher requires that the 345 * hash mode is set to CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm 346 * is used, the CPA_CY_SYM_CIPHER_AES_CCM element of the 347 * CpaCySymCipherAlgorithm enum MUST be used to set up the related 348 * CpaCySymCipherSetupData structure in the session context. */ 349 CPA_CY_SYM_HASH_AES_GCM, 350 /**< AES algorithm in GCM mode. This authenticated cipher requires that the 351 * hash mode is set to CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm 352 * is used, the CPA_CY_SYM_CIPHER_AES_GCM element of the 353 * CpaCySymCipherAlgorithm enum MUST be used to set up the related 354 * CpaCySymCipherSetupData structure in the session context. */ 355 CPA_CY_SYM_HASH_KASUMI_F9, 356 /**< Kasumi algorithm in F9 mode. This is only supported in the hash 357 * mode CPA_CY_SYM_HASH_MODE_AUTH. */ 358 CPA_CY_SYM_HASH_SNOW3G_UIA2, 359 /**< SNOW3G algorithm in UIA2 mode. This is only supported in the hash 360 * mode CPA_CY_SYM_HASH_MODE_AUTH. */ 361 CPA_CY_SYM_HASH_AES_CMAC, 362 /**< AES CMAC algorithm. This is only supported in the hash mode 363 * CPA_CY_SYM_HASH_MODE_AUTH. */ 364 CPA_CY_SYM_HASH_AES_GMAC, 365 /**< AES GMAC algorithm. This is only supported in the hash mode 366 * CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm 367 * is used, the CPA_CY_SYM_CIPHER_AES_GCM element of the 368 * CpaCySymCipherAlgorithm enum MUST be used to set up the related 369 * CpaCySymCipherSetupData structure in the session context. */ 370 CPA_CY_SYM_HASH_AES_CBC_MAC, 371 /**< AES-CBC-MAC algorithm. This is only supported in the hash mode 372 * CPA_CY_SYM_HASH_MODE_AUTH. Only 128-bit keys are supported. */ 373 CPA_CY_SYM_HASH_ZUC_EIA3, 374 /**< ZUC algorithm in EIA3 mode */ 375 CPA_CY_SYM_HASH_SHA3_256, 376 /**< 256 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and 377 * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash 378 * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. 379 * Partial requests are not supported, that is, only requests 380 * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ 381 CPA_CY_SYM_HASH_SHA3_224, 382 /**< 224 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and 383 * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash 384 * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. 385 */ 386 CPA_CY_SYM_HASH_SHA3_384, 387 /**< 384 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and 388 * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash 389 * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. 390 * Partial requests are not supported, that is, only requests 391 * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ 392 CPA_CY_SYM_HASH_SHA3_512, 393 /**< 512 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and 394 * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash 395 * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. 396 * Partial requests are not supported, that is, only requests 397 * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ 398 CPA_CY_SYM_HASH_SHAKE_128, 399 /**< 128 bit SHAKE algorithm. This is only supported in the hash 400 * mode CPA_CY_SYM_HASH_MODE_PLAIN. Partial requests are not 401 * supported, that is, only requests of CPA_CY_SYM_PACKET_TYPE_FULL 402 * are supported. */ 403 CPA_CY_SYM_HASH_SHAKE_256, 404 /**< 256 bit SHAKE algorithm. This is only supported in the hash 405 * mode CPA_CY_SYM_HASH_MODE_PLAIN. Partial requests are not 406 * supported, that is, only requests of CPA_CY_SYM_PACKET_TYPE_FULL 407 * are supported. */ 408 CPA_CY_SYM_HASH_POLY, 409 /**< Poly1305 hash algorithm. This is only supported in the hash mode 410 * CPA_CY_SYM_HASH_MODE_AUTH. This hash algorithm is only supported 411 * as part of an algorithm chain with AES_CY_SYM_CIPHER_CHACHA to 412 * implement the ChaCha20-Poly1305 AEAD algorithm. */ 413 CPA_CY_SYM_HASH_SM3 414 /**< SM3 hash algorithm. Supported in all 3 hash modes. */ 415 } CpaCySymHashAlgorithm; 416 417 /** 418 * @ingroup cpaCySym 419 * Size of bitmap needed for hash "capabilities" type. 420 * 421 * @description 422 * Defines the number of bits in the bitmap to represent supported 423 * hashes in the type @ref CpaCySymCapabilitiesInfo. Should be set to 424 * at least one greater than the largest value in the enumerated type 425 * @ref CpaCySymHashAlgorithm, so that the value of the enum constant 426 * can also be used as the bit position in the bitmap. 427 * 428 * A larger value was chosen to allow for extensibility without the need 429 * to change the size of the bitmap (to ease backwards compatibility in 430 * future versions of the API). 431 */ 432 #define CPA_CY_SYM_HASH_CAP_BITMAP_SIZE (32) 433 434 /** 435 ***************************************************************************** 436 * @ingroup cpaCySym 437 * Hash Mode Nested Setup Data. 438 * @description 439 * This structure contains data relating to a hash session in 440 * CPA_CY_SYM_HASH_MODE_NESTED mode. 441 * 442 *****************************************************************************/ 443 typedef struct _CpaCySymHashNestedModeSetupData { 444 Cpa8U *pInnerPrefixData; 445 /**< A pointer to a buffer holding the Inner Prefix data. For optimal 446 * performance the prefix data SHOULD be 8-byte aligned. This data is 447 * prepended to the data being hashed before the inner hash operation is 448 * performed. */ 449 Cpa32U innerPrefixLenInBytes; 450 /**< The inner prefix length in bytes. The maximum size the prefix data 451 * can be is 255 bytes. */ 452 CpaCySymHashAlgorithm outerHashAlgorithm; 453 /**< The hash algorithm used for the outer hash. Note: The inner hash 454 * algorithm is provided in the hash context. */ 455 Cpa8U *pOuterPrefixData; 456 /**< A pointer to a buffer holding the Outer Prefix data. For optimal 457 * performance the prefix data SHOULD be 8-byte aligned. This data is 458 * prepended to the output from the inner hash operation before the outer 459 * hash operation is performed.*/ 460 Cpa32U outerPrefixLenInBytes; 461 /**< The outer prefix length in bytes. The maximum size the prefix data 462 * can be is 255 bytes. */ 463 } CpaCySymHashNestedModeSetupData; 464 465 /** 466 ***************************************************************************** 467 * @ingroup cpaCySym 468 * Hash Auth Mode Setup Data. 469 * @description 470 * This structure contains data relating to a hash session in 471 * CPA_CY_SYM_HASH_MODE_AUTH mode. 472 * 473 *****************************************************************************/ 474 typedef struct _CpaCySymHashAuthModeSetupData { 475 Cpa8U *authKey; 476 /**< Authentication key pointer. 477 * For the GCM (@ref CPA_CY_SYM_HASH_AES_GCM) and CCM (@ref 478 * CPA_CY_SYM_HASH_AES_CCM) modes of operation, this field is ignored; 479 * the authentication key is the same as the cipher key (see 480 * the field pCipherKey in struct @ref CpaCySymCipherSetupData). 481 */ 482 Cpa32U authKeyLenInBytes; 483 /**< Length of the authentication key in bytes. The key length MUST be 484 * less than or equal to the block size of the algorithm. It is the client's 485 * responsibility to ensure that the key length is compliant with the 486 * standard being used (for example RFC 2104, FIPS 198a). 487 * 488 * For the GCM (@ref CPA_CY_SYM_HASH_AES_GCM) and CCM (@ref 489 * CPA_CY_SYM_HASH_AES_CCM) modes of operation, this field is ignored; 490 * the authentication key is the same as the cipher key, and so is its 491 * length (see the field cipherKeyLenInBytes in struct @ref 492 * CpaCySymCipherSetupData). 493 */ 494 Cpa32U aadLenInBytes; 495 /**< The length of the additional authenticated data (AAD) in bytes. 496 * The maximum permitted value is 240 bytes, unless otherwise 497 * specified below. 498 * 499 * This field must be specified when the hash algorithm is one of the 500 * following: 501 502 * - For SNOW3G (@ref CPA_CY_SYM_HASH_SNOW3G_UIA2), this is the 503 * length of the IV (which should be 16). 504 * - For GCM (@ref CPA_CY_SYM_HASH_AES_GCM). In this case, this is the 505 * length of the Additional Authenticated Data (called A, in NIST 506 * SP800-38D). 507 * - For CCM (@ref CPA_CY_SYM_HASH_AES_CCM). In this case, this is the 508 * length of the associated data (called A, in NIST SP800-38C). 509 * Note that this does NOT include the length of any padding, or the 510 * 18 bytes reserved at the start of the above field to store the 511 * block B0 and the encoded length. The maximum permitted value in 512 * this case is 222 bytes. 513 * 514 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of operation 515 * this field is not used and should be set to 0. Instead the length 516 * of the AAD data is specified in the messageLenToHashInBytes field of 517 * the CpaCySymOpData structure. 518 */ 519 } CpaCySymHashAuthModeSetupData; 520 521 /** 522 ***************************************************************************** 523 * @ingroup cpaCySym 524 * Hash Setup Data. 525 * @description 526 * This structure contains data relating to a hash session. The fields 527 * hashAlgorithm, hashMode and digestResultLenInBytes are common to all 528 * three hash modes and MUST be set for each mode. 529 * 530 *****************************************************************************/ 531 typedef struct _CpaCySymHashSetupData { 532 CpaCySymHashAlgorithm hashAlgorithm; 533 /**< Hash algorithm. For mode CPA_CY_SYM_MODE_HASH_NESTED, this is the 534 * inner hash algorithm. */ 535 CpaCySymHashMode hashMode; 536 /**< Mode of the hash operation. Valid options include plain, auth or 537 * nested hash mode. */ 538 Cpa32U digestResultLenInBytes; 539 /**< Length of the digest to be returned. If the verify option is set, 540 * this specifies the length of the digest to be compared for the 541 * session. 542 * 543 * For CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this is the octet length 544 * of the MAC, which can be one of 4, 6, 8, 10, 12, 14 or 16. 545 * 546 * For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), this is the length in bytes 547 * of the authentication tag. 548 * 549 * If the value is less than the maximum length allowed by the hash, 550 * the result shall be truncated. If the value is greater than the 551 * maximum length allowed by the hash, an error (@ref 552 * CPA_STATUS_INVALID_PARAM) is returned from the function @ref 553 * cpaCySymInitSession. 554 * 555 * In the case of nested hash, it is the outer hash which determines 556 * the maximum length allowed. */ 557 CpaCySymHashAuthModeSetupData authModeSetupData; 558 /**< Authentication Mode Setup Data. 559 * Only valid for mode CPA_CY_SYM_MODE_HASH_AUTH */ 560 CpaCySymHashNestedModeSetupData nestedModeSetupData; 561 /**< Nested Hash Mode Setup Data 562 * Only valid for mode CPA_CY_SYM_MODE_HASH_NESTED */ 563 } CpaCySymHashSetupData; 564 565 /** 566 ***************************************************************************** 567 * @ingroup cpaCySym 568 * Algorithm Chaining Operation Ordering 569 * @description 570 * This enum defines the ordering of operations for algorithm chaining. 571 * 572 ****************************************************************************/ 573 typedef enum _CpaCySymAlgChainOrder 574 { 575 CPA_CY_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER = 1, 576 /**< Perform the hash operation followed by the cipher operation. If it is 577 * required that the result of the hash (i.e. the digest) is going to be 578 * included in the data to be ciphered, then: 579 * 580 * <ul> 581 * <li> The digest MUST be placed in the destination buffer at the 582 * location corresponding to the end of the data region to be hashed 583 * (hashStartSrcOffsetInBytes + messageLenToHashInBytes), 584 * i.e. there must be no gaps between the start of the digest and the 585 * end of the data region to be hashed.</li> 586 * <li> The messageLenToCipherInBytes member of the CpaCySymOpData 587 * structure must be equal to the overall length of the plain text, 588 * the digest length and any (optional) trailing data that is to be 589 * included.</li> 590 * <li> The messageLenToCipherInBytes must be a multiple to the block 591 * size if a block cipher is being used.</li> 592 * </ul> 593 * 594 * The following is an example of the layout of the buffer before the 595 * operation, after the hash, and after the cipher: 596 597 @verbatim 598 599 +-------------------------+---------------+ 600 | Plaintext | Tail | 601 +-------------------------+---------------+ 602 <-messageLenToHashInBytes-> 603 604 +-------------------------+--------+------+ 605 | Plaintext | Digest | Tail | 606 +-------------------------+--------+------+ 607 <--------messageLenToCipherInBytes--------> 608 609 +-----------------------------------------+ 610 | Cipher Text | 611 +-----------------------------------------+ 612 613 @endverbatim 614 */ 615 CPA_CY_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH 616 /**< Perform the cipher operation followed by the hash operation. 617 * The hash operation will be performed on the ciphertext resulting from 618 * the cipher operation. 619 * 620 * The following is an example of the layout of the buffer before the 621 * operation, after the cipher, and after the hash: 622 623 @verbatim 624 625 +--------+---------------------------+---------------+ 626 | Head | Plaintext | Tail | 627 +--------+---------------------------+---------------+ 628 <-messageLenToCipherInBytes-> 629 630 +--------+---------------------------+---------------+ 631 | Head | Ciphertext | Tail | 632 +--------+---------------------------+---------------+ 633 <------messageLenToHashInBytes-------> 634 635 +--------+---------------------------+--------+------+ 636 | Head | Ciphertext | Digest | Tail | 637 +--------+---------------------------+--------+------+ 638 639 @endverbatim 640 * 641 */ 642 } CpaCySymAlgChainOrder; 643 644 /** 645 ***************************************************************************** 646 * @ingroup cpaCySym 647 * Session Setup Data. 648 * @description 649 * This structure contains data relating to setting up a session. The 650 * client needs to complete the information in this structure in order to 651 * setup a session. 652 * 653 ****************************************************************************/ 654 typedef struct _CpaCySymSessionSetupData { 655 CpaCyPriority sessionPriority; 656 /**< Priority of this session */ 657 CpaCySymOp symOperation; 658 /**< Operation to perfom */ 659 CpaCySymCipherSetupData cipherSetupData; 660 /**< Cipher Setup Data for the session. This member is ignored for the 661 * CPA_CY_SYM_OP_HASH operation. */ 662 CpaCySymHashSetupData hashSetupData; 663 /**< Hash Setup Data for a session. This member is ignored for the 664 * CPA_CY_SYM_OP_CIPHER operation. */ 665 CpaCySymAlgChainOrder algChainOrder; 666 /**< If this operation data structure relates to an algorithm chaining 667 * session then this parameter determines the order in which the chained 668 * operations are performed. If this structure does not relate to an 669 * algorithm chaining session then this parameter will be ignored. 670 * 671 * @note In the case of authenticated ciphers (GCM and CCM), which are 672 * also presented as "algorithm chaining", this value is also ignored. 673 * The chaining order is defined by the authenticated cipher, in those 674 * cases. */ 675 CpaBoolean digestIsAppended; 676 /**< Flag indicating whether the digest is appended immediately following 677 * the region over which the digest is computed. This is true for both 678 * IPsec packets and SSL/TLS records. 679 * 680 * If this flag is set, then the value of the pDigestResult field of 681 * the structure @ref CpaCySymOpData is ignored. 682 * 683 * @note The value of this field is ignored for the authenticated cipher 684 * AES_CCM as the digest must be appended in this case. 685 * 686 * @note Setting digestIsAppended for hash only operations when 687 * verifyDigest is also set is not supported. For hash only operations 688 * when verifyDigest is set, digestIsAppended should be set to CPA_FALSE. 689 */ 690 CpaBoolean verifyDigest; 691 /**< This flag is relevant only for operations which generate a message 692 * digest. If set to true, the computed digest will not be written back 693 * to the buffer location specified by other parameters, but instead will 694 * be verified (i.e. compared to the value passed in at that location). 695 * The number of bytes to be written or compared is indicated by the 696 * digest output length for the session. 697 * @note This option is only valid for full packets and for final 698 * partial packets when using partials without algorithm chaining. 699 * @note The value of this field is ignored for the authenticated ciphers 700 * (AES_CCM and AES_GCM). Digest verification is always done for these 701 * (when the direction is decrypt) and unless the DP API is used, 702 * the message buffer will be zeroed if verification fails. When using the 703 * DP API, it is the API clients responsibility to clear the message 704 * buffer when digest verification fails. 705 */ 706 CpaBoolean partialsNotRequired; 707 /**< This flag indicates if partial packet processing is required for this 708 * session. If set to true, partial packet processing will not be enabled 709 * for this session and any calls to cpaCySymPerformOp() with the 710 * packetType parameter set to a value other than 711 * CPA_CY_SYM_PACKET_TYPE_FULL will fail. 712 */ 713 } CpaCySymSessionSetupData ; 714 715 /** 716 ***************************************************************************** 717 * @ingroup cpaCySym 718 * Session Update Data. 719 * @description 720 * This structure contains data relating to resetting a session. 721 ****************************************************************************/ 722 typedef struct _CpaCySymSessionUpdateData { 723 Cpa32U flags; 724 /**< Flags indicating which fields to update. 725 * All bits should be set to 0 except those fields to be updated. 726 */ 727 #define CPA_CY_SYM_SESUPD_CIPHER_KEY 1 << 0 728 #define CPA_CY_SYM_SESUPD_CIPHER_DIR 1 << 1 729 #define CPA_CY_SYM_SESUPD_AUTH_KEY 1 << 2 730 Cpa8U *pCipherKey; 731 /**< Cipher key. 732 * The same restrictions apply as described in the corresponding field 733 * of the data structure @ref CpaCySymCipherSetupData. 734 */ 735 CpaCySymCipherDirection cipherDirection; 736 /**< This parameter determines if the cipher operation is an encrypt or 737 * a decrypt operation. 738 * The same restrictions apply as described in the corresponding field 739 * of the data structure @ref CpaCySymCipherSetupData. 740 */ 741 Cpa8U *authKey; 742 /**< Authentication key pointer. 743 * The same restrictions apply as described in the corresponding field 744 * of the data structure @ref CpaCySymHashAuthModeSetupData. 745 */ 746 } CpaCySymSessionUpdateData; 747 748 /** 749 ***************************************************************************** 750 * @ingroup cpaCySym 751 * Cryptographic Component Operation Data. 752 * @description 753 * This structure contains data relating to performing cryptographic 754 * processing on a data buffer. This request is used with 755 * cpaCySymPerformOp() call for performing cipher, hash, auth cipher 756 * or a combined hash and cipher operation. 757 * 758 * @see 759 * CpaCySymPacketType 760 * 761 * @note 762 * If the client modifies or frees the memory referenced in this structure 763 * after it has been submitted to the cpaCySymPerformOp function, and 764 * before it has been returned in the callback, undefined behavior will 765 * result. 766 ****************************************************************************/ 767 typedef struct _CpaCySymOpData { 768 CpaCySymSessionCtx sessionCtx; 769 /**< Handle for the initialized session context */ 770 CpaCySymPacketType packetType; 771 /**< Selects the packet type */ 772 Cpa8U *pIv; 773 /**< Initialization Vector or Counter. 774 * 775 * - For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for 776 * SNOW3G in UEA2 mode, this is the Initialization Vector (IV) 777 * value. 778 * - For block ciphers in CTR mode, this is the counter. 779 * - For GCM mode, this is either the IV (if the length is 96 bits) or J0 780 * (for other sizes), where J0 is as defined by NIST SP800-38D. 781 * Regardless of the IV length, a full 16 bytes needs to be allocated. 782 * - For CCM mode, the first byte is reserved, and the nonce should be 783 * written starting at &pIv[1] (to allow space for the implementation 784 * to write in the flags in the first byte). Note that a full 16 bytes 785 * should be allocated, even though the ivLenInBytes field will have 786 * a value less than this. 787 * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. 788 * - For AES-XTS, this is the 128bit tweak, i, from IEEE Std 1619-2007. 789 * 790 * For optimum performance, the data pointed to SHOULD be 8-byte 791 * aligned. 792 * 793 * The IV/Counter will be updated after every partial cryptographic 794 * operation. 795 */ 796 Cpa32U ivLenInBytes; 797 /**< Length of valid IV data pointed to by the pIv parameter. 798 * 799 * - For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for 800 * SNOW3G in UEA2 mode, this is the length of the IV (which 801 * must be the same as the block length of the cipher). 802 * - For block ciphers in CTR mode, this is the length of the counter 803 * (which must be the same as the block length of the cipher). 804 * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which 805 * case pIv points to J0. 806 * - For CCM mode, this is the length of the nonce, which can be in the 807 * range 7 to 13 inclusive. 808 */ 809 Cpa32U cryptoStartSrcOffsetInBytes; 810 /**< Starting point for cipher processing, specified as number of bytes 811 * from start of data in the source buffer. The result of the cipher 812 * operation will be written back into the output buffer starting 813 * at this location. 814 */ 815 Cpa32U messageLenToCipherInBytes; 816 /**< The message length, in bytes, of the source buffer on which the 817 * cryptographic operation will be computed. This must be a multiple of 818 * the block size if a block cipher is being used. This is also the same 819 * as the result length. 820 * 821 * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value 822 * should not include the length of the padding or the length of the 823 * MAC; the driver will compute the actual number of bytes over which 824 * the encryption will occur, which will include these values. 825 * 826 * @note There are limitations on this length for partial 827 * operations. Refer to the cpaCySymPerformOp function description for 828 * details. 829 * 830 * @note On some implementations, this length may be limited to a 16-bit 831 * value (65535 bytes). 832 * 833 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field 834 * should be set to 0. 835 */ 836 Cpa32U hashStartSrcOffsetInBytes; 837 /**< Starting point for hash processing, specified as number of bytes 838 * from start of packet in source buffer. 839 * 840 * @note For CCM and GCM modes of operation, this field is ignored. 841 * The field @ref pAdditionalAuthData field should be set instead. 842 * 843 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 844 * operation, this field specifies the start of the AAD data in 845 * the source buffer. 846 */ 847 Cpa32U messageLenToHashInBytes; 848 /**< The message length, in bytes, of the source buffer that the hash 849 * will be computed on. 850 * 851 * @note There are limitations on this length for partial operations. 852 * Refer to the @ref cpaCySymPerformOp function description for details. 853 * 854 * @note For CCM and GCM modes of operation, this field is ignored. 855 * The field @ref pAdditionalAuthData field should be set instead. 856 * 857 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 858 * operation, this field specifies the length of the AAD data in the 859 * source buffer. The maximum length supported for AAD data for AES-GMAC 860 * is 16383 bytes. 861 * 862 * @note On some implementations, this length may be limited to a 16-bit 863 * value (65535 bytes). 864 */ 865 Cpa8U *pDigestResult; 866 /**< If the digestIsAppended member of the @ref CpaCySymSessionSetupData 867 * structure is NOT set then this is a pointer to the location where the 868 * digest result should be inserted (in the case of digest generation) 869 * or where the purported digest exists (in the case of digest verification). 870 * 871 * At session registration time, the client specified the digest result 872 * length with the digestResultLenInBytes member of the @ref 873 * CpaCySymHashSetupData structure. The client must allocate at least 874 * digestResultLenInBytes of physically contiguous memory at this location. 875 * 876 * For partial packet processing without algorithm chaining, this pointer 877 * will be ignored for all but the final partial operation. 878 * 879 * For digest generation, the digest result will overwrite any data 880 * at this location. 881 * 882 * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result" 883 * read "authentication tag T". 884 * 885 * If the digestIsAppended member of the @ref CpaCySymSessionSetupData 886 * structure is set then this value is ignored and the digest result 887 * is understood to be in the destination buffer for digest generation, 888 * and in the source buffer for digest verification. The location of the 889 * digest result in this case is immediately following the region over 890 * which the digest is computed. 891 * 892 */ 893 Cpa8U *pAdditionalAuthData; 894 /**< Pointer to Additional Authenticated Data (AAD) needed for 895 * authenticated cipher mechanisms (CCM and GCM), and to the IV for 896 * SNOW3G authentication (@ref CPA_CY_SYM_HASH_SNOW3G_UIA2). 897 * For other authentication mechanisms this pointer is ignored. 898 * 899 * The length of the data pointed to by this field is set up for 900 * the session in the @ref CpaCySymHashAuthModeSetupData structure 901 * as part of the @ref cpaCySymInitSession function call. This length 902 * must not exceed 240 bytes. 903 * 904 * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM), the caller 905 * should setup this field as follows: 906 * 907 * - the nonce should be written starting at an offset of one byte 908 * into the array, leaving room for the implementation to write in 909 * the flags to the first byte. For example, 910 * <br> 911 * memcpy(&pOpData->pAdditionalAuthData[1], pNonce, nonceLen); 912 * <br> 913 * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. 914 * 915 * - the additional authentication data itself should be written 916 * starting at an offset of 18 bytes into the array, leaving room for 917 * the length encoding in the first two bytes of the second block. 918 * For example, 919 * <br> 920 * memcpy(&pOpData->pAdditionalAuthData[18], pAad, aadLen); 921 * <br> 922 * The macro @ref CPA_CY_SYM_CCM_SET_AAD may be used here. 923 * 924 * - the array should be big enough to hold the above fields, plus 925 * any padding to round this up to the nearest multiple of the 926 * block size (16 bytes). Padding will be added by the 927 * implementation. 928 * 929 * Finally, for GCM (@ref CPA_CY_SYM_HASH_AES_GCM), the caller 930 * should setup this field as follows: 931 * 932 * - the AAD is written in starting at byte 0 933 * - the array must be big enough to hold the AAD, plus any padding 934 * to round this up to the nearest multiple of the block size (16 935 * bytes). Padding will be added by the implementation. 936 * 937 * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of 938 * operation, this field is not used and should be set to 0. Instead 939 * the AAD data should be placed in the source buffer. 940 */ 941 } CpaCySymOpData; 942 943 /** 944 ***************************************************************************** 945 * @ingroup cpaCySym 946 * Setup the nonce for CCM. 947 * @description 948 * This macro sets the nonce in the appropriate locations of the 949 * @ref CpaCySymOpData struct for the authenticated encryption 950 * algorithm @ref CPA_CY_SYM_HASH_AES_CCM. 951 ****************************************************************************/ 952 #define CPA_CY_SYM_CCM_SET_NONCE(pOpData, pNonce, nonceLen) do { \ 953 memcpy(&pOpData->pIv[1], pNonce, nonceLen); \ 954 memcpy(&pOpData->pAdditionalAuthData[1], pNonce, nonceLen); \ 955 } while (0) 956 957 /** 958 ***************************************************************************** 959 * @ingroup cpaCySym 960 * Setup the additional authentication data for CCM. 961 * @description 962 * This macro sets the additional authentication data in the 963 * appropriate location of the@ref CpaCySymOpData struct for the 964 * authenticated encryptionalgorithm @ref CPA_CY_SYM_HASH_AES_CCM. 965 ****************************************************************************/ 966 #define CPA_CY_SYM_CCM_SET_AAD(pOpData, pAad, aadLen) do { \ 967 memcpy(&pOpData->pAdditionalAuthData[18], pAad, aadLen); \ 968 } while (0) 969 970 971 /** 972 ***************************************************************************** 973 * @ingroup cpaCySym 974 * Cryptographic Component Statistics. 975 * @deprecated 976 * As of v1.3 of the cryptographic API, this structure has been 977 * deprecated, replaced by @ref CpaCySymStats64. 978 * @description 979 * This structure contains statistics on the Symmetric Cryptographic 980 * operations. Statistics are set to zero when the component is 981 * initialized. 982 ****************************************************************************/ 983 typedef struct _CpaCySymStats { 984 Cpa32U numSessionsInitialized; 985 /**< Number of session initialized */ 986 Cpa32U numSessionsRemoved; 987 /**< Number of sessions removed */ 988 Cpa32U numSessionErrors; 989 /**< Number of session initialized and removed errors. */ 990 Cpa32U numSymOpRequests; 991 /**< Number of successful symmetric operation requests. */ 992 Cpa32U numSymOpRequestErrors; 993 /**< Number of operation requests that had an error and could 994 * not be processed. */ 995 Cpa32U numSymOpCompleted; 996 /**< Number of operations that completed successfully. */ 997 Cpa32U numSymOpCompletedErrors; 998 /**< Number of operations that could not be completed 999 * successfully due to errors. */ 1000 Cpa32U numSymOpVerifyFailures; 1001 /**< Number of operations that completed successfully, but the 1002 * result of the digest verification test was that it failed. 1003 * Note that this does not indicate an error condition. */ 1004 } CpaCySymStats CPA_DEPRECATED; 1005 1006 /** 1007 ***************************************************************************** 1008 * @ingroup cpaCySym 1009 * Cryptographic Component Statistics (64-bit version). 1010 * @description 1011 * This structure contains a 64-bit version of the statistics on 1012 * the Symmetric Cryptographic operations. 1013 * Statistics are set to zero when the component is initialized. 1014 ****************************************************************************/ 1015 typedef struct _CpaCySymStats64 { 1016 Cpa64U numSessionsInitialized; 1017 /**< Number of session initialized */ 1018 Cpa64U numSessionsRemoved; 1019 /**< Number of sessions removed */ 1020 Cpa64U numSessionErrors; 1021 /**< Number of session initialized and removed errors. */ 1022 Cpa64U numSymOpRequests; 1023 /**< Number of successful symmetric operation requests. */ 1024 Cpa64U numSymOpRequestErrors; 1025 /**< Number of operation requests that had an error and could 1026 * not be processed. */ 1027 Cpa64U numSymOpCompleted; 1028 /**< Number of operations that completed successfully. */ 1029 Cpa64U numSymOpCompletedErrors; 1030 /**< Number of operations that could not be completed 1031 * successfully due to errors. */ 1032 Cpa64U numSymOpVerifyFailures; 1033 /**< Number of operations that completed successfully, but the 1034 * result of the digest verification test was that it failed. 1035 * Note that this does not indicate an error condition. */ 1036 } CpaCySymStats64; 1037 1038 /** 1039 ***************************************************************************** 1040 * @ingroup cpaCySym 1041 * Definition of callback function 1042 * 1043 * @description 1044 * This is the callback function prototype. The callback function is 1045 * registered by the application using the cpaCySymInitSession() 1046 * function call. 1047 * 1048 * @context 1049 * This callback function can be executed in a context that DOES NOT 1050 * permit sleeping to occur. 1051 * @assumptions 1052 * None 1053 * @sideEffects 1054 * None 1055 * @reentrant 1056 * No 1057 * @threadSafe 1058 * Yes 1059 * 1060 * @param[in] pCallbackTag Opaque value provided by user while making 1061 * individual function call. 1062 * @param[in] status Status of the operation. Valid values are 1063 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 1064 * CPA_STATUS_UNSUPPORTED. 1065 * @param[in] operationType Identifies the operation type that was 1066 * requested in the cpaCySymPerformOp function. 1067 * @param[in] pOpData Pointer to structure with input parameters. 1068 * @param[in] pDstBuffer Caller MUST allocate a sufficiently sized 1069 * destination buffer to hold the data output. For 1070 * out-of-place processing the data outside the 1071 * cryptographic regions in the source buffer are 1072 * copied into the destination buffer. To perform 1073 * "in-place" processing set the pDstBuffer 1074 * parameter in cpaCySymPerformOp function to point 1075 * at the same location as pSrcBuffer. For optimum 1076 * performance, the data pointed to SHOULD be 1077 * 8-byte aligned. 1078 * @param[in] verifyResult This parameter is valid when the verifyDigest 1079 * option is set in the CpaCySymSessionSetupData 1080 * structure. A value of CPA_TRUE indicates that 1081 * the compare succeeded. A value of CPA_FALSE 1082 * indicates that the compare failed for an 1083 * unspecified reason. 1084 * 1085 * @retval 1086 * None 1087 * @pre 1088 * Component has been initialized. 1089 * @post 1090 * None 1091 * @note 1092 * None 1093 * @see 1094 * cpaCySymInitSession(), 1095 * cpaCySymRemoveSession() 1096 * 1097 *****************************************************************************/ 1098 typedef void (*CpaCySymCbFunc)(void *pCallbackTag, 1099 CpaStatus status, 1100 const CpaCySymOp operationType, 1101 void *pOpData, 1102 CpaBufferList *pDstBuffer, 1103 CpaBoolean verifyResult); 1104 1105 /** 1106 ***************************************************************************** 1107 * @ingroup cpaCySym 1108 * Gets the size required to store a session context. 1109 * 1110 * @description 1111 * This function is used by the client to determine the size of the memory 1112 * it must allocate in order to store the session context. This MUST be 1113 * called before the client allocates the memory for the session context 1114 * and before the client calls the @ref cpaCySymInitSession function. 1115 * 1116 * For a given implementation of this API, it is safe to assume that 1117 * cpaCySymSessionCtxGetSize() will always return the same size and that 1118 * the size will not be different for different setup data parameters. 1119 * However, it should be noted that the size may change: 1120 * (1) between different implementations of the API (e.g. between software 1121 * and hardware implementations or between different hardware 1122 * implementations) 1123 * (2) between different releases of the same API implementation. 1124 * 1125 * The size returned by this function is the smallest size needed to 1126 * support all possible combinations of setup data parameters. Some 1127 * setup data parameter combinations may fit within a smaller session 1128 * context size. The alternate cpaCySymSessionCtxGetDynamicSize() 1129 * function will return the smallest size needed to fit the 1130 * provided setup data parameters. 1131 * 1132 * @context 1133 * This is a synchronous function that cannot sleep. It can be 1134 * executed in a context that does not permit sleeping. 1135 * @assumptions 1136 * None 1137 * @sideEffects 1138 * None 1139 * @blocking 1140 * No. 1141 * @reentrant 1142 * No 1143 * @threadSafe 1144 * Yes 1145 * 1146 * @param[in] instanceHandle Instance handle. 1147 * @param[in] pSessionSetupData Pointer to session setup data which 1148 * contains parameters which are static 1149 * for a given cryptographic session such 1150 * as operation type, mechanisms, and keys 1151 * for cipher and/or hash operations. 1152 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 1153 * to hold the Session Context. 1154 * 1155 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1156 * @retval CPA_STATUS_FAIL Function failed. 1157 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1158 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1159 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1160 * 1161 * @pre 1162 * The component has been initialized via cpaCyStartInstance function. 1163 * @post 1164 * None 1165 * @note 1166 * This is a synchronous function and has no completion callback 1167 * associated with it. 1168 * @see 1169 * CpaCySymSessionSetupData 1170 * cpaCySymInitSession() 1171 * cpaCySymSessionCtxGetDynamicSize() 1172 * cpaCySymPerformOp() 1173 * 1174 *****************************************************************************/ 1175 CpaStatus 1176 cpaCySymSessionCtxGetSize(const CpaInstanceHandle instanceHandle, 1177 const CpaCySymSessionSetupData *pSessionSetupData, 1178 Cpa32U *pSessionCtxSizeInBytes); 1179 1180 /** 1181 ***************************************************************************** 1182 * @ingroup cpaCySym 1183 * Gets the minimum size required to store a session context. 1184 * 1185 * @description 1186 * This function is used by the client to determine the smallest size of 1187 * the memory it must allocate in order to store the session context. 1188 * This MUST be called before the client allocates the memory for the 1189 * session context and before the client calls the @ref cpaCySymInitSession 1190 * function. 1191 * 1192 * This function is an alternate to cpaCySymSessionGetSize(). 1193 * cpaCySymSessionCtxGetSize() will return a fixed size which is the 1194 * minimum memory size needed to support all possible setup data parameter 1195 * combinations. cpaCySymSessionCtxGetDynamicSize() will return the 1196 * minimum memory size needed to support the specific session setup 1197 * data parameters provided. This size may be different for different setup 1198 * data parameters. 1199 * 1200 * @context 1201 * This is a synchronous function that cannot sleep. It can be 1202 * executed in a context that does not permit sleeping. 1203 * @assumptions 1204 * None 1205 * @sideEffects 1206 * None 1207 * @blocking 1208 * No. 1209 * @reentrant 1210 * No 1211 * @threadSafe 1212 * Yes 1213 * 1214 * @param[in] instanceHandle Instance handle. 1215 * @param[in] pSessionSetupData Pointer to session setup data which 1216 * contains parameters which are static 1217 * for a given cryptographic session such 1218 * as operation type, mechanisms, and keys 1219 * for cipher and/or hash operations. 1220 * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required 1221 * to hold the Session Context. 1222 * 1223 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1224 * @retval CPA_STATUS_FAIL Function failed. 1225 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1226 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1227 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1228 * 1229 * @pre 1230 * The component has been initialized via cpaCyStartInstance function. 1231 * @post 1232 * None 1233 * @note 1234 * This is a synchronous function and has no completion callback 1235 * associated with it. 1236 * @see 1237 * CpaCySymSessionSetupData 1238 * cpaCySymInitSession() 1239 * cpaCySymSessionCtxGetSize() 1240 * cpaCySymPerformOp() 1241 * 1242 *****************************************************************************/ 1243 CpaStatus 1244 cpaCySymSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle, 1245 const CpaCySymSessionSetupData *pSessionSetupData, 1246 Cpa32U *pSessionCtxSizeInBytes); 1247 1248 /** 1249 ***************************************************************************** 1250 * @ingroup cpaCySym 1251 * Initialize a session for symmetric cryptographic API. 1252 * 1253 * @description 1254 * This function is used by the client to initialize an asynchronous 1255 * completion callback function for the symmetric cryptographic 1256 * operations. Clients MAY register multiple callback functions using 1257 * this function. 1258 * The callback function is identified by the combination of userContext, 1259 * pSymCb and session context (sessionCtx). The session context is the 1260 * handle to the session and needs to be passed when processing calls. 1261 * Callbacks on completion of operations within a session are guaranteed 1262 * to be in the same order they were submitted in. 1263 * 1264 * @context 1265 * This is a synchronous function and it cannot sleep. It can be 1266 * executed in a context that does not permit sleeping. 1267 * @assumptions 1268 * None 1269 * @sideEffects 1270 * None 1271 * @blocking 1272 * No. 1273 * @reentrant 1274 * No 1275 * @threadSafe 1276 * Yes 1277 * 1278 * @param[in] instanceHandle Instance handle. 1279 * @param[in] pSymCb Pointer to callback function to be 1280 * registered. Set to NULL if the 1281 * cpaCySymPerformOp function is required to 1282 * work in a synchronous manner. 1283 * @param[in] pSessionSetupData Pointer to session setup data which contains 1284 * parameters which are static for a given 1285 * cryptographic session such as operation 1286 * type, mechanisms, and keys for cipher and/or 1287 * hash operations. 1288 * @param[out] sessionCtx Pointer to the memory allocated by the 1289 * client to store the session context. This 1290 * will be initialized with this function. This 1291 * value needs to be passed to subsequent 1292 * processing calls. 1293 * 1294 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1295 * @retval CPA_STATUS_FAIL Function failed. 1296 * @retval CPA_STATUS_RETRY Resubmit the request. 1297 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1298 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1299 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1300 * the request. 1301 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1302 * 1303 * @pre 1304 * The component has been initialized via cpaCyStartInstance function. 1305 * @post 1306 * None 1307 * @note 1308 * This is a synchronous function and has no completion callback 1309 * associated with it. 1310 * @see 1311 * CpaCySymSessionCtx, 1312 * CpaCySymCbFunc, 1313 * CpaCySymSessionSetupData, 1314 * cpaCySymRemoveSession(), 1315 * cpaCySymPerformOp() 1316 * 1317 *****************************************************************************/ 1318 CpaStatus 1319 cpaCySymInitSession(const CpaInstanceHandle instanceHandle, 1320 const CpaCySymCbFunc pSymCb, 1321 const CpaCySymSessionSetupData *pSessionSetupData, 1322 CpaCySymSessionCtx sessionCtx); 1323 1324 /** 1325 ***************************************************************************** 1326 * @ingroup cpaCySym 1327 * Remove (delete) a symmetric cryptographic session. 1328 * 1329 * @description 1330 * This function will remove a previously initialized session context 1331 * and the installed callback handler function. Removal will fail if 1332 * outstanding calls still exist for the initialized session handle. 1333 * The client needs to retry the remove function at a later time. 1334 * The memory for the session context MUST not be freed until this call 1335 * has completed successfully. 1336 * 1337 * @context 1338 * This is a synchronous function that cannot sleep. It can be 1339 * executed in a context that does not permit sleeping. 1340 * @assumptions 1341 * None 1342 * @sideEffects 1343 * None 1344 * @blocking 1345 * No. 1346 * @reentrant 1347 * No 1348 * @threadSafe 1349 * Yes 1350 * 1351 * @param[in] instanceHandle Instance handle. 1352 * @param[in,out] pSessionCtx Session context to be removed. 1353 * 1354 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1355 * @retval CPA_STATUS_FAIL Function failed. 1356 * @retval CPA_STATUS_RETRY Resubmit the request. 1357 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1358 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1359 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1360 * the request. 1361 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1362 * 1363 * @pre 1364 * The component has been initialized via cpaCyStartInstance function. 1365 * @post 1366 * None 1367 * @note 1368 * Note that this is a synchronous function and has no completion callback 1369 * associated with it. 1370 * 1371 * @see 1372 * CpaCySymSessionCtx, 1373 * cpaCySymInitSession() 1374 * 1375 *****************************************************************************/ 1376 CpaStatus 1377 cpaCySymRemoveSession(const CpaInstanceHandle instanceHandle, 1378 CpaCySymSessionCtx pSessionCtx); 1379 1380 /** 1381 ***************************************************************************** 1382 * @ingroup cpaCySym 1383 * Update a session. 1384 * 1385 * @description 1386 * This function is used to update certain parameters of a session, as 1387 * specified by the CpaCySymSessionUpdateData data structure. 1388 * 1389 * It can be used on sessions created with either the so-called 1390 * Traditional API (@ref cpaCySymInitSession) or the Data Plane API 1391 * (@ref cpaCySymDpInitSession). 1392 * 1393 * In order for this function to operate correctly, two criteria must 1394 * be met: 1395 * 1396 * - In the case of sessions created with the Traditional API, the 1397 * session must be stateless, i.e. the field partialsNotRequired of 1398 * the CpaCySymSessionSetupData data structure must be FALSE. 1399 * (Sessions created using the Data Plane API are always stateless.) 1400 * 1401 * - There must be no outstanding requests in flight for the session. 1402 * The application can call the function @ref cpaCySymSessionInUse 1403 * to test for this. 1404 * 1405 * Note that in the case of multi-threaded applications (which are 1406 * supported using the Traditional API only), this function may fail 1407 * even if a previous invocation of the function @ref 1408 * cpaCySymSessionInUse indicated that there were no outstanding 1409 * requests. 1410 * 1411 * @param[in] sessionCtx Identifies the session to be reset. 1412 * @param[in] pSessionUpdateData Pointer to session data which contains 1413 * the parameters to be updated. 1414 * 1415 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1416 * @retval CPA_STATUS_FAIL Function failed. 1417 * @retval CPA_STATUS_RETRY Resubmit the request. 1418 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1419 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1420 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1421 * the request. 1422 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1423 * 1424 * @pre 1425 * The component has been initialized via cpaCyStartInstance function. 1426 * @post 1427 * None 1428 * @note 1429 * This is a synchronous function and has no completion callback 1430 * associated with it. 1431 *****************************************************************************/ 1432 CpaStatus 1433 cpaCySymUpdateSession(CpaCySymSessionCtx sessionCtx, 1434 const CpaCySymSessionUpdateData *pSessionUpdateData); 1435 1436 /** 1437 ***************************************************************************** 1438 * @ingroup cpaCySym 1439 * Indicates whether there are outstanding requests on a given 1440 * session. 1441 * 1442 * @description 1443 * This function is used to test whether there are outstanding 1444 * requests in flight for a specified session. This may be used 1445 * before resetting session parameters using the function @ref 1446 * cpaCySymResetSession. See some additional notes on 1447 * multi-threaded applications described on that function. 1448 * 1449 * @param[in] sessionCtx Identifies the session to be reset. 1450 * @param[out] pSessionInUse Returns CPA_TRUE if there are 1451 * outstanding requests on the session, 1452 * or CPA_FALSE otherwise. 1453 *****************************************************************************/ 1454 CpaStatus 1455 cpaCySymSessionInUse(CpaCySymSessionCtx sessionCtx, 1456 CpaBoolean* pSessionInUse); 1457 1458 /** 1459 ***************************************************************************** 1460 * @ingroup cpaCySym 1461 * Perform a symmetric cryptographic operation on an existing session. 1462 * 1463 * @description 1464 * Performs a cipher, hash or combined (cipher and hash) operation on 1465 * the source data buffer using supported symmetric key algorithms and 1466 * modes. 1467 * 1468 * This function maintains cryptographic state between calls for 1469 * partial cryptographic operations. If a partial cryptographic 1470 * operation is being performed, then on a per-session basis, the next 1471 * part of the multi-part message can be submitted prior to previous 1472 * parts being completed, the only limitation being that all parts 1473 * must be performed in sequential order. 1474 * 1475 * If for any reason a client wishes to terminate the partial packet 1476 * processing on the session (for example if a packet fragment was lost) 1477 * then the client MUST remove the session. 1478 * 1479 * When using partial packet processing with algorithm chaining, only 1480 * the cipher state is maintained between calls. The hash state is 1481 * not be maintained between calls. Instead the hash digest will be 1482 * generated/verified for each call. If both the cipher state and 1483 * hash state need to be maintained between calls, algorithm chaining 1484 * cannot be used. 1485 1486 * The following restrictions apply to the length: 1487 * 1488 * - When performing block based operations on a partial packet 1489 * (excluding the final partial packet), the data that is to be 1490 * operated on MUST be a multiple of the block size of the algorithm 1491 * being used. This restriction only applies to the cipher state 1492 * when using partial packets with algorithm chaining. 1493 * 1494 * - The final block must not be of length zero (0) if the operation 1495 * being performed is the authentication algorithm @ref 1496 * CPA_CY_SYM_HASH_AES_XCBC. This is because this algorithm requires 1497 * that the final block be XORed with another value internally. 1498 * If the length is zero, then the return code @ref 1499 * CPA_STATUS_INVALID_PARAM will be returned. 1500 * 1501 * - The length of the final block must be greater than or equal to 1502 * 16 bytes when using the @ref CPA_CY_SYM_CIPHER_AES_XTS cipher 1503 * algorithm. 1504 * 1505 * Partial packet processing is supported only when the following 1506 * conditions are true: 1507 * 1508 * - The cipher, hash or authentication operation is "in place" (that is, 1509 * pDstBuffer == pSrcBuffer) 1510 * 1511 * - The cipher or hash algorithm is NOT one of Kasumi or SNOW3G 1512 * 1513 * - The cipher mode is NOT F8 mode. 1514 * 1515 * - The hash algorithm is NOT SHAKE 1516 * 1517 * - The cipher algorithm is not SM4 1518 * 1519 * - The cipher algorithm is not CPA_CY_SYM_CIPHER_CHACHA and the hash 1520 * algorithm is not CPA_CY_SYM_HASH_POLY. 1521 * 1522 * - The cipher algorithm is not CPA_CY_SYM_CIPHER_AES_GCM and the hash 1523 * algorithm is not CPA_CY_SYM_HASH_AES_GCM. 1524 * 1525 * - The instance/implementation supports partial packets as one of 1526 * its capabilities (see @ref CpaCySymCapabilitiesInfo). 1527 * 1528 * The term "in-place" means that the result of the cryptographic 1529 * operation is written into the source buffer. The term "out-of-place" 1530 * means that the result of the cryptographic operation is written into 1531 * the destination buffer. To perform "in-place" processing, set the 1532 * pDstBuffer parameter to point at the same location as the pSrcBuffer 1533 * parameter. 1534 * 1535 * @context 1536 * When called as an asynchronous function it cannot sleep. It can be 1537 * executed in a context that does not permit sleeping. 1538 * When called as a synchronous function it may sleep. It MUST NOT be 1539 * executed in a context that DOES NOT permit sleeping. 1540 * @assumptions 1541 * None 1542 * @sideEffects 1543 * None 1544 * @blocking 1545 * Yes when configured to operate in synchronous mode. 1546 * @reentrant 1547 * No 1548 * @threadSafe 1549 * Yes 1550 * 1551 * @param[in] instanceHandle Instance handle. 1552 * @param[in] pCallbackTag Opaque data that will be returned to the client 1553 * in the callback. 1554 * @param[in] pOpData Pointer to a structure containing request 1555 * parameters. The client code allocates the memory 1556 * for this structure. This component takes 1557 * ownership of the memory until it is returned in 1558 * the callback. 1559 * @param[in] pSrcBuffer The source buffer. The caller MUST allocate 1560 * the source buffer and populate it 1561 * with data. For optimum performance, the data 1562 * pointed to SHOULD be 8-byte aligned. For 1563 * block ciphers, the data passed in MUST be 1564 * a multiple of the relevant block size. 1565 * i.e. padding WILL NOT be applied to the data. 1566 * For optimum performance, the buffer should 1567 * only contain the data region that the 1568 * cryptographic operation(s) must be performed on. 1569 * Any additional data in the source buffer may be 1570 * copied to the destination buffer and this copy 1571 * may degrade performance. 1572 * @param[out] pDstBuffer The destination buffer. The caller MUST 1573 * allocate a sufficiently sized destination 1574 * buffer to hold the data output (including 1575 * the authentication tag in the case of CCM). 1576 * Furthermore, the destination buffer must be the 1577 * same size as the source buffer (i.e. the sum of 1578 * lengths of the buffers in the buffer list must 1579 * be the same). This effectively means that the 1580 * source buffer must in fact be big enough to hold 1581 * the output data, too. This is because, 1582 * for out-of-place processing, the data outside the 1583 * regions in the source buffer on which 1584 * cryptographic operations are performed are copied 1585 * into the destination buffer. To perform 1586 * "in-place" processing set the pDstBuffer 1587 * parameter in cpaCySymPerformOp function to point 1588 * at the same location as pSrcBuffer. For optimum 1589 * performance, the data pointed to SHOULD be 1590 * 8-byte aligned. 1591 * @param[out] pVerifyResult In synchronous mode, this parameter is returned 1592 * when the verifyDigest option is set in the 1593 * CpaCySymSessionSetupData structure. A value of 1594 * CPA_TRUE indicates that the compare succeeded. A 1595 * value of CPA_FALSE indicates that the compare 1596 * failed for an unspecified reason. 1597 * 1598 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1599 * @retval CPA_STATUS_FAIL Function failed. 1600 * @retval CPA_STATUS_RETRY Resubmit the request. 1601 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1602 * @retval CPA_STATUS_RESOURCE Error related to system resource. 1603 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1604 * the request. 1605 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1606 * 1607 * @pre 1608 * The component has been initialized via cpaCyStartInstance function. 1609 * A Cryptographic session has been previously setup using the 1610 * @ref cpaCySymInitSession function call. 1611 * @post 1612 * None 1613 * 1614 * @note 1615 * When in asynchronous mode, a callback of type CpaCySymCbFunc is 1616 * generated in response to this function call. Any errors generated during 1617 * processing are reported as part of the callback status code. 1618 * 1619 * @see 1620 * CpaCySymOpData, 1621 * cpaCySymInitSession(), 1622 * cpaCySymRemoveSession() 1623 *****************************************************************************/ 1624 CpaStatus 1625 cpaCySymPerformOp(const CpaInstanceHandle instanceHandle, 1626 void *pCallbackTag, 1627 const CpaCySymOpData *pOpData, 1628 const CpaBufferList *pSrcBuffer, 1629 CpaBufferList *pDstBuffer, 1630 CpaBoolean *pVerifyResult); 1631 1632 /** 1633 ***************************************************************************** 1634 * @ingroup cpaCySym 1635 * Query symmetric cryptographic statistics for a specific instance. 1636 * 1637 * @deprecated 1638 * As of v1.3 of the cryptographic API, this function has been 1639 * deprecated, replaced by @ref cpaCySymQueryStats64(). 1640 * 1641 * @description 1642 * This function will query a specific instance for statistics. The 1643 * user MUST allocate the CpaCySymStats structure and pass the 1644 * reference to that into this function call. This function will write 1645 * the statistic results into the passed in CpaCySymStats 1646 * structure. 1647 * 1648 * Note: statistics returned by this function do not interrupt current data 1649 * processing and as such can be slightly out of sync with operations that 1650 * are in progress during the statistics retrieval process. 1651 * 1652 * @context 1653 * This is a synchronous function and it can sleep. It MUST NOT be 1654 * executed in a context that DOES NOT permit sleeping. 1655 * @assumptions 1656 * None 1657 * @sideEffects 1658 * None 1659 * @blocking 1660 * Yes 1661 * @reentrant 1662 * No 1663 * @threadSafe 1664 * Yes 1665 * 1666 * @param[in] instanceHandle Instance handle. 1667 * @param[out] pSymStats Pointer to memory into which the 1668 * statistics will be written. 1669 * 1670 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1671 * @retval CPA_STATUS_FAIL Function failed. 1672 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1673 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1674 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1675 * the request. 1676 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1677 * 1678 * @pre 1679 * Component has been initialized. 1680 * @post 1681 * None 1682 * @note 1683 * This function operates in a synchronous manner, i.e. no asynchronous 1684 * callback will be generated. 1685 * @see 1686 * CpaCySymStats 1687 *****************************************************************************/ 1688 CpaStatus CPA_DEPRECATED 1689 cpaCySymQueryStats(const CpaInstanceHandle instanceHandle, 1690 struct _CpaCySymStats *pSymStats); 1691 1692 /** 1693 ***************************************************************************** 1694 * @ingroup cpaCySym 1695 * Query symmetric cryptographic statistics (64-bit version) for a 1696 * specific instance. 1697 * 1698 * @description 1699 * This function will query a specific instance for statistics. The 1700 * user MUST allocate the CpaCySymStats64 structure and pass the 1701 * reference to that into this function call. This function will write 1702 * the statistic results into the passed in CpaCySymStats64 1703 * structure. 1704 * 1705 * Note: statistics returned by this function do not interrupt current data 1706 * processing and as such can be slightly out of sync with operations that 1707 * are in progress during the statistics retrieval process. 1708 * 1709 * @context 1710 * This is a synchronous function and it can sleep. It MUST NOT be 1711 * executed in a context that DOES NOT permit sleeping. 1712 * @assumptions 1713 * None 1714 * @sideEffects 1715 * None 1716 * @blocking 1717 * Yes 1718 * @reentrant 1719 * No 1720 * @threadSafe 1721 * Yes 1722 * 1723 * @param[in] instanceHandle Instance handle. 1724 * @param[out] pSymStats Pointer to memory into which the 1725 * statistics will be written. 1726 * 1727 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1728 * @retval CPA_STATUS_FAIL Function failed. 1729 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1730 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1731 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1732 * the request. 1733 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1734 * 1735 * @pre 1736 * Component has been initialized. 1737 * @post 1738 * None 1739 * @note 1740 * This function operates in a synchronous manner, i.e. no asynchronous 1741 * callback will be generated. 1742 * @see 1743 * CpaCySymStats64 1744 *****************************************************************************/ 1745 CpaStatus 1746 cpaCySymQueryStats64(const CpaInstanceHandle instanceHandle, 1747 CpaCySymStats64 *pSymStats); 1748 1749 /** 1750 ***************************************************************************** 1751 * @ingroup cpaCySym 1752 * Symmetric Capabilities Info 1753 * 1754 * @description 1755 * This structure contains the capabilities that vary across 1756 * implementations of the symmetric sub-API of the cryptographic API. 1757 * This structure is used in conjunction with @ref 1758 * cpaCySymQueryCapabilities() to determine the capabilities supported 1759 * by a particular API implementation. 1760 * 1761 * For example, to see if an implementation supports cipher 1762 * @ref CPA_CY_SYM_CIPHER_AES_CBC, use the code 1763 * 1764 * @code 1765 1766 if (CPA_BITMAP_BIT_TEST(capInfo.ciphers, CPA_CY_SYM_CIPHER_AES_CBC)) 1767 { 1768 // algo is supported 1769 } 1770 else 1771 { 1772 // algo is not supported 1773 } 1774 * @endcode 1775 * 1776 * The client MUST allocate memory for this structure and any members 1777 * that require memory. When the structure is passed into the function 1778 * ownership of the memory passes to the function. Ownership of the 1779 * memory returns to the client when the function returns. 1780 *****************************************************************************/ 1781 typedef struct _CpaCySymCapabilitiesInfo 1782 { 1783 CPA_BITMAP(ciphers, CPA_CY_SYM_CIPHER_CAP_BITMAP_SIZE); 1784 /**< Bitmap representing which cipher algorithms (and modes) are 1785 * supported by the instance. 1786 * Bits can be tested using the macro @ref CPA_BITMAP_BIT_TEST. 1787 * The bit positions are those specified in the enumerated type 1788 * @ref CpaCySymCipherAlgorithm. */ 1789 CPA_BITMAP(hashes, CPA_CY_SYM_HASH_CAP_BITMAP_SIZE); 1790 /**< Bitmap representing which hash/authentication algorithms are 1791 * supported by the instance. 1792 * Bits can be tested using the macro @ref CPA_BITMAP_BIT_TEST. 1793 * The bit positions are those specified in the enumerated type 1794 * @ref CpaCySymHashAlgorithm. */ 1795 CpaBoolean partialPacketSupported; 1796 /**< CPA_TRUE if instance supports partial packets. 1797 * See @ref CpaCySymPacketType. */ 1798 } CpaCySymCapabilitiesInfo; 1799 1800 /** 1801 ***************************************************************************** 1802 * @ingroup cpaCySym 1803 * Returns capabilities of the symmetric API group of a Cryptographic 1804 * API instance. 1805 * 1806 * @description 1807 * This function is used to determine which specific capabilities are 1808 * supported within the symmetric sub-group of the Cryptographic API. 1809 * 1810 * @context 1811 * The function shall not be called in an interrupt context. 1812 * @assumptions 1813 * None 1814 * @sideEffects 1815 * None 1816 * @blocking 1817 * This function is synchronous and blocking. 1818 * @reentrant 1819 * No 1820 * @threadSafe 1821 * Yes 1822 * 1823 * @param[in] instanceHandle Handle to an instance of this API. 1824 * @param[out] pCapInfo Pointer to capabilities info structure. 1825 * All fields in the structure 1826 * are populated by the API instance. 1827 * 1828 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1829 * @retval CPA_STATUS_FAIL Function failed. 1830 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1831 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1832 * 1833 * @pre 1834 * The instance has been initialized via the @ref cpaCyStartInstance 1835 * function. 1836 * @post 1837 * None 1838 *****************************************************************************/ 1839 CpaStatus 1840 cpaCySymQueryCapabilities(const CpaInstanceHandle instanceHandle, 1841 CpaCySymCapabilitiesInfo * pCapInfo); 1842 1843 #ifdef __cplusplus 1844 } /* close the extern "C" { */ 1845 #endif 1846 1847 #endif /* CPA_CY_SYM_H */ 1848