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