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