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