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_rsa.h 45 * 46 * @defgroup cpaCyRsa RSA API 47 * 48 * @ingroup cpaCy 49 * 50 * @description 51 * These functions specify the API for Public Key Encryption 52 * (Cryptography) RSA operations. The PKCS #1 V2.1 specification is 53 * supported, however the support is limited to "two-prime" mode. RSA 54 * multi-prime is not supported. 55 * 56 * @note 57 * These functions implement RSA cryptographic primitives. RSA padding 58 * schemes are not implemented. For padding schemes that require the mgf 59 * function see @ref cpaCyKeyGen. 60 * 61 * @note 62 * Large numbers are represented on the QuickAssist API as described 63 * in the Large Number API (@ref cpaCyLn). 64 *****************************************************************************/ 65 66 #ifndef CPA_CY_RSA_H 67 #define CPA_CY_RSA_H 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 #include "cpa_cy_common.h" 74 75 /** 76 ***************************************************************************** 77 * @ingroup cpaCyRsa 78 * RSA Version. 79 * @description 80 * This enumeration lists the version identifier for the PKCS #1 V2.1 81 * standard. 82 * @note 83 * Multi-prime (more than two primes) is not supported. 84 * 85 *****************************************************************************/ 86 typedef enum _CpaCyRsaVersion 87 { 88 CPA_CY_RSA_VERSION_TWO_PRIME = 1 89 /**< The version supported is "two-prime". */ 90 } CpaCyRsaVersion; 91 92 /** 93 ***************************************************************************** 94 * @ingroup cpaCyRsa 95 * RSA Public Key Structure. 96 * @description 97 * This structure contains the two components which comprise the RSA 98 * public key as defined in the PKCS #1 V2.1 standard. 99 * All values in this structure are required to be in Most Significant Byte 100 * first order, e.g. modulusN.pData[0] = MSB. 101 * 102 *****************************************************************************/ 103 typedef struct _CpaCyRsaPublicKey { 104 CpaFlatBuffer modulusN; 105 /**< The modulus (n). 106 * For key generation operations, the client MUST allocate the memory 107 * for this parameter; its value is generated. 108 * For encrypt operations this parameter is an input. */ 109 CpaFlatBuffer publicExponentE; 110 /**< The public exponent (e). 111 * For key generation operations, this field is unused. It is NOT 112 * generated by the interface; it is the responsibility of the client 113 * to set this to the same value as the corresponding parameter on 114 * the CpaCyRsaKeyGenOpData structure before using the key for 115 * encryption. 116 * For encrypt operations this parameter is an input. */ 117 } CpaCyRsaPublicKey; 118 119 /** 120 ***************************************************************************** 121 * @ingroup cpaCyRsa 122 * RSA Private Key Structure For Representation 1. 123 * @description 124 * This structure contains the first representation that can be used for 125 * describing the RSA private key, represented by the tuple of the 126 * modulus (n) and the private exponent (d). 127 * All values in this structure are required to be in Most Significant Byte 128 * first order, e.g. modulusN.pData[0] = MSB. 129 * 130 *****************************************************************************/ 131 typedef struct _CpaCyRsaPrivateKeyRep1 { 132 CpaFlatBuffer modulusN; 133 /**< The modulus (n). For key generation operations the memory MUST 134 * be allocated by the client and the value is generated. For other 135 * operations this is an input. Permitted lengths are: 136 * 137 * - 512 bits (64 bytes), 138 * - 1024 bits (128 bytes), 139 * - 1536 bits (192 bytes), 140 * - 2048 bits (256 bytes), 141 * - 3072 bits (384 bytes), 142 * - 4096 bits (512 bytes), or 143 * - 8192 bits (1024 bytes). 144 */ 145 CpaFlatBuffer privateExponentD; 146 /**< The private exponent (d). For key generation operations the 147 * memory MUST be allocated by the client and the value is generated. For 148 * other operations this is an input. 149 * NOTE: It is important that the value D is big enough. It is STRONGLY 150 * recommended that this value is at least half the length of the modulus 151 * N to protect against the Wiener attack. */ 152 } CpaCyRsaPrivateKeyRep1; 153 154 /** 155 ***************************************************************************** 156 * @ingroup cpaCyRsa 157 * RSA Private Key Structure For Representation 2. 158 * @description 159 * This structure contains the second representation that can be used for 160 * describing the RSA private key. The quintuple of p, q, dP, dQ, and qInv 161 * (explained below and in the spec) are required for the second 162 * representation. The optional sequence of triplets are not included. 163 * All values in this structure are required to be in Most Significant Byte 164 * first order, e.g. prime1P.pData[0] = MSB. 165 * 166 *****************************************************************************/ 167 typedef struct _CpaCyRsaPrivateKeyRep2 { 168 CpaFlatBuffer prime1P; 169 /**< The first large prime (p). 170 * For key generation operations, this field is unused. */ 171 CpaFlatBuffer prime2Q; 172 /**< The second large prime (q). 173 * For key generation operations, this field is unused. */ 174 CpaFlatBuffer exponent1Dp; 175 /**< The first factor CRT exponent (dP). d mod (p-1). */ 176 CpaFlatBuffer exponent2Dq; 177 /**< The second factor CRT exponent (dQ). d mod (q-1). */ 178 CpaFlatBuffer coefficientQInv; 179 /**< The (first) Chinese Remainder Theorem (CRT) coefficient (qInv). 180 * (inverse of q) mod p. */ 181 } CpaCyRsaPrivateKeyRep2; 182 183 /** 184 ***************************************************************************** 185 * @ingroup cpaCyRsa 186 * RSA private key representation type. 187 * @description 188 * This enumeration lists which PKCS V2.1 representation of the private 189 * key is being used. 190 * 191 *****************************************************************************/ 192 typedef enum _CpaCyRsaPrivateKeyRepType 193 { 194 CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_1= 1, 195 /**< The first representation of the RSA private key. */ 196 CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_2 197 /**< The second representation of the RSA private key. */ 198 } CpaCyRsaPrivateKeyRepType; 199 200 /** 201 ***************************************************************************** 202 * @ingroup cpaCyRsa 203 * RSA Private Key Structure. 204 * @description 205 * This structure contains the two representations that can be used for 206 * describing the RSA private key. The privateKeyRepType will be used to 207 * identify which representation is to be used. Typically, using the 208 * second representation results in faster decryption operations. 209 * 210 *****************************************************************************/ 211 typedef struct _CpaCyRsaPrivateKey { 212 CpaCyRsaVersion version; 213 /**< Indicates the version of the PKCS #1 specification that is 214 * supported. 215 * Note that this applies to both representations. */ 216 CpaCyRsaPrivateKeyRepType privateKeyRepType; 217 /**< This value is used to identify which of the private key 218 * representation types in this structure is relevant. 219 * When performing key generation operations for Type 2 representations, 220 * memory must also be allocated for the type 1 representations, and values 221 * for both will be returned. */ 222 CpaCyRsaPrivateKeyRep1 privateKeyRep1; 223 /**< This is the first representation of the RSA private key as 224 * defined in the PKCS #1 V2.1 specification. For key generation operations 225 * the memory for this structure is allocated by the client and the 226 * specific values are generated. For other operations this is an input 227 * parameter. */ 228 CpaCyRsaPrivateKeyRep2 privateKeyRep2; 229 /**< This is the second representation of the RSA private key as 230 * defined in the PKCS #1 V2.1 specification. For key generation operations 231 * the memory for this structure is allocated by the client and the 232 * specific values are generated. For other operations this is an input 233 * parameter. */ 234 } CpaCyRsaPrivateKey; 235 236 /** 237 ***************************************************************************** 238 * @ingroup cpaCyRsa 239 * RSA Key Generation Data. 240 * @description 241 * This structure lists the different items that are required in the 242 * cpaCyRsaGenKey function. The client MUST allocate the memory for this 243 * structure. When the structure is passed into the function, ownership of 244 * the memory passes to the function. Ownership of the memory returns to 245 * the client when this structure is returned in the 246 * CpaCyRsaKeyGenCbFunc callback function. 247 * 248 * @note 249 * If the client modifies or frees the memory referenced in this structure 250 * after it has been submitted to the cpaCyRsaGenKey function, and 251 * before it has been returned in the callback, undefined behavior will 252 * result. 253 * All values in this structure are required to be in Most Significant Byte 254 * first order, e.g. prime1P.pData[0] = MSB. 255 * 256 * The following limitations on the permutations of the supported bit 257 * lengths of p, q and n (written as {p, q, n}) apply: 258 * 259 * - {256, 256, 512} or 260 * - {512, 512, 1024} or 261 * - {768, 768, 1536} or 262 * - {1024, 1024, 2048} or 263 * - {1536, 1536, 3072} or 264 * - {2048, 2048, 4096}. 265 * 266 *****************************************************************************/ 267 typedef struct _CpaCyRsaKeyGenOpData { 268 CpaFlatBuffer prime1P; 269 /**< A large random prime number (p). This MUST be created by the 270 * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048. 271 * Limitations apply - refer to the description above for details. */ 272 CpaFlatBuffer prime2Q; 273 /**< A large random prime number (q). This MUST be created by the 274 * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048. 275 * Limitations apply - refer to the description above for details. If the 276 * private key representation type is 2, then this pointer will be assigned 277 * to the relevant structure member of the representation 2 private key. */ 278 Cpa32U modulusLenInBytes; 279 /**< The bit length of the modulus (n). This is the modulus length for 280 * both the private and public keys. The length of the modulus N parameter 281 * for the private key representation 1 structure and the public key 282 * structures will be assigned to this value. References to the strength of 283 * RSA actually refer to this bit length. Recommended minimum is 1024 bits. 284 * Permitted lengths are: 285 * - 512 bits (64 bytes), 286 * - 1024 bits (128 bytes), 287 * - 1536 bits (192 bytes), 288 * - 2048 bits (256 bytes), 289 * - 3072 bits (384 bytes), or 290 * - 4096 bits (512 bytes). 291 * Limitations apply - refer to description above for details. */ 292 CpaCyRsaVersion version; 293 /**< Indicates the version of the PKCS #1 specification that is 294 * supported. 295 * Note that this applies to both representations. */ 296 CpaCyRsaPrivateKeyRepType privateKeyRepType; 297 /**< This value is used to identify which of the private key 298 * representation types is required to be generated. */ 299 CpaFlatBuffer publicExponentE; 300 /**< The public exponent (e). */ 301 } CpaCyRsaKeyGenOpData; 302 303 /** 304 ***************************************************************************** 305 * @ingroup cpaCyRsa 306 * RSA Encryption Primitive Operation Data 307 * @description 308 * This structure lists the different items that are required in the 309 * cpaCyRsaEncrypt function. As the RSA encryption primitive and 310 * verification primitive operations are mathematically identical this 311 * structure may also be used to perform an RSA verification primitive 312 * operation. 313 * When performing an RSA encryption primitive operation, the input data 314 * is the message and the output data is the cipher text. 315 * When performing an RSA verification primitive operation, the input data 316 * is the signature and the output data is the message. 317 * The client MUST allocate the memory for this structure. When the 318 * structure is passed into the function, ownership of the memory passes 319 * to the function. Ownership of the memory returns to the client when 320 * this structure is returned in the CpaCyRsaEncryptCbFunc 321 * callback function. 322 * 323 * @note 324 * If the client modifies or frees the memory referenced in this structure 325 * after it has been submitted to the cpaCyRsaEncrypt function, and 326 * before it has been returned in the callback, undefined behavior will 327 * result. 328 * All values in this structure are required to be in Most Significant Byte 329 * first order, e.g. inputData.pData[0] = MSB. 330 * 331 *****************************************************************************/ 332 typedef struct _CpaCyRsaEncryptOpData { 333 CpaCyRsaPublicKey *pPublicKey; 334 /**< Pointer to the public key. */ 335 CpaFlatBuffer inputData; 336 /**< The input data that the RSA encryption primitive operation is 337 * performed on. The data pointed to is an integer that MUST be in big- 338 * endian order. The value MUST be between 0 and the modulus n - 1. */ 339 } CpaCyRsaEncryptOpData; 340 341 /** 342 ***************************************************************************** 343 * @ingroup cpaCyRsa 344 * RSA Decryption Primitive Operation Data 345 * @description 346 * This structure lists the different items that are required in the 347 * cpaCyRsaDecrypt function. As the RSA decryption primitive and 348 * signature primitive operations are mathematically identical this 349 * structure may also be used to perform an RSA signature primitive 350 * operation. 351 * When performing an RSA decryption primitive operation, the input data 352 * is the cipher text and the output data is the message text. 353 * When performing an RSA signature primitive operation, the input data 354 * is the message and the output data is the signature. 355 * The client MUST allocate the memory for this structure. When the 356 * structure is passed into the function, ownership of the memory passes 357 * to he function. Ownership of the memory returns to the client when 358 * this structure is returned in the CpaCyRsaDecryptCbFunc 359 * callback function. 360 * 361 * @note 362 * If the client modifies or frees the memory referenced in this structure 363 * after it has been submitted to the cpaCyRsaDecrypt function, and 364 * before it has been returned in the callback, undefined behavior will 365 * result. 366 * All values in this structure are required to be in Most Significant Byte 367 * first order, e.g. inputData.pData[0] = MSB. 368 * 369 *****************************************************************************/ 370 typedef struct _CpaCyRsaDecryptOpData { 371 CpaCyRsaPrivateKey *pRecipientPrivateKey; 372 /**< Pointer to the recipient's RSA private key. */ 373 CpaFlatBuffer inputData; 374 /**< The input data that the RSA decryption primitive operation is 375 * performed on. The data pointed to is an integer that MUST be in big- 376 * endian order. The value MUST be between 0 and the modulus n - 1. */ 377 } CpaCyRsaDecryptOpData; 378 379 /** 380 ***************************************************************************** 381 * @ingroup cpaCyRsa 382 * RSA Statistics. 383 * @deprecated 384 * As of v1.3 of the Crypto API, this structure has been deprecated, 385 * replaced by @ref CpaCyRsaStats64. 386 * @description 387 * This structure contains statistics on the RSA operations. 388 * Statistics are set to zero when the component is initialized, and are 389 * collected per instance. 390 ****************************************************************************/ 391 typedef struct _CpaCyRsaStats { 392 Cpa32U numRsaKeyGenRequests; 393 /**< Total number of successful RSA key generation requests. */ 394 Cpa32U numRsaKeyGenRequestErrors; 395 /**< Total number of RSA key generation requests that had an error and 396 * could not be processed. */ 397 Cpa32U numRsaKeyGenCompleted; 398 /**< Total number of RSA key generation operations that completed 399 * successfully. */ 400 Cpa32U numRsaKeyGenCompletedErrors; 401 /**< Total number of RSA key generation operations that could not be 402 * completed successfully due to errors. */ 403 Cpa32U numRsaEncryptRequests; 404 /**< Total number of successful RSA encrypt operation requests. */ 405 Cpa32U numRsaEncryptRequestErrors; 406 /**< Total number of RSA encrypt requests that had an error and could 407 * not be processed. */ 408 Cpa32U numRsaEncryptCompleted; 409 /**< Total number of RSA encrypt operations that completed 410 * successfully. */ 411 Cpa32U numRsaEncryptCompletedErrors; 412 /**< Total number of RSA encrypt operations that could not be 413 * completed successfully due to errors. */ 414 Cpa32U numRsaDecryptRequests; 415 /**< Total number of successful RSA decrypt operation requests. */ 416 Cpa32U numRsaDecryptRequestErrors; 417 /**< Total number of RSA decrypt requests that had an error and could 418 * not be processed. */ 419 Cpa32U numRsaDecryptCompleted; 420 /**< Total number of RSA decrypt operations that completed 421 * successfully. */ 422 Cpa32U numRsaDecryptCompletedErrors; 423 /**< Total number of RSA decrypt operations that could not be 424 * completed successfully due to errors. */ 425 } CpaCyRsaStats CPA_DEPRECATED; 426 427 /** 428 ***************************************************************************** 429 * @ingroup cpaCyRsa 430 * RSA Statistics (64-bit version). 431 * @description 432 * This structure contains 64-bit version of the statistics on the RSA 433 * operations. 434 * Statistics are set to zero when the component is initialized, and are 435 * collected per instance. 436 ****************************************************************************/ 437 typedef struct _CpaCyRsaStats64 { 438 Cpa64U numRsaKeyGenRequests; 439 /**< Total number of successful RSA key generation requests. */ 440 Cpa64U numRsaKeyGenRequestErrors; 441 /**< Total number of RSA key generation requests that had an error and 442 * could not be processed. */ 443 Cpa64U numRsaKeyGenCompleted; 444 /**< Total number of RSA key generation operations that completed 445 * successfully. */ 446 Cpa64U numRsaKeyGenCompletedErrors; 447 /**< Total number of RSA key generation operations that could not be 448 * completed successfully due to errors. */ 449 Cpa64U numRsaEncryptRequests; 450 /**< Total number of successful RSA encrypt operation requests. */ 451 Cpa64U numRsaEncryptRequestErrors; 452 /**< Total number of RSA encrypt requests that had an error and could 453 * not be processed. */ 454 Cpa64U numRsaEncryptCompleted; 455 /**< Total number of RSA encrypt operations that completed 456 * successfully. */ 457 Cpa64U numRsaEncryptCompletedErrors; 458 /**< Total number of RSA encrypt operations that could not be 459 * completed successfully due to errors. */ 460 Cpa64U numRsaDecryptRequests; 461 /**< Total number of successful RSA decrypt operation requests. */ 462 Cpa64U numRsaDecryptRequestErrors; 463 /**< Total number of RSA decrypt requests that had an error and could 464 * not be processed. */ 465 Cpa64U numRsaDecryptCompleted; 466 /**< Total number of RSA decrypt operations that completed 467 * successfully. */ 468 Cpa64U numRsaDecryptCompletedErrors; 469 /**< Total number of RSA decrypt operations that could not be 470 * completed successfully due to errors. */ 471 Cpa64U numKptRsaDecryptRequests; 472 /**< Total number of successful KPT RSA decrypt operation requests. */ 473 Cpa64U numKptRsaDecryptRequestErrors; 474 /**< Total number of KPT RSA decrypt requests that had an error and could 475 * not be processed. */ 476 Cpa64U numKptRsaDecryptCompleted; 477 /**< Total number of KPT RSA decrypt operations that completed 478 * successfully. */ 479 Cpa64U numKptRsaDecryptCompletedErrors; 480 /**< Total number of KPT RSA decrypt operations that could not be 481 * completed successfully due to errors. */ 482 } CpaCyRsaStats64; 483 484 /** 485 ***************************************************************************** 486 * @ingroup cpaCyRsa 487 * Definition of the RSA key generation callback function. 488 * 489 * @description 490 * This is the prototype for the RSA key generation callback function. The 491 * callback function pointer is passed in as a parameter to the 492 * cpaCyRsaGenKey function. It will be invoked once the request has 493 * completed. 494 * 495 * @context 496 * This callback function can be executed in a context that DOES NOT 497 * permit sleeping to occur. 498 * @assumptions 499 * None 500 * @sideEffects 501 * None 502 * @reentrant 503 * No 504 * @threadSafe 505 * Yes 506 * 507 * @param[in] pCallbackTag Opaque value provided by user while making 508 * individual function calls. 509 * @param[in] status Status of the operation. Valid values are 510 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 511 * CPA_STATUS_UNSUPPORTED. 512 * @param[in] pKeyGenOpData Structure with output params for callback. 513 * @param[in] pPrivateKey Structure which contains pointers to the memory 514 * into which the generated private key will be 515 * written. 516 * @param[in] pPublicKey Structure which contains pointers to the memory 517 * into which the generated public key will be 518 * written. The pointer to the public exponent (e) 519 * that is returned in this structure is equal to 520 * the input public exponent. 521 * @retval 522 * None 523 * @pre 524 * Component has been initialized. 525 * @post 526 * None 527 * @note 528 * None 529 * @see 530 * CpaCyRsaPrivateKey, 531 * CpaCyRsaPublicKey, 532 * cpaCyRsaGenKey() 533 * 534 *****************************************************************************/ 535 typedef void (*CpaCyRsaKeyGenCbFunc)(void *pCallbackTag, 536 CpaStatus status, 537 void *pKeyGenOpData, 538 CpaCyRsaPrivateKey *pPrivateKey, 539 CpaCyRsaPublicKey *pPublicKey); 540 541 /** 542 ***************************************************************************** 543 * @ingroup cpaCyRsa 544 * Generate RSA keys. 545 * 546 * @description 547 * This function will generate private and public keys for RSA as specified 548 * in the PKCS #1 V2.1 standard. Both representation types of the private 549 * key may be generated. 550 * 551 * @context 552 * When called as an asynchronous function it cannot sleep. It can be 553 * executed in a context that does not permit sleeping. 554 * When called as a synchronous function it may sleep. It MUST NOT be 555 * executed in a context that DOES NOT permit sleeping. 556 * @assumptions 557 * None 558 * @sideEffects 559 * None 560 * @blocking 561 * Yes when configured to operate in synchronous mode. 562 * @reentrant 563 * No 564 * @threadSafe 565 * Yes 566 * 567 * @param[in] instanceHandle Instance handle. 568 * @param[in] pRsaKeyGenCb Pointer to the callback function to be invoked 569 * when the operation is complete. If this is 570 * set to a NULL value the function will operate 571 * synchronously. 572 * @param[in] pCallbackTag Opaque User Data for this specific call. Will 573 * be returned unchanged in the callback. 574 * @param[in] pKeyGenOpData Structure containing all the data needed to 575 * perform the RSA key generation operation. The 576 * client code allocates the memory for this 577 * structure. This component takes ownership of 578 * the memory until it is returned in the 579 * callback. 580 * @param[out] pPrivateKey Structure which contains pointers to the memory 581 * into which the generated private key will be 582 * written. The client MUST allocate memory 583 * for this structure, and for the pointers 584 * within it, recursively; on return, these will 585 * be populated. 586 * @param[out] pPublicKey Structure which contains pointers to the memory 587 * into which the generated public key will be 588 * written. The memory for this structure and 589 * for the modulusN parameter MUST be allocated 590 * by the client, and will be populated on return 591 * from the call. The field publicExponentE 592 * is not modified or touched in any way; it is 593 * the responsibility of the client to set this 594 * to the same value as the corresponding 595 * parameter on the CpaCyRsaKeyGenOpData 596 * structure before using the key for encryption. 597 * 598 * @retval CPA_STATUS_SUCCESS Function executed successfully. 599 * @retval CPA_STATUS_FAIL Function failed. 600 * @retval CPA_STATUS_RETRY Resubmit the request. 601 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 602 * @retval CPA_STATUS_RESOURCE Error related to system resources. 603 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 604 * the request. 605 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 606 * 607 * @pre 608 * The component has been initialized via cpaCyStartInstance function. 609 * @post 610 * None 611 * @note 612 * When pRsaKeyGenCb is non-NULL, an asynchronous callback of type is 613 * generated in response to this function call. 614 * Any errors generated during processing are reported as part of the 615 * callback status code. For optimal performance, data pointers SHOULD be 616 * 8-byte aligned. 617 * @see 618 * CpaCyRsaKeyGenOpData, 619 * CpaCyRsaKeyGenCbFunc, 620 * cpaCyRsaEncrypt(), 621 * cpaCyRsaDecrypt() 622 * 623 *****************************************************************************/ 624 CpaStatus 625 cpaCyRsaGenKey(const CpaInstanceHandle instanceHandle, 626 const CpaCyRsaKeyGenCbFunc pRsaKeyGenCb, 627 void *pCallbackTag, 628 const CpaCyRsaKeyGenOpData *pKeyGenOpData, 629 CpaCyRsaPrivateKey *pPrivateKey, 630 CpaCyRsaPublicKey *pPublicKey); 631 632 /** 633 ***************************************************************************** 634 * @ingroup cpaCyRsa 635 * Perform the RSA encrypt (or verify) primitive operation on the input 636 * data. 637 * 638 * @description 639 * This function will perform an RSA encryption primitive operation on the 640 * input data using the specified RSA public key. As the RSA encryption 641 * primitive and verification primitive operations are mathematically 642 * identical this function may also be used to perform an RSA verification 643 * primitive operation. 644 * 645 * @context 646 * When called as an asynchronous function it cannot sleep. It can be 647 * executed in a context that does not permit sleeping. 648 * When called as a synchronous function it may sleep. It MUST NOT be 649 * executed in a context that DOES NOT permit sleeping. 650 * @assumptions 651 * None 652 * @sideEffects 653 * None 654 * @blocking 655 * Yes when configured to operate in synchronous mode. 656 * @reentrant 657 * No 658 * @threadSafe 659 * Yes 660 * 661 * @param[in] instanceHandle Instance handle. 662 * @param[in] pRsaEncryptCb Pointer to callback function to be invoked 663 * when the operation is complete. If this is 664 * set to a NULL value the function will operate 665 * synchronously. 666 * @param[in] pCallbackTag Opaque User Data for this specific call. Will 667 * be returned unchanged in the callback. 668 * @param[in] pEncryptOpData Structure containing all the data needed to 669 * perform the RSA encryption operation. The 670 * client code allocates the memory for this 671 * structure. This component takes ownership of 672 * the memory until it is returned in the 673 * callback. 674 * @param[out] pOutputData Pointer to structure into which the result of 675 * the RSA encryption primitive is written. The 676 * client MUST allocate this memory. The data 677 * pointed to is an integer in big-endian order. 678 * The value will be between 0 and the modulus 679 * n - 1. 680 * On invocation the callback function will 681 * contain this parameter in the pOut parameter. 682 * 683 * @retval CPA_STATUS_SUCCESS Function executed successfully. 684 * @retval CPA_STATUS_FAIL Function failed. 685 * @retval CPA_STATUS_RETRY Resubmit the request. 686 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 687 * @retval CPA_STATUS_RESOURCE Error related to system resources. 688 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 689 * the request. 690 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 691 * 692 * @pre 693 * The component has been initialized via cpaCyStartInstance function. 694 * @post 695 * None 696 * @note 697 * When pRsaEncryptCb is non-NULL an asynchronous callback of type is 698 * generated in response to this function call. 699 * Any errors generated during processing are reported as part of the 700 * callback status code. For optimal performance, data pointers SHOULD be 701 * 8-byte aligned. 702 * @see 703 * CpaCyGenFlatBufCbFunc 704 * CpaCyRsaEncryptOpData 705 * cpaCyRsaGenKey() 706 * cpaCyRsaDecrypt() 707 * 708 *****************************************************************************/ 709 CpaStatus 710 cpaCyRsaEncrypt(const CpaInstanceHandle instanceHandle, 711 const CpaCyGenFlatBufCbFunc pRsaEncryptCb, 712 void *pCallbackTag, 713 const CpaCyRsaEncryptOpData *pEncryptOpData, 714 CpaFlatBuffer *pOutputData); 715 716 /** 717 ***************************************************************************** 718 * @ingroup cpaCyRsa 719 * Perform the RSA decrypt (or sign) primitive operation on the input 720 * data. 721 * 722 * @description 723 * This function will perform an RSA decryption primitive operation on the 724 * input data using the specified RSA private key. As the RSA decryption 725 * primitive and signing primitive operations are mathematically identical 726 * this function may also be used to perform an RSA signing primitive 727 * operation. 728 * 729 * @context 730 * When called as an asynchronous function it cannot sleep. It can be 731 * executed in a context that does not permit sleeping. 732 * When called as a synchronous function it may sleep. It MUST NOT be 733 * executed in a context that DOES NOT permit sleeping. 734 * @assumptions 735 * None 736 * @sideEffects 737 * None 738 * @blocking 739 * Yes when configured to operate in synchronous mode. 740 * @reentrant 741 * No 742 * @threadSafe 743 * Yes 744 * 745 * @param[in] instanceHandle Instance handle. 746 * @param[in] pRsaDecryptCb Pointer to callback function to be invoked 747 * when the operation is complete. If this is 748 * set to a NULL value the function will operate 749 * synchronously. 750 * @param[in] pCallbackTag Opaque User Data for this specific call. 751 * Will be returned unchanged in the callback. 752 * @param[in] pDecryptOpData Structure containing all the data needed to 753 * perform the RSA decrypt operation. The 754 * client code allocates the memory for this 755 * structure. This component takes ownership 756 * of the memory until it is returned in the 757 * callback. 758 * @param[out] pOutputData Pointer to structure into which the result of 759 * the RSA decryption primitive is written. The 760 * client MUST allocate this memory. The data 761 * pointed to is an integer in big-endian order. 762 * The value will be between 0 and the modulus 763 * n - 1. 764 * On invocation the callback function will 765 * contain this parameter in the pOut parameter. 766 * 767 * @retval CPA_STATUS_SUCCESS Function executed successfully. 768 * @retval CPA_STATUS_FAIL Function failed. 769 * @retval CPA_STATUS_RETRY Resubmit the request. 770 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 771 * @retval CPA_STATUS_RESOURCE Error related to system resources. 772 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 773 * the request. 774 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 775 * 776 * @pre 777 * The component has been initialized via cpaCyStartInstance function. 778 * @post 779 * None 780 * @note 781 * When pRsaDecryptCb is non-NULL an asynchronous callback is generated in 782 * response to this function call. 783 * Any errors generated during processing are reported as part of the 784 * callback status code. For optimal performance, data pointers SHOULD be 785 * 8-byte aligned. 786 * @see 787 * CpaCyRsaDecryptOpData, 788 * CpaCyGenFlatBufCbFunc, 789 * cpaCyRsaGenKey(), 790 * cpaCyRsaEncrypt() 791 * 792 *****************************************************************************/ 793 CpaStatus 794 cpaCyRsaDecrypt(const CpaInstanceHandle instanceHandle, 795 const CpaCyGenFlatBufCbFunc pRsaDecryptCb, 796 void *pCallbackTag, 797 const CpaCyRsaDecryptOpData *pDecryptOpData, 798 CpaFlatBuffer * pOutputData); 799 800 /** 801 ***************************************************************************** 802 * @ingroup cpaCyRsa 803 * Query statistics for a specific RSA instance. 804 * 805 * @deprecated 806 * As of v1.3 of the Crypto API, this function has been deprecated, 807 * replaced by @ref cpaCyRsaQueryStats64(). 808 * 809 * @description 810 * This function will query a specific instance for RSA statistics. The 811 * user MUST allocate the CpaCyRsaStats structure and pass the 812 * reference to that into this function call. This function will write the 813 * statistic results into the passed in CpaCyRsaStats structure. 814 * 815 * Note: statistics returned by this function do not interrupt current data 816 * processing and as such can be slightly out of sync with operations that 817 * are in progress during the statistics retrieval process. 818 * 819 * @context 820 * This is a synchronous function and it can sleep. It MUST NOT be 821 * executed in a context that DOES NOT permit sleeping. 822 * @assumptions 823 * None 824 * @sideEffects 825 * None 826 * @blocking 827 * This function is synchronous and blocking. 828 * @reentrant 829 * No 830 * @threadSafe 831 * Yes 832 * 833 * @param[in] instanceHandle Instance handle. 834 * @param[out] pRsaStats Pointer to memory into which the statistics 835 * will be written. 836 * 837 * @retval CPA_STATUS_SUCCESS Function executed successfully. 838 * @retval CPA_STATUS_FAIL Function failed. 839 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 840 * @retval CPA_STATUS_RESOURCE Error related to system resources. 841 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 842 * the request. 843 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 844 * 845 * @pre 846 * Component has been initialized. 847 * @post 848 * None 849 * @note 850 * This function operates in a synchronous manner and no asynchronous 851 * callback will be generated. 852 * @see 853 * CpaCyRsaStats 854 * 855 *****************************************************************************/ 856 CpaStatus CPA_DEPRECATED 857 cpaCyRsaQueryStats(const CpaInstanceHandle instanceHandle, 858 struct _CpaCyRsaStats *pRsaStats); 859 860 /** 861 ***************************************************************************** 862 * @ingroup cpaCyRsa 863 * Query statistics (64-bit version) for a specific RSA instance. 864 * 865 * @description 866 * This function will query a specific instance for RSA statistics. The 867 * user MUST allocate the CpaCyRsaStats64 structure and pass the 868 * reference to that into this function call. This function will write the 869 * statistic results into the passed in CpaCyRsaStats64 structure. 870 * 871 * Note: statistics returned by this function do not interrupt current data 872 * processing and as such can be slightly out of sync with operations that 873 * are in progress during the statistics retrieval process. 874 * 875 * @context 876 * This is a synchronous function and it can sleep. It MUST NOT be 877 * executed in a context that DOES NOT permit sleeping. 878 * @assumptions 879 * None 880 * @sideEffects 881 * None 882 * @blocking 883 * This function is synchronous and blocking. 884 * @reentrant 885 * No 886 * @threadSafe 887 * Yes 888 * 889 * @param[in] instanceHandle Instance handle. 890 * @param[out] pRsaStats Pointer to memory into which the statistics 891 * will be written. 892 * 893 * @retval CPA_STATUS_SUCCESS Function executed successfully. 894 * @retval CPA_STATUS_FAIL Function failed. 895 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 896 * @retval CPA_STATUS_RESOURCE Error related to system resources. 897 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 898 * the request. 899 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 900 * 901 * @pre 902 * Component has been initialized. 903 * @post 904 * None 905 * @note 906 * This function operates in a synchronous manner and no asynchronous 907 * callback will be generated. 908 * @see 909 * CpaCyRsaStats64 910 *****************************************************************************/ 911 CpaStatus 912 cpaCyRsaQueryStats64(const CpaInstanceHandle instanceHandle, 913 CpaCyRsaStats64 *pRsaStats); 914 915 #ifdef __cplusplus 916 } /* close the extern "C" { */ 917 #endif 918 919 #endif /* CPA_CY_RSA_H */ 920