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_key.h 12 * 13 * @defgroup cpaCyKeyGen Cryptographic Key and Mask Generation API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for key and mask generation 19 * operations. 20 * 21 *****************************************************************************/ 22 23 #ifndef CPA_CY_KEY_H 24 #define CPA_CY_KEY_H 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include "cpa_cy_common.h" 31 #include "cpa_cy_sym.h" /* needed for hash algorithm, for MGF */ 32 33 /** 34 ***************************************************************************** 35 * @ingroup cpaCyKeyGen 36 * SSL or TLS key generation random number length. 37 * 38 * @description 39 * Defines the permitted SSL or TLS random number length in bytes that 40 * may be used with the functions @ref cpaCyKeyGenSsl and @ref 41 * cpaCyKeyGenTls. This is the length of the client or server random 42 * number values. 43 *****************************************************************************/ 44 #define CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES (32) 45 46 /** 47 ***************************************************************************** 48 * @ingroup cpaCyKeyGen 49 * SSL Operation Types 50 * @description 51 * Enumeration of the different SSL operations that can be specified in 52 * the struct @ref CpaCyKeyGenSslOpData. It identifies the label. 53 *****************************************************************************/ 54 typedef enum _CpaCyKeySslOp 55 { 56 CPA_CY_KEY_SSL_OP_MASTER_SECRET_DERIVE = 1, 57 /**< Derive the master secret */ 58 CPA_CY_KEY_SSL_OP_KEY_MATERIAL_DERIVE, 59 /**< Derive the key material */ 60 CPA_CY_KEY_SSL_OP_USER_DEFINED 61 /**< User Defined Operation for custom labels*/ 62 } CpaCyKeySslOp; 63 64 65 /** 66 ***************************************************************************** 67 * @ingroup cpaCyKeyGen 68 * SSL data for key generation functions 69 * @description 70 * This structure contains data for use in key generation operations for 71 * SSL. For specific SSL key generation operations, the structure fields 72 * MUST be set as follows: 73 * 74 * @par SSL Master-Secret Derivation: 75 * <br> sslOp = CPA_CY_KEY_SSL_OP_MASTER_SECRET_DERIVE 76 * <br> secret = pre-master secret key 77 * <br> seed = client_random + server_random 78 * <br> userLabel = NULL 79 * 80 * @par SSL Key-Material Derivation: 81 * <br> sslOp = CPA_CY_KEY_SSL_OP_KEY_MATERIAL_DERIVE 82 * <br> secret = master secret key 83 * <br> seed = server_random + client_random 84 * <br> userLabel = NULL 85 * 86 * <br> Note that the client/server random order is reversed from that 87 * used for master-secret derivation. 88 * 89 * @note Each of the client and server random numbers need to be of 90 * length CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES. 91 * 92 * @note In each of the above descriptions, + indicates concatenation. 93 * 94 * @note The label used is predetermined by the SSL operation in line 95 * with the SSL 3.0 specification, and can be overridden by using 96 * a user defined operation CPA_CY_KEY_SSL_OP_USER_DEFINED and 97 * associated userLabel. 98 * 99 ****************************************************************************/ 100 typedef struct _CpaCyKeyGenSslOpData { 101 CpaCyKeySslOp sslOp; 102 /**< Indicate the SSL operation to be performed */ 103 CpaFlatBuffer secret; 104 /**< Flat buffer containing a pointer to either the master or pre-master 105 * secret key. The length field indicates the length of the secret key in 106 * bytes. Implementation-specific limits may apply to this length. */ 107 CpaFlatBuffer seed; 108 /**< Flat buffer containing a pointer to the seed data. 109 * Implementation-specific limits may apply to this length. */ 110 CpaFlatBuffer info; 111 /**< Flat buffer containing a pointer to the info data. 112 * Implementation-specific limits may apply to this length. */ 113 Cpa32U generatedKeyLenInBytes; 114 /**< The requested length of the generated key in bytes. 115 * Implementation-specific limits may apply to this length. */ 116 CpaFlatBuffer userLabel; 117 /**< Optional flat buffer containing a pointer to a user defined label. 118 * The length field indicates the length of the label in bytes. To use this 119 * field, the sslOp must be CPA_CY_KEY_SSL_OP_USER_DEFINED, 120 * or otherwise it is ignored and can be set to NULL. 121 * Implementation-specific limits may apply to this length. */ 122 } CpaCyKeyGenSslOpData; 123 124 /** 125 ***************************************************************************** 126 * @ingroup cpaCyKeyGen 127 * TLS Operation Types 128 * @description 129 * Enumeration of the different TLS operations that can be specified in 130 * the CpaCyKeyGenTlsOpData. It identifies the label. 131 * 132 * The functions @ref cpaCyKeyGenTls and @ref cpaCyKeyGenTls2 133 * accelerate the TLS PRF, which is defined as part of RFC2246 (TLS 134 * v1.0), RFC4346 (TLS v1.1), and RFC5246 (TLS v1.2). 135 * One of the inputs to each of these functions is a label. 136 * This enumerated type defines values that correspond to some of 137 * the required labels. 138 * However, for some of the operations/labels required by these RFCs, 139 * no values are specified. 140 * 141 * In such cases, a user-defined value must be provided. The client 142 * should use the enum value @ref CPA_CY_KEY_TLS_OP_USER_DEFINED, and 143 * pass the label using the userLabel field of the @ref 144 * CpaCyKeyGenTlsOpData data structure. 145 * 146 *****************************************************************************/ 147 typedef enum _CpaCyKeyTlsOp 148 { 149 CPA_CY_KEY_TLS_OP_MASTER_SECRET_DERIVE = 1, 150 /**< Derive the master secret using the TLS PRF. 151 * Corresponds to RFC2246/5246 section 8.1, operation "Computing the 152 * master secret", label "master secret". */ 153 CPA_CY_KEY_TLS_OP_KEY_MATERIAL_DERIVE, 154 /**< Derive the key material using the TLS PRF. 155 * Corresponds to RFC2246/5246 section 6.3, operation "Derive the key 156 * material", label "key expansion". */ 157 CPA_CY_KEY_TLS_OP_CLIENT_FINISHED_DERIVE, 158 /**< Derive the client finished tag using the TLS PRF. 159 * Corresponds to RFC2246/5246 section 7.4.9, operation "Client finished", 160 * label "client finished". */ 161 CPA_CY_KEY_TLS_OP_SERVER_FINISHED_DERIVE, 162 /**< Derive the server finished tag using the TLS PRF. 163 * Corresponds to RFC2246/5246 section 7.4.9, operation "Server finished", 164 * label "server finished". */ 165 CPA_CY_KEY_TLS_OP_USER_DEFINED 166 /**< User Defined Operation for custom labels. */ 167 168 } CpaCyKeyTlsOp; 169 170 171 /** 172 ***************************************************************************** 173 * @file cpa_cy_key.h 174 * @ingroup cpaCyKeyGen 175 * TLS Operation Types 176 * @description 177 * Enumeration of the different TLS operations that can be specified in 178 * the CpaCyKeyGenHKDFOpData. 179 * 180 * The function @ref cpaCyKeyGenTls3 181 * accelerates the TLS HKDF, which is defined as part of RFC5869 (HKDF) 182 * and RFC8446 (TLS v1.3). 183 * 184 * This enumerated type defines the support HKDF operations for 185 * extraction and expansion of keying material. 186 * 187 *****************************************************************************/ 188 typedef enum _CpaCyKeyHKDFOp 189 { 190 CPA_CY_HKDF_KEY_EXTRACT = 12, 191 /**< HKDF Extract operation 192 * Corresponds to RFC5869 section 2.2, step 1 "Extract" */ 193 CPA_CY_HKDF_KEY_EXPAND, 194 /**< HKDF Expand operation 195 * Corresponds to RFC5869 section 2.3, step 2 "Expand" */ 196 CPA_CY_HKDF_KEY_EXTRACT_EXPAND, 197 /**< HKDF operation 198 * This performs HKDF_EXTRACT and HKDF_EXPAND in a single 199 * API invocation. */ 200 CPA_CY_HKDF_KEY_EXPAND_LABEL , 201 /**< HKDF Expand label operation for TLS 1.3 202 * Corresponds to RFC8446 section 7.1 Key Schedule definition for 203 * HKDF-Expand-Label, which refers to HKDF-Expand defined in RFC5869. */ 204 CPA_CY_HKDF_KEY_EXTRACT_EXPAND_LABEL 205 /**< HKDF Extract plus Expand label operation for TLS 1.3 206 * Corresponds to RFC5869 section 2.2, step 1 "Extract" followed by 207 * RFC8446 section 7.1 Key Schedule definition for 208 * HKDF-Expand-Label, which refers to HKDF-Expand defined in RFC5869. */ 209 } CpaCyKeyHKDFOp; 210 211 212 /** 213 ***************************************************************************** 214 * @file cpa_cy_key.h 215 * @ingroup cpaCyKeyGen 216 * TLS Operation Types 217 * @description 218 * Enumeration of the different cipher suites that may be used in a TLS 219 * v1.3 operation. This value is used to infer the sizes of the key 220 * and iv sublabel. 221 * 222 * The function @ref cpaCyKeyGenTls3 223 * accelerates the TLS HKDF, which is defined as part of RFC5869 (HKDF) 224 * and RFC8446 (TLS v1.3). 225 * 226 * This enumerated type defines the supported cipher suites in the 227 * TLS operation that require HKDF key operations. 228 * 229 *****************************************************************************/ 230 typedef enum _CpaCyKeyHKDFCipherSuite 231 { 232 CPA_CY_HKDF_TLS_AES_128_GCM_SHA256 = 1, 233 CPA_CY_HKDF_TLS_AES_256_GCM_SHA384, 234 CPA_CY_HKDF_TLS_CHACHA20_POLY1305_SHA256 , 235 CPA_CY_HKDF_TLS_AES_128_CCM_SHA256, 236 CPA_CY_HKDF_TLS_AES_128_CCM_8_SHA256 237 } CpaCyKeyHKDFCipherSuite; 238 239 240 /** 241 ***************************************************************************** 242 * @file cpa_cy_key.h 243 * @ingroup cpaCyKeyGen 244 * TLS Operation Types 245 * @description 246 * Bitwise constants for HKDF sublabels 247 * 248 * These definitions provide bit settings for sublabels for 249 * HKDF-ExpandLabel operations. 250 * 251 * <br> key sublabel to generate "key" keying material 252 * <br> iv sublabel to generate "iv" keying material 253 * <br> resumption sublabel to generate "resumption" keying material 254 * <br> finished sublabel to generate "finished" keying material 255 * 256 *****************************************************************************/ 257 258 #define CPA_CY_HKDF_SUBLABEL_KEY ((Cpa16U)0x0001) 259 /**< Bit for creation of key material for 'key' sublabel */ 260 #define CPA_CY_HKDF_SUBLABEL_IV ((Cpa16U)0x0002) 261 /**< Bit for creation of key material for 'iv' sublabel */ 262 #define CPA_CY_HKDF_SUBLABEL_RESUMPTION ((Cpa16U)0x0004) 263 /**< Bit for creation of key material for 'resumption' sublabel */ 264 #define CPA_CY_HKDF_SUBLABEL_FINISHED ((Cpa16U)0x0008) 265 /**< Bit for creation of key material for 'finished' sublabel */ 266 267 #define CPA_CY_HKDF_KEY_MAX_SECRET_SZ ((Cpa8U)80) 268 /** space in bytes PSK or (EC)DH */ 269 #define CPA_CY_HKDF_KEY_MAX_HMAC_SZ ((Cpa8U)48) 270 /** space in bytes of CPA_CY_SYM_HASH_SHA384 result */ 271 #define CPA_CY_HKDF_KEY_MAX_INFO_SZ ((Cpa8U)80) 272 /** space in bytes of largest info needed for TLS 1.3, 273 * rounded up to multiple of 8 */ 274 #define CPA_CY_HKDF_KEY_MAX_LABEL_SZ ((Cpa8U)78) 275 /** space in bytes of largest label for TLS 1.3 */ 276 #define CPA_CY_HKDF_KEY_MAX_LABEL_COUNT ((Cpa8U)4) 277 /** Maximum number of labels in op structure */ 278 279 /** 280 ***************************************************************************** 281 * @file cpa_cy_key.h 282 * @ingroup cpaCyKeyGen 283 * TLS data for key generation functions 284 * @description 285 * This structure contains data for describing label for the 286 * HKDF Extract Label function 287 * 288 * @par Extract Label Function 289 * <br> labelLen = length of the label field 290 * <br> contextLen = length of the context field 291 * <br> sublabelFlag = Mask of sub labels required for this label. 292 * <br> label = label as defined in RFC8446 293 * <br> context = context as defined in RFC8446 294 * 295 ****************************************************************************/ 296 typedef struct _CpaCyKeyGenHKDFExpandLabel 297 { 298 Cpa8U label[CPA_CY_HKDF_KEY_MAX_LABEL_SZ]; 299 /**< HKDFLabel field as defined in RFC8446 sec 7.1. 300 */ 301 Cpa8U labelLen; 302 /**< The length, in bytes of the label */ 303 Cpa8U sublabelFlag; 304 /**< mask of sublabels to be generated. 305 * This flag is composed of zero or more of: 306 * CPA_CY_HKDF_SUBLABEL_KEY 307 * CPA_CY_HKDF_SUBLABEL_IV 308 * CPA_CY_HKDF_SUBLABEL_RESUMPTION 309 * CPA_CY_HKDF_SUBLABEL_FINISHED 310 */ 311 } CpaCyKeyGenHKDFExpandLabel; 312 313 /** 314 ***************************************************************************** 315 * @ingroup cpaCyKeyGen 316 * TLS data for key generation functions 317 * @description 318 * This structure contains data for all HKDF operations: 319 * <br> HKDF Extract 320 * <br> HKDF Expand 321 * <br> HKDF Expand Label 322 * <br> HKDF Extract and Expand 323 * <br> HKDF Extract and Expand Label 324 * 325 * @par HKDF Map Structure Elements 326 * <br> secret - IKM value for extract operations or PRK for expand 327 * or expand operations. 328 * <br> seed - contains the salt for extract 329 * operations 330 * <br> info - contains the info data for extract operations 331 * <br> labels - See notes above 332 * 333 ****************************************************************************/ 334 typedef struct _CpaCyKeyGenHKDFOpData 335 { 336 CpaCyKeyHKDFOp hkdfKeyOp; 337 /**< Keying operation to be performed. */ 338 Cpa8U secretLen; 339 /**< Length of secret field */ 340 Cpa16U seedLen; 341 /**< Length of seed field */ 342 Cpa16U infoLen; 343 /**< Length of info field */ 344 Cpa16U numLabels; 345 /**< Number of filled CpaCyKeyGenHKDFExpandLabel elements */ 346 Cpa8U secret[CPA_CY_HKDF_KEY_MAX_SECRET_SZ]; 347 /**< Input Key Material or PRK */ 348 Cpa8U seed[CPA_CY_HKDF_KEY_MAX_HMAC_SZ]; 349 /**< Input salt */ 350 Cpa8U info[CPA_CY_HKDF_KEY_MAX_INFO_SZ]; 351 /**< info field */ 352 CpaCyKeyGenHKDFExpandLabel label[CPA_CY_HKDF_KEY_MAX_LABEL_COUNT]; 353 /**< array of Expand Label structures */ 354 } CpaCyKeyGenHKDFOpData; 355 356 /** 357 ***************************************************************************** 358 * @ingroup cpaCyKeyGen 359 * TLS data for key generation functions 360 * @description 361 * This structure contains data for use in key generation operations for 362 * TLS. For specific TLS key generation operations, the structure fields 363 * MUST be set as follows: 364 * 365 * @par TLS Master-Secret Derivation: 366 * <br> tlsOp = CPA_CY_KEY_TLS_OP_MASTER_SECRET_DERIVE 367 * <br> secret = pre-master secret key 368 * <br> seed = client_random + server_random 369 * <br> userLabel = NULL 370 * 371 * @par TLS Key-Material Derivation: 372 * <br> tlsOp = CPA_CY_KEY_TLS_OP_KEY_MATERIAL_DERIVE 373 * <br> secret = master secret key 374 * <br> seed = server_random + client_random 375 * <br> userLabel = NULL 376 * 377 * <br> Note that the client/server random order is reversed from 378 * that used for Master-Secret Derivation. 379 * 380 * @par TLS Client finished/Server finished tag Derivation: 381 * <br> tlsOp = CPA_CY_KEY_TLS_OP_CLIENT_FINISHED_DERIVE (client) 382 * <br> or CPA_CY_KEY_TLS_OP_SERVER_FINISHED_DERIVE (server) 383 * <br> secret = master secret key 384 * <br> seed = MD5(handshake_messages) + SHA-1(handshake_messages) 385 * <br> userLabel = NULL 386 * 387 * @note Each of the client and server random seeds need to be of 388 * length CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES. 389 * @note In each of the above descriptions, + indicates concatenation. 390 * @note The label used is predetermined by the TLS operation in line 391 * with the TLS specifications, and can be overridden by using 392 * a user defined operation CPA_CY_KEY_TLS_OP_USER_DEFINED 393 * and associated userLabel. 394 * 395 ****************************************************************************/ 396 typedef struct _CpaCyKeyGenTlsOpData { 397 CpaCyKeyTlsOp tlsOp; 398 /**< TLS operation to be performed */ 399 CpaFlatBuffer secret; 400 /**< Flat buffer containing a pointer to either the master or pre-master 401 * secret key. The length field indicates the length of the secret in 402 * bytes. */ 403 CpaFlatBuffer seed; 404 /**< Flat buffer containing a pointer to the seed data. 405 * Implementation-specific limits may apply to this length. */ 406 Cpa32U generatedKeyLenInBytes; 407 /**< The requested length of the generated key in bytes. 408 * Implementation-specific limits may apply to this length. */ 409 CpaFlatBuffer userLabel; 410 /**< Optional flat buffer containing a pointer to a user defined label. 411 * The length field indicates the length of the label in bytes. To use this 412 * field, the tlsOp must be CPA_CY_KEY_TLS_OP_USER_DEFINED. 413 * Implementation-specific limits may apply to this length. */ 414 } CpaCyKeyGenTlsOpData; 415 416 /** 417 ***************************************************************************** 418 * @ingroup cpaCyKeyGen 419 * Key Generation Mask Generation Function (MGF) Data 420 * @description 421 * This structure contains data relating to Mask Generation Function 422 * key generation operations. 423 * 424 * @note The default hash algorithm used by the MGF is SHA-1. If a 425 * different hash algorithm is preferred, then see the extended 426 * version of this structure, @ref CpaCyKeyGenMgfOpDataExt. 427 * @see 428 * cpaCyKeyGenMgf 429 ****************************************************************************/ 430 typedef struct _CpaCyKeyGenMgfOpData { 431 CpaFlatBuffer seedBuffer; 432 /**< Caller MUST allocate a buffer and populate with the input seed 433 * data. For optimal performance the start of the seed SHOULD be allocated 434 * on an 8-byte boundary. The length field represents the seed length in 435 * bytes. Implementation-specific limits may apply to this length. */ 436 Cpa32U maskLenInBytes; 437 /**< The requested length of the generated mask in bytes. 438 * Implementation-specific limits may apply to this length. */ 439 } CpaCyKeyGenMgfOpData; 440 441 /** 442 ***************************************************************************** 443 * @ingroup cpaCyKeyGen 444 * Extension to the original Key Generation Mask Generation Function 445 * (MGF) Data 446 * @description 447 * This structure is an extension to the original MGF data structure. 448 * The extension allows the hash function to be specified. 449 * @note 450 * This structure is separate from the base @ref CpaCyKeyGenMgfOpData 451 * structure in order to retain backwards compatibility with the 452 * original version of the API. 453 * @see 454 * cpaCyKeyGenMgfExt 455 ****************************************************************************/ 456 typedef struct _CpaCyKeyGenMgfOpDataExt { 457 CpaCyKeyGenMgfOpData baseOpData; 458 /**< "Base" operational data for MGF generation */ 459 CpaCySymHashAlgorithm hashAlgorithm; 460 /**< Specifies the hash algorithm to be used by the Mask Generation 461 * Function */ 462 } CpaCyKeyGenMgfOpDataExt; 463 464 /** 465 ***************************************************************************** 466 * @ingroup cpaCyKeyGen 467 * Key Generation Statistics. 468 * @deprecated 469 * As of v1.3 of the Crypto API, this structure has been deprecated, 470 * replaced by @ref CpaCyKeyGenStats64. 471 * @description 472 * This structure contains statistics on the key and mask generation 473 * operations. Statistics are set to zero when the component is 474 * initialized, and are collected per instance. 475 * 476 ****************************************************************************/ 477 typedef struct _CpaCyKeyGenStats { 478 Cpa32U numSslKeyGenRequests; 479 /**< Total number of successful SSL key generation requests. */ 480 Cpa32U numSslKeyGenRequestErrors; 481 /**< Total number of SSL key generation requests that had an error and 482 * could not be processed. */ 483 Cpa32U numSslKeyGenCompleted; 484 /**< Total number of SSL key generation operations that completed 485 * successfully. */ 486 Cpa32U numSslKeyGenCompletedErrors; 487 /**< Total number of SSL key generation operations that could not be 488 * completed successfully due to errors. */ 489 Cpa32U numTlsKeyGenRequests; 490 /**< Total number of successful TLS key generation requests. */ 491 Cpa32U numTlsKeyGenRequestErrors; 492 /**< Total number of TLS key generation requests that had an error and 493 * could not be processed. */ 494 Cpa32U numTlsKeyGenCompleted; 495 /**< Total number of TLS key generation operations that completed 496 * successfully. */ 497 Cpa32U numTlsKeyGenCompletedErrors; 498 /**< Total number of TLS key generation operations that could not be 499 * completed successfully due to errors. */ 500 Cpa32U numMgfKeyGenRequests; 501 /**< Total number of successful MGF key generation requests (including 502 * "extended" MGF requests). */ 503 Cpa32U numMgfKeyGenRequestErrors; 504 /**< Total number of MGF key generation requests that had an error and 505 * could not be processed. */ 506 Cpa32U numMgfKeyGenCompleted; 507 /**< Total number of MGF key generation operations that completed 508 * successfully. */ 509 Cpa32U numMgfKeyGenCompletedErrors; 510 /**< Total number of MGF key generation operations that could not be 511 * completed successfully due to errors. */ 512 } CpaCyKeyGenStats CPA_DEPRECATED; 513 514 /** 515 ***************************************************************************** 516 * @ingroup cpaCyKeyGen 517 * Key Generation Statistics (64-bit version). 518 * @description 519 * This structure contains the 64-bit version of the statistics 520 * on the key and mask generation operations. 521 * Statistics are set to zero when the component is 522 * initialized, and are collected per instance. 523 * 524 ****************************************************************************/ 525 typedef struct _CpaCyKeyGenStats64 { 526 Cpa64U numSslKeyGenRequests; 527 /**< Total number of successful SSL key generation requests. */ 528 Cpa64U numSslKeyGenRequestErrors; 529 /**< Total number of SSL key generation requests that had an error and 530 * could not be processed. */ 531 Cpa64U numSslKeyGenCompleted; 532 /**< Total number of SSL key generation operations that completed 533 * successfully. */ 534 Cpa64U numSslKeyGenCompletedErrors; 535 /**< Total number of SSL key generation operations that could not be 536 * completed successfully due to errors. */ 537 Cpa64U numTlsKeyGenRequests; 538 /**< Total number of successful TLS key generation requests. */ 539 Cpa64U numTlsKeyGenRequestErrors; 540 /**< Total number of TLS key generation requests that had an error and 541 * could not be processed. */ 542 Cpa64U numTlsKeyGenCompleted; 543 /**< Total number of TLS key generation operations that completed 544 * successfully. */ 545 Cpa64U numTlsKeyGenCompletedErrors; 546 /**< Total number of TLS key generation operations that could not be 547 * completed successfully due to errors. */ 548 Cpa64U numMgfKeyGenRequests; 549 /**< Total number of successful MGF key generation requests (including 550 * "extended" MGF requests). */ 551 Cpa64U numMgfKeyGenRequestErrors; 552 /**< Total number of MGF key generation requests that had an error and 553 * could not be processed. */ 554 Cpa64U numMgfKeyGenCompleted; 555 /**< Total number of MGF key generation operations that completed 556 * successfully. */ 557 Cpa64U numMgfKeyGenCompletedErrors; 558 /**< Total number of MGF key generation operations that could not be 559 * completed successfully due to errors. */ 560 } CpaCyKeyGenStats64; 561 562 /** 563 ***************************************************************************** 564 * @ingroup cpaCyKeyGen 565 * SSL Key Generation Function. 566 * @description 567 * This function is used for SSL key generation. It implements the key 568 * generation function defined in section 6.2.2 of the SSL 3.0 569 * specification as described in 570 * http://www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt. 571 * 572 * The input seed is taken as a flat buffer and the generated key is 573 * returned to caller in a flat destination data buffer. 574 * @context 575 * When called as an asynchronous function it cannot sleep. It can be 576 * executed in a context that does not permit sleeping. 577 * When called as a synchronous function it may sleep. It MUST NOT be 578 * executed in a context that DOES NOT permit sleeping. 579 * @assumptions 580 * None 581 * @sideEffects 582 * None 583 * @blocking 584 * Yes when configured to operate in synchronous mode. 585 * @reentrant 586 * No 587 * @threadSafe 588 * Yes 589 * 590 * @param[in] instanceHandle Instance handle. 591 * @param[in] pKeyGenCb Pointer to callback function to be 592 * invoked when the operation is complete. 593 * If this is set to a NULL value the 594 * function will operate synchronously. 595 * @param[in] pCallbackTag Opaque User Data for this specific 596 * call. Will be returned unchanged in the 597 * callback. 598 * @param[in] pKeyGenSslOpData Structure containing all the data 599 * needed to perform the SSL key 600 * generation operation. The client code 601 * allocates the memory for this 602 * structure. This component takes 603 * ownership of the memory until it is 604 * returned in the callback. 605 * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient 606 * buffer to hold the key generation 607 * output. The data pointer SHOULD be 608 * aligned on an 8-byte boundary. The 609 * length field passed in represents the 610 * size of the buffer in bytes. The value 611 * that is returned is the size of the 612 * result key in bytes. 613 * On invocation the callback function 614 * will contain this parameter in the 615 * pOut parameter. 616 * 617 * @retval CPA_STATUS_SUCCESS Function executed successfully. 618 * @retval CPA_STATUS_FAIL Function failed. 619 * @retval CPA_STATUS_RETRY Resubmit the request. 620 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 621 * @retval CPA_STATUS_RESOURCE Error related to system resources. 622 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 623 * Resubmit the request. 624 * 625 * @pre 626 * The component has been initialized via cpaCyStartInstance function. 627 * @post 628 * None 629 * @see 630 * CpaCyKeyGenSslOpData, 631 * CpaCyGenFlatBufCbFunc 632 * 633 *****************************************************************************/ 634 CpaStatus 635 cpaCyKeyGenSsl(const CpaInstanceHandle instanceHandle, 636 const CpaCyGenFlatBufCbFunc pKeyGenCb, 637 void *pCallbackTag, 638 const CpaCyKeyGenSslOpData *pKeyGenSslOpData, 639 CpaFlatBuffer *pGeneratedKeyBuffer); 640 641 /** 642 ***************************************************************************** 643 * @ingroup cpaCyKeyGen 644 * TLS Key Generation Function. 645 * @description 646 * This function is used for TLS key generation. It implements the 647 * TLS PRF (Pseudo Random Function) as defined by RFC2246 (TLS v1.0) 648 * and RFC4346 (TLS v1.1). 649 * 650 * The input seed is taken as a flat buffer and the generated key is 651 * returned to caller in a flat destination data buffer. 652 * 653 * @context 654 * When called as an asynchronous function it cannot sleep. It can be 655 * executed in a context that does not permit sleeping. 656 * When called as a synchronous function it may sleep. It MUST NOT be 657 * executed in a context that DOES NOT permit sleeping. 658 * @assumptions 659 * None 660 * @sideEffects 661 * None 662 * @blocking 663 * Yes when configured to operate in synchronous mode. 664 * @reentrant 665 * No 666 * @threadSafe 667 * Yes 668 * 669 * @param[in] instanceHandle Instance handle. 670 * @param[in] pKeyGenCb Pointer to callback function to be 671 * invoked when the operation is complete. 672 * If this is set to a NULL value the 673 * function will operate synchronously. 674 * @param[in] pCallbackTag Opaque User Data for this specific 675 * call. Will be returned unchanged in the 676 * callback. 677 * @param[in] pKeyGenTlsOpData Structure containing all the data 678 * needed to perform the TLS key 679 * generation operation. The client code 680 * allocates the memory for this 681 * structure. This component takes 682 * ownership of the memory until it is 683 * returned in the callback. 684 * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient 685 * buffer to hold the key generation 686 * output. The data pointer SHOULD be 687 * aligned on an 8-byte boundary. The 688 * length field passed in represents the 689 * size of the buffer in bytes. The value 690 * that is returned is the size of the 691 * result key in bytes. 692 * On invocation the callback function 693 * will contain this parameter in the 694 * pOut parameter. 695 * 696 * @retval CPA_STATUS_SUCCESS Function executed successfully. 697 * @retval CPA_STATUS_FAIL Function failed. 698 * @retval CPA_STATUS_RETRY Resubmit the request. 699 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 700 * @retval CPA_STATUS_RESOURCE Error related to system resources. 701 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 702 * Resubmit the request. 703 * 704 * @pre 705 * The component has been initialized via cpaCyStartInstance function. 706 * @post 707 * None 708 * @see 709 * CpaCyKeyGenTlsOpData, 710 * CpaCyGenFlatBufCbFunc 711 * 712 *****************************************************************************/ 713 CpaStatus 714 cpaCyKeyGenTls(const CpaInstanceHandle instanceHandle, 715 const CpaCyGenFlatBufCbFunc pKeyGenCb, 716 void *pCallbackTag, 717 const CpaCyKeyGenTlsOpData *pKeyGenTlsOpData, 718 CpaFlatBuffer *pGeneratedKeyBuffer); 719 720 /** 721 ***************************************************************************** 722 * @ingroup cpaCyKeyGen 723 * TLS Key Generation Function version 2. 724 * @description 725 * This function is used for TLS key generation. It implements the 726 * TLS PRF (Pseudo Random Function) as defined by RFC5246 (TLS v1.2). 727 * 728 * The input seed is taken as a flat buffer and the generated key is 729 * returned to caller in a flat destination data buffer. 730 * 731 * @context 732 * When called as an asynchronous function it cannot sleep. It can be 733 * executed in a context that does not permit sleeping. 734 * When called as a synchronous function it may sleep. It MUST NOT be 735 * executed in a context that DOES NOT permit sleeping. 736 * @assumptions 737 * None 738 * @sideEffects 739 * None 740 * @blocking 741 * Yes when configured to operate in synchronous mode. 742 * @reentrant 743 * No 744 * @threadSafe 745 * Yes 746 * 747 * @param[in] instanceHandle Instance handle. 748 * @param[in] pKeyGenCb Pointer to callback function to be 749 * invoked when the operation is complete. 750 * If this is set to a NULL value the 751 * function will operate synchronously. 752 * @param[in] pCallbackTag Opaque User Data for this specific 753 * call. Will be returned unchanged in the 754 * callback. 755 * @param[in] pKeyGenTlsOpData Structure containing all the data 756 * needed to perform the TLS key 757 * generation operation. The client code 758 * allocates the memory for this 759 * structure. This component takes 760 * ownership of the memory until it is 761 * returned in the callback. 762 * @param[in] hashAlgorithm Specifies the hash algorithm to use. 763 * According to RFC5246, this should be 764 * "SHA-256 or a stronger standard hash 765 * function." 766 * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient 767 * buffer to hold the key generation 768 * output. The data pointer SHOULD be 769 * aligned on an 8-byte boundary. The 770 * length field passed in represents the 771 * size of the buffer in bytes. The value 772 * that is returned is the size of the 773 * result key in bytes. 774 * On invocation the callback function 775 * will contain this parameter in the 776 * pOut parameter. 777 * 778 * @retval CPA_STATUS_SUCCESS Function executed successfully. 779 * @retval CPA_STATUS_FAIL Function failed. 780 * @retval CPA_STATUS_RETRY Resubmit the request. 781 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 782 * @retval CPA_STATUS_RESOURCE Error related to system resources. 783 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 784 * Resubmit the request. 785 * 786 * @pre 787 * The component has been initialized via cpaCyStartInstance function. 788 * @post 789 * None 790 * @see 791 * CpaCyKeyGenTlsOpData, 792 * CpaCyGenFlatBufCbFunc 793 * 794 *****************************************************************************/ 795 CpaStatus 796 cpaCyKeyGenTls2(const CpaInstanceHandle instanceHandle, 797 const CpaCyGenFlatBufCbFunc pKeyGenCb, 798 void *pCallbackTag, 799 const CpaCyKeyGenTlsOpData *pKeyGenTlsOpData, 800 CpaCySymHashAlgorithm hashAlgorithm, 801 CpaFlatBuffer *pGeneratedKeyBuffer); 802 803 804 /** 805 ***************************************************************************** 806 * @ingroup cpaCyKeyGen 807 * TLS Key Generation Function version 3. 808 * @description 809 * This function is used for TLS key generation. It implements the 810 * TLS HKDF (HMAC Key Derivation Function) as defined by 811 * RFC5689 (HKDF) and RFC8446 (TLS 1.3). 812 * 813 * The input seed is taken as a flat buffer and the generated key is 814 * returned to caller in a flat destination data buffer. 815 * 816 * @context 817 * When called as an asynchronous function it cannot sleep. It can be 818 * executed in a context that does not permit sleeping. 819 * When called as a synchronous function it may sleep. It MUST NOT be 820 * executed in a context that DOES NOT permit sleeping. 821 * @assumptions 822 * None 823 * @sideEffects 824 * None 825 * @blocking 826 * Yes when configured to operate in synchronous mode. 827 * @reentrant 828 * No 829 * @threadSafe 830 * Yes 831 * 832 * @param[in] instanceHandle Instance handle. 833 * @param[in] pKeyGenCb Pointer to callback function to be 834 * invoked when the operation is complete. 835 * If this is set to a NULL value the 836 * function will operate synchronously. 837 * @param[in] pCallbackTag Opaque User Data for this specific 838 * call. Will be returned unchanged in the 839 * callback. 840 * @param[in] pKeyGenTlsOpData Structure containing all the data 841 * needed to perform the TLS key 842 * generation operation. The client code 843 * allocates the memory for this 844 * structure. This component takes 845 * ownership of the memory until it is 846 * returned in the callback. The memory 847 * must be pinned and contiguous, suitable 848 * for DMA operations. 849 * @param[in] hashAlgorithm Specifies the hash algorithm to use. 850 * According to RFC5246, this should be 851 * "SHA-256 or a stronger standard hash 852 * function." 853 * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient 854 * buffer to hold the key generation 855 * output. The data pointer SHOULD be 856 * aligned on an 8-byte boundary. The 857 * length field passed in represents the 858 * size of the buffer in bytes. The value 859 * that is returned is the size of the 860 * result key in bytes. 861 * On invocation the callback function 862 * will contain this parameter in the 863 * pOut parameter. 864 * 865 * @retval CPA_STATUS_SUCCESS Function executed successfully. 866 * @retval CPA_STATUS_FAIL Function failed. 867 * @retval CPA_STATUS_RETRY Resubmit the request. 868 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 869 * @retval CPA_STATUS_RESOURCE Error related to system resources. 870 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 871 * Resubmit the request. 872 * 873 * @pre 874 * The component has been initialized via cpaCyStartInstance function. 875 * @post 876 * None 877 * @see 878 * CpaCyGenFlatBufCbFunc 879 * CpaCyKeyGenHKDFOpData 880 * 881 *****************************************************************************/ 882 CpaStatus 883 cpaCyKeyGenTls3(const CpaInstanceHandle instanceHandle, 884 const CpaCyGenFlatBufCbFunc pKeyGenCb, 885 void *pCallbackTag, 886 const CpaCyKeyGenHKDFOpData *pKeyGenTlsOpData, 887 CpaCyKeyHKDFCipherSuite cipherSuite, 888 CpaFlatBuffer *pGeneratedKeyBuffer); 889 890 891 /** 892 ***************************************************************************** 893 * @ingroup cpaCyKeyGen 894 * Mask Generation Function. 895 * @description 896 * This function implements the mask generation function MGF1 as 897 * defined by PKCS#1 v2.1, and RFC3447. The input seed is taken 898 * as a flat buffer and the generated mask is returned to caller in a 899 * flat destination data buffer. 900 * 901 * @note The default hash algorithm used by the MGF is SHA-1. If a 902 * different hash algorithm is preferred, then see the "extended" 903 * version of this function, @ref cpaCyKeyGenMgfExt. 904 * 905 * @context 906 * When called as an asynchronous function it cannot sleep. It can be 907 * executed in a context that does not permit sleeping. 908 * When called as a synchronous function it may sleep. It MUST NOT be 909 * executed in a context that DOES NOT permit sleeping. 910 * @assumptions 911 * None 912 * @sideEffects 913 * None 914 * @blocking 915 * Yes when configured to operate in synchronous mode. 916 * @reentrant 917 * No 918 * @threadSafe 919 * Yes 920 * 921 * @param[in] instanceHandle Instance handle. 922 * @param[in] pKeyGenCb Pointer to callback function to be 923 * invoked when the operation is complete. 924 * If this is set to a NULL value the 925 * function will operate synchronously. 926 * @param[in] pCallbackTag Opaque User Data for this specific call. 927 * Will be returned unchanged in the 928 * callback. 929 * @param[in] pKeyGenMgfOpData Structure containing all the data needed 930 * to perform the MGF key generation 931 * operation. The client code allocates the 932 * memory for this structure. This 933 * component takes ownership of the memory 934 * until it is returned in the callback. 935 * @param[out] pGeneratedMaskBuffer Caller MUST allocate a sufficient buffer 936 * to hold the generated mask. The data 937 * pointer SHOULD be aligned on an 8-byte 938 * boundary. The length field passed in 939 * represents the size of the buffer in 940 * bytes. The value that is returned is the 941 * size of the generated mask in bytes. 942 * On invocation the callback function 943 * will contain this parameter in the 944 * pOut parameter. 945 * 946 * @retval CPA_STATUS_SUCCESS Function executed successfully. 947 * @retval CPA_STATUS_FAIL Function failed. 948 * @retval CPA_STATUS_RETRY Resubmit the request. 949 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 950 * @retval CPA_STATUS_RESOURCE Error related to system resources. 951 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 952 * Resubmit the request. 953 * 954 * @pre 955 * The component has been initialized via cpaCyStartInstance function. 956 * @post 957 * None 958 * @see 959 * CpaCyKeyGenMgfOpData, 960 * CpaCyGenFlatBufCbFunc 961 * 962 *****************************************************************************/ 963 CpaStatus 964 cpaCyKeyGenMgf(const CpaInstanceHandle instanceHandle, 965 const CpaCyGenFlatBufCbFunc pKeyGenCb, 966 void *pCallbackTag, 967 const CpaCyKeyGenMgfOpData *pKeyGenMgfOpData, 968 CpaFlatBuffer *pGeneratedMaskBuffer); 969 970 /** 971 ***************************************************************************** 972 * @ingroup cpaCyKeyGen 973 * Extended Mask Generation Function. 974 * @description 975 * This function is used for mask generation. It differs from the "base" 976 * version of the function (@ref cpaCyKeyGenMgf) in that it allows 977 * the hash function used by the Mask Generation Function to be 978 * specified. 979 * 980 * @context 981 * When called as an asynchronous function it cannot sleep. It can be 982 * executed in a context that does not permit sleeping. 983 * When called as a synchronous function it may sleep. It MUST NOT be 984 * executed in a context that DOES NOT permit sleeping. 985 * @assumptions 986 * None 987 * @sideEffects 988 * None 989 * @blocking 990 * Yes when configured to operate in synchronous mode. 991 * @reentrant 992 * No 993 * @threadSafe 994 * Yes 995 * 996 * @param[in] instanceHandle Instance handle. 997 * @param[in] pKeyGenCb Pointer to callback function to be 998 * invoked when the operation is complete. 999 * If this is set to a NULL value the 1000 * function will operate synchronously. 1001 * @param[in] pCallbackTag Opaque User Data for this specific call. 1002 * Will be returned unchanged in the 1003 * callback. 1004 * @param[in] pKeyGenMgfOpDataExt Structure containing all the data needed 1005 * to perform the extended MGF key generation 1006 * operation. The client code allocates the 1007 * memory for this structure. This 1008 * component takes ownership of the memory 1009 * until it is returned in the callback. 1010 * @param[out] pGeneratedMaskBuffer Caller MUST allocate a sufficient buffer 1011 * to hold the generated mask. The data 1012 * pointer SHOULD be aligned on an 8-byte 1013 * boundary. The length field passed in 1014 * represents the size of the buffer in 1015 * bytes. The value that is returned is the 1016 * size of the generated mask in bytes. 1017 * On invocation the callback function 1018 * will contain this parameter in the 1019 * pOut parameter. 1020 * 1021 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1022 * @retval CPA_STATUS_FAIL Function failed. 1023 * @retval CPA_STATUS_RETRY Resubmit the request. 1024 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1025 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1026 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 1027 * Resubmit the request. 1028 * 1029 * @pre 1030 * The component has been initialized via cpaCyStartInstance function. 1031 * @post 1032 * None 1033 * @note 1034 * This function is only used to generate a mask keys from seed 1035 * material. 1036 * @see 1037 * CpaCyKeyGenMgfOpData, 1038 * CpaCyGenFlatBufCbFunc 1039 * 1040 *****************************************************************************/ 1041 CpaStatus 1042 cpaCyKeyGenMgfExt(const CpaInstanceHandle instanceHandle, 1043 const CpaCyGenFlatBufCbFunc pKeyGenCb, 1044 void *pCallbackTag, 1045 const CpaCyKeyGenMgfOpDataExt *pKeyGenMgfOpDataExt, 1046 CpaFlatBuffer *pGeneratedMaskBuffer); 1047 1048 /** 1049 ***************************************************************************** 1050 * @ingroup cpaCyKeyGen 1051 * Queries the Key and Mask generation statistics specific to 1052 * an instance. 1053 * 1054 * @deprecated 1055 * As of v1.3 of the Crypto API, this function has been deprecated, 1056 * replaced by @ref cpaCyKeyGenQueryStats64(). 1057 * 1058 * @description 1059 * This function will query a specific instance for key and mask 1060 * generation statistics. The user MUST allocate the CpaCyKeyGenStats 1061 * structure and pass the reference to that into this function call. This 1062 * function will write the statistic results into the passed in 1063 * CpaCyKeyGenStats structure. 1064 * 1065 * Note: statistics returned by this function do not interrupt current data 1066 * processing and as such can be slightly out of sync with operations that 1067 * are in progress during the statistics retrieval process. 1068 * 1069 * @context 1070 * This is a synchronous function and it can sleep. It MUST NOT be 1071 * executed in a context that DOES NOT permit sleeping. 1072 * @assumptions 1073 * None 1074 * @sideEffects 1075 * None 1076 * @blocking 1077 * This function is synchronous and blocking. 1078 * @reentrant 1079 * No 1080 * @threadSafe 1081 * Yes 1082 * 1083 * @param[in] instanceHandle Instance handle. 1084 * @param[out] pKeyGenStats Pointer to memory into which the statistics 1085 * will be written. 1086 * 1087 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1088 * @retval CPA_STATUS_FAIL Function failed. 1089 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1090 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1091 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 1092 * Resubmit the request. 1093 * 1094 * @pre 1095 * Component has been initialized. 1096 * @post 1097 * None 1098 * @note 1099 * This function operates in a synchronous manner and no asynchronous 1100 * callback will be generated. 1101 * 1102 * @see 1103 * CpaCyKeyGenStats 1104 * 1105 *****************************************************************************/ 1106 CpaStatus CPA_DEPRECATED 1107 cpaCyKeyGenQueryStats(const CpaInstanceHandle instanceHandle, 1108 struct _CpaCyKeyGenStats *pKeyGenStats); 1109 1110 /** 1111 ***************************************************************************** 1112 * @ingroup cpaCyKeyGen 1113 * Queries the Key and Mask generation statistics (64-bit version) 1114 * specific to an instance. 1115 * 1116 * @description 1117 * This function will query a specific instance for key and mask 1118 * generation statistics. The user MUST allocate the CpaCyKeyGenStats64 1119 * structure and pass the reference to that into this function call. This 1120 * function will write the statistic results into the passed in 1121 * CpaCyKeyGenStats64 structure. 1122 * 1123 * Note: statistics returned by this function do not interrupt current data 1124 * processing and as such can be slightly out of sync with operations that 1125 * are in progress during the statistics retrieval process. 1126 * 1127 * @context 1128 * This is a synchronous function and it can sleep. It MUST NOT be 1129 * executed in a context that DOES NOT permit sleeping. 1130 * @assumptions 1131 * None 1132 * @sideEffects 1133 * None 1134 * @blocking 1135 * This function is synchronous and blocking. 1136 * @reentrant 1137 * No 1138 * @threadSafe 1139 * Yes 1140 * 1141 * @param[in] instanceHandle Instance handle. 1142 * @param[out] pKeyGenStats Pointer to memory into which the statistics 1143 * will be written. 1144 * 1145 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1146 * @retval CPA_STATUS_FAIL Function failed. 1147 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1148 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1149 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 1150 * Resubmit the request. 1151 * 1152 * @pre 1153 * Component has been initialized. 1154 * @post 1155 * None 1156 * @note 1157 * This function operates in a synchronous manner and no asynchronous 1158 * callback will be generated. 1159 * 1160 * @see 1161 * CpaCyKeyGenStats64 1162 *****************************************************************************/ 1163 CpaStatus 1164 cpaCyKeyGenQueryStats64(const CpaInstanceHandle instanceHandle, 1165 CpaCyKeyGenStats64 *pKeyGenStats); 1166 1167 #ifdef __cplusplus 1168 } /* close the extern "C" { */ 1169 #endif 1170 1171 #endif /* CPA_CY_KEY_H */ 1172