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