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_dh.h 12 * 13 * @defgroup cpaCyDh Diffie-Hellman (DH) API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the API for Public Key Encryption 19 * (Cryptography) operations for use with Diffie-Hellman algorithm. 20 * 21 * @note 22 * Large numbers are represented on the QuickAssist API as described 23 * in the Large Number API (@ref cpaCyLn). 24 *****************************************************************************/ 25 26 #ifndef CPA_CY_DH_H 27 #define CPA_CY_DH_H 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #include "cpa_cy_common.h" 34 /** 35 ***************************************************************************** 36 * @ingroup cpaCyDh 37 * Diffie-Hellman Phase 1 Key Generation Data. 38 * @description 39 * This structure lists the different items that are required in the 40 * cpaCyDhKeyGenPhase1 function. The client MUST allocate the memory for 41 * this structure. When the structure is passed into the function, 42 * ownership of the memory passes to the function. Ownership of the memory 43 * returns to the client when this structure is returned with the 44 * CpaCyDhPhase1KeyGenOpData structure. 45 * 46 * @note 47 * If the client modifies or frees the memory referenced in this structure 48 * after it has been submitted to the cpaCyDhKeyGenPhase1 function, and 49 * before it has been returned in the callback, undefined behavior will 50 * result. 51 * All values in this structure are required to be in Most Significant Byte 52 * first order, e.g. primeP.pData[0] = MSB. 53 * 54 *****************************************************************************/ 55 typedef struct _CpaCyDhPhase1KeyGenOpData { 56 CpaFlatBuffer primeP; 57 /**< Flat buffer containing a pointer to the random odd prime number (p). 58 * The bit-length of this number may be one of 768, 1024, 1536, 2048, 59 * 3072, 4096 or 8192. 60 */ 61 CpaFlatBuffer baseG; 62 /**< Flat buffer containing a pointer to base (g). This MUST comply with 63 * the following: 64 * 0 < g < p. 65 */ 66 CpaFlatBuffer privateValueX; 67 /**< Flat buffer containing a pointer to the private value (x). This is a 68 * random value which MUST satisfy the following condition: 69 * 0 < PrivateValueX < (PrimeP - 1) 70 * 71 * Refer to PKCS #3: Diffie-Hellman Key-Agreement Standard for details. 72 * The client creating this data MUST ensure the compliance of this value 73 * with the standard. Note: This value is also needed to complete local 74 * phase 2 Diffie-Hellman operation.*/ 75 } CpaCyDhPhase1KeyGenOpData; 76 77 /** 78 ***************************************************************************** 79 * @ingroup cpaCyDh 80 * Diffie-Hellman Phase 2 Secret Key Generation Data. 81 * @description 82 * This structure lists the different items that required in the 83 * cpaCyDhKeyGenPhase2Secret function. The client MUST allocate the 84 * memory for this structure. When the structure is passed into the 85 * function, ownership of the memory passes to the function. Ownership of 86 * the memory returns to the client when this structure is returned with 87 * the callback. 88 * @note 89 * If the client modifies or frees the memory referenced in this structure 90 * after it has been submitted to the cpaCyDhKeyGenPhase2Secret 91 * function, and before it has been returned in the callback, undefined 92 * behavior will result. 93 * All values in this structure are required to be in Most Significant Byte 94 * first order, e.g. primeP.pData[0] = MSB. 95 * 96 *****************************************************************************/ 97 typedef struct _CpaCyDhPhase2SecretKeyGenOpData { 98 CpaFlatBuffer primeP; 99 /**< Flat buffer containing a pointer to the random odd prime number (p). 100 * The bit-length of this number may be one of 768, 1024, 1536, 2048, 101 * 3072, 4096 or 8192. 102 * This SHOULD be same prime number as was used in the phase 1 key 103 * generation operation. */ 104 CpaFlatBuffer remoteOctetStringPV; 105 /**< Flat buffer containing a pointer to the remote entity 106 * octet string Public Value (PV). */ 107 CpaFlatBuffer privateValueX; 108 /**< Flat buffer containing a pointer to the private value (x). This 109 * value may have been used in a call to the cpaCyDhKeyGenPhase1 function. 110 * This is a random value which MUST satisfy the following condition: 111 * 0 < privateValueX < (primeP - 1). */ 112 } CpaCyDhPhase2SecretKeyGenOpData; 113 114 /** 115 ***************************************************************************** 116 * @ingroup cpaCyDh 117 * Diffie-Hellman Statistics. 118 * @deprecated 119 * As of v1.3 of the Crypto API, this structure has been deprecated, 120 * replaced by @ref CpaCyDhStats64. 121 * @description 122 * This structure contains statistics on the Diffie-Hellman operations. 123 * Statistics are set to zero when the component is initialized, and are 124 * collected per instance. 125 ****************************************************************************/ 126 typedef struct _CpaCyDhStats { 127 Cpa32U numDhPhase1KeyGenRequests; 128 /**< Total number of successful Diffie-Hellman phase 1 key 129 * generation requests. */ 130 Cpa32U numDhPhase1KeyGenRequestErrors; 131 /**< Total number of Diffie-Hellman phase 1 key generation requests 132 * that had an error and could not be processed. */ 133 Cpa32U numDhPhase1KeyGenCompleted; 134 /**< Total number of Diffie-Hellman phase 1 key generation operations 135 * that completed successfully. */ 136 Cpa32U numDhPhase1KeyGenCompletedErrors; 137 /**< Total number of Diffie-Hellman phase 1 key generation operations 138 * that could not be completed successfully due to errors. */ 139 Cpa32U numDhPhase2KeyGenRequests; 140 /**< Total number of successful Diffie-Hellman phase 2 key 141 * generation requests. */ 142 Cpa32U numDhPhase2KeyGenRequestErrors; 143 /**< Total number of Diffie-Hellman phase 2 key generation requests 144 * that had an error and could not be processed. */ 145 Cpa32U numDhPhase2KeyGenCompleted; 146 /**< Total number of Diffie-Hellman phase 2 key generation operations 147 * that completed successfully. */ 148 Cpa32U numDhPhase2KeyGenCompletedErrors; 149 /**< Total number of Diffie-Hellman phase 2 key generation operations 150 * that could not be completed successfully due to errors. */ 151 } CpaCyDhStats CPA_DEPRECATED; 152 153 /** 154 ***************************************************************************** 155 * @ingroup cpaCyDh 156 * Diffie-Hellman Statistics (64-bit version). 157 * @description 158 * This structure contains the 64-bit version of the statistics on the 159 * Diffie-Hellman operations. 160 * Statistics are set to zero when the component is initialized, and are 161 * collected per instance. 162 ****************************************************************************/ 163 typedef struct _CpaCyDhStats64 { 164 Cpa64U numDhPhase1KeyGenRequests; 165 /**< Total number of successful Diffie-Hellman phase 1 key 166 * generation requests. */ 167 Cpa64U numDhPhase1KeyGenRequestErrors; 168 /**< Total number of Diffie-Hellman phase 1 key generation requests 169 * that had an error and could not be processed. */ 170 Cpa64U numDhPhase1KeyGenCompleted; 171 /**< Total number of Diffie-Hellman phase 1 key generation operations 172 * that completed successfully. */ 173 Cpa64U numDhPhase1KeyGenCompletedErrors; 174 /**< Total number of Diffie-Hellman phase 1 key generation operations 175 * that could not be completed successfully due to errors. */ 176 Cpa64U numDhPhase2KeyGenRequests; 177 /**< Total number of successful Diffie-Hellman phase 2 key 178 * generation requests. */ 179 Cpa64U numDhPhase2KeyGenRequestErrors; 180 /**< Total number of Diffie-Hellman phase 2 key generation requests 181 * that had an error and could not be processed. */ 182 Cpa64U numDhPhase2KeyGenCompleted; 183 /**< Total number of Diffie-Hellman phase 2 key generation operations 184 * that completed successfully. */ 185 Cpa64U numDhPhase2KeyGenCompletedErrors; 186 /**< Total number of Diffie-Hellman phase 2 key generation operations 187 * that could not be completed successfully due to errors. */ 188 } CpaCyDhStats64; 189 190 /** 191 ***************************************************************************** 192 * @ingroup cpaCyDh 193 * Function to implement Diffie-Hellman phase 1 operations. 194 * 195 * @description 196 * This function may be used to implement the Diffie-Hellman phase 1 197 * operations as defined in the PKCS #3 standard. It may be used to 198 * generate the (local) octet string public value (PV) key. 199 * The prime number sizes specified in RFC 2409, 4306, and part of 200 * RFC 3526 are supported (bit size 6144 from RFC 3536 is not 201 * supported). 202 * 203 * @context 204 * When called as an asynchronous function it cannot sleep. It can be 205 * executed in a context that does not permit sleeping. 206 * When called as a synchronous function it may sleep. It MUST NOT be 207 * executed in a context that DOES NOT permit sleeping. 208 * @assumptions 209 * None 210 * @sideEffects 211 * None 212 * @blocking 213 * Yes when configured to operate in synchronous mode. 214 * @reentrant 215 * No 216 * @threadSafe 217 * Yes 218 * 219 * @param[in] instanceHandle Instance handle. 220 * @param[in] pDhPhase1Cb Pointer to a callback function to be invoked 221 * when the operation is complete. If the 222 * pointer is set to a NULL value the function 223 * will operate synchronously. 224 * @param[in] pCallbackTag Opaque User Data for this specific call. 225 * Will be returned unchanged in the callback 226 * @param[in] pPhase1KeyGenData Structure containing all the data needed 227 * to perform the DH Phase 1 key generation 228 * operation. The client code allocates the 229 * memory for this structure. This component 230 * takes ownership of the memory until it is 231 * returned in the callback. 232 * @param[out] pLocalOctetStringPV Pointer to memory allocated by the client 233 * into which the (local) octet string Public 234 * Value (PV) will be written. This value 235 * needs to be sent to the remote entity with 236 * which Diffie-Hellman is negotiating. 237 * The size of this buffer in bytes (as 238 * represented by the dataLenInBytes field) 239 * MUST be at least big enough to store 240 * the public value, which may have a bit 241 * length up to that of pPrimeP. 242 * On invocation the callback function 243 * will contain this parameter in the 244 * pOut parameter. 245 * 246 * @retval CPA_STATUS_SUCCESS Function executed successfully. 247 * @retval CPA_STATUS_FAIL Function failed. 248 * @retval CPA_STATUS_RETRY Resubmit the request. 249 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 250 * @retval CPA_STATUS_RESOURCE Error related to system resources. 251 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 252 * the request. 253 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 254 * 255 * @pre 256 * The component has been initialized via cpaCyStartInstance function. 257 * @post 258 * None 259 * @note 260 * When pDhPhase1Cb is non-NULL an asynchronous callback of type 261 * CpaCyGenFlatBufCbFunc is generated in response to this function 262 * call. Any errors generated during processing are reported in the 263 * structure returned in the callback. 264 * 265 * @see 266 * CpaCyGenFlatBufCbFunc, 267 * CpaCyDhPhase1KeyGenOpData 268 * 269 *****************************************************************************/ 270 CpaStatus 271 cpaCyDhKeyGenPhase1(const CpaInstanceHandle instanceHandle, 272 const CpaCyGenFlatBufCbFunc pDhPhase1Cb, 273 void *pCallbackTag, 274 const CpaCyDhPhase1KeyGenOpData *pPhase1KeyGenData, 275 CpaFlatBuffer *pLocalOctetStringPV); 276 277 /** 278 ***************************************************************************** 279 * @ingroup cpaCyDh 280 * Function to implement Diffie-Hellman phase 2 operations. 281 * 282 * @description 283 * This function may be used to implement the Diffie-Hellman phase 2 284 * operation as defined in the PKCS #3 standard. It may be used to 285 * generate the Diffie-Hellman shared secret key. 286 * 287 * @context 288 * When called as an asynchronous function it cannot sleep. It can be 289 * executed in a context that does not permit sleeping. 290 * When called as a synchronous function it may sleep. It MUST NOT be 291 * executed in a context that DOES NOT permit sleeping. 292 * @assumptions 293 * None 294 * @sideEffects 295 * None 296 * @blocking 297 * Yes when configured to operate in synchronous mode. 298 * @reentrant 299 * No 300 * @threadSafe 301 * Yes 302 * 303 * @param[in] instanceHandle Instance handle. 304 * @param[in] pDhPhase2Cb Pointer to a callback function to be 305 * invoked when the operation is complete. 306 * If the pointer is set to a NULL value 307 * the function will operate synchronously. 308 * @param[in] pCallbackTag Opaque User Data for this specific 309 * call. Will be returned unchanged in 310 * the callback. 311 * @param[in] pPhase2SecretKeyGenData Structure containing all the data 312 * needed to perform the DH Phase 2 313 * secret key generation operation. The 314 * client code allocates the memory for 315 * this structure. This component takes 316 * ownership of the memory until it is 317 * returned in the callback. 318 * @param[out] pOctetStringSecretKey Pointer to memory allocated by the 319 * client into which the octet string 320 * secret key will be written. 321 * The size of this buffer in bytes (as 322 * represented by the dataLenInBytes field) 323 * MUST be at least big enough to store 324 * the public value, which may have a bit 325 * length up to that of pPrimeP. 326 * On invocation the callback function 327 * will contain this parameter in the 328 * pOut parameter. 329 * 330 * @retval CPA_STATUS_SUCCESS Function executed successfully. 331 * @retval CPA_STATUS_FAIL Function failed. 332 * @retval CPA_STATUS_RETRY Resubmit the request. 333 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 334 * @retval CPA_STATUS_RESOURCE Error related to system resources. 335 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 336 * the request. 337 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 338 * 339 * @pre 340 * The component has been initialized via cpaCyStartInstance function. 341 * @post 342 * None 343 * @note 344 * When pDhPhase2Cb is non-NULL an asynchronous callback of type 345 * CpaCyGenFlatBufCbFunc is generated in response to this function 346 * call. Any errors generated during processing are reported in the 347 * structure returned in the callback. 348 * 349 * @see 350 * CpaCyGenFlatBufCbFunc, 351 * CpaCyDhPhase2SecretKeyGenOpData 352 * 353 *****************************************************************************/ 354 CpaStatus 355 cpaCyDhKeyGenPhase2Secret(const CpaInstanceHandle instanceHandle, 356 const CpaCyGenFlatBufCbFunc pDhPhase2Cb, 357 void *pCallbackTag, 358 const CpaCyDhPhase2SecretKeyGenOpData *pPhase2SecretKeyGenData, 359 CpaFlatBuffer *pOctetStringSecretKey); 360 361 /** 362 ***************************************************************************** 363 * @ingroup cpaCyDh 364 * Query statistics for Diffie-Hellman operations 365 * 366 * @deprecated 367 * As of v1.3 of the Crypto API, this function has been deprecated, 368 * replaced by @ref cpaCyDhQueryStats64(). 369 * 370 * @description 371 * This function will query a specific Instance handle for Diffie- 372 * Hellman statistics. The user MUST allocate the CpaCyDhStats 373 * structure and pass the reference to that structure into this function 374 * call. This function writes the statistic results into the passed in 375 * CpaCyDhStats structure. 376 * 377 * Note: statistics returned by this function do not interrupt current data 378 * processing and as such can be slightly out of sync with operations that 379 * are in progress during the statistics retrieval process. 380 * 381 * @context 382 * This is a synchronous function and it can sleep. It MUST NOT be 383 * executed in a context that DOES NOT permit sleeping. 384 * @assumptions 385 * None 386 * @sideEffects 387 * None 388 * @reentrant 389 * No 390 * @threadSafe 391 * Yes 392 * 393 * @param[in] instanceHandle Instance handle. 394 * @param[out] pDhStats Pointer to memory into which the statistics 395 * will be written. 396 * 397 * @retval CPA_STATUS_SUCCESS Function executed successfully. 398 * @retval CPA_STATUS_FAIL Function failed. 399 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 400 * @retval CPA_STATUS_RESOURCE Error related to system resources. 401 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 402 * the request. 403 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 404 * 405 * @pre 406 * Component has been initialized. 407 * 408 * @post 409 * None 410 * @note 411 * This function operates in a synchronous manner and no asynchronous 412 * callback will be generated. 413 * @see 414 * CpaCyDhStats 415 *****************************************************************************/ 416 CpaStatus CPA_DEPRECATED 417 cpaCyDhQueryStats(const CpaInstanceHandle instanceHandle, 418 struct _CpaCyDhStats *pDhStats); 419 420 /** 421 ***************************************************************************** 422 * @ingroup cpaCyDh 423 * Query statistics (64-bit version) for Diffie-Hellman operations 424 * 425 * @description 426 * This function will query a specific Instance handle for the 64-bit 427 * version of the Diffie-Hellman statistics. The user MUST allocate the 428 * CpaCyDhStats64 structure and pass the reference to that structure into 429 * this function call. This function writes the statistic results into 430 * the passed in CpaCyDhStats64 structure. 431 * 432 * Note: statistics returned by this function do not interrupt current data 433 * processing and as such can be slightly out of sync with operations that 434 * are in progress during the statistics retrieval process. 435 * 436 * @context 437 * This is a synchronous function and it can sleep. It MUST NOT be 438 * executed in a context that DOES NOT permit sleeping. 439 * @assumptions 440 * None 441 * @sideEffects 442 * None 443 * @reentrant 444 * No 445 * @threadSafe 446 * Yes 447 * 448 * @param[in] instanceHandle Instance handle. 449 * @param[out] pDhStats Pointer to memory into which the statistics 450 * will be written. 451 * 452 * @retval CPA_STATUS_SUCCESS Function executed successfully. 453 * @retval CPA_STATUS_FAIL Function failed. 454 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 455 * @retval CPA_STATUS_RESOURCE Error related to system resources. 456 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 457 * the request. 458 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 459 * 460 * @pre 461 * Component has been initialized. 462 * 463 * @post 464 * None 465 * @note 466 * This function operates in a synchronous manner and no asynchronous 467 * callback will be generated. 468 * @see 469 * CpaCyDhStats64 470 *****************************************************************************/ 471 CpaStatus 472 cpaCyDhQueryStats64(const CpaInstanceHandle instanceHandle, 473 CpaCyDhStats64 *pDhStats); 474 475 /*****************************************************************************/ 476 477 #ifdef __cplusplus 478 } /* close the extern "C" { */ 479 #endif 480 481 #endif /* CPA_CY_DH_H */ 482