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_kpt.h 12 * 13 * @defgroup cpaCyKpt Intel(R) Key Protection Technology (KPT) Cryptographic API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the APIs for Key Protection Technology (KPT) 19 * Cryptographic services. 20 * 21 * @note 22 * These functions implement the KPT Cryptographic API. 23 * This API is experimental and subject to change. 24 * 25 *****************************************************************************/ 26 27 #ifndef __CPA_CY_KPT_H__ 28 #define __CPA_CY_KPT_H__ 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 #include "cpa_cy_common.h" 34 #include "cpa_cy_rsa.h" 35 #include "cpa_cy_ecdsa.h" 36 #include "cpa_cy_ec.h" 37 38 /** 39 ***************************************************************************** 40 * @ingroup cpaCyKpt 41 * KPT wrapping key handle 42 * 43 * @description 44 * Handle to a unique wrapping key in wrapping key table. Application 45 * creates it in KPT key transfer phase and maintains it for KPT Crypto 46 * service. For each KPT Crypto service API invocation, this handle will 47 * be used to get a SWK(Symmetric Wrapping Key) to unwrap 48 * WPK(Wrapped Private Key) before performing the requested crypto 49 * service. 50 * 51 *****************************************************************************/ 52 typedef Cpa64U CpaCyKptHandle; 53 54 /** 55 ***************************************************************************** 56 * @ingroup cpaCyKpt 57 * Return Status 58 * @description 59 * This enumeration lists all the possible return status after completing 60 * KPT APIs. 61 * 62 *****************************************************************************/ 63 typedef enum CpaCyKptKeyManagementStatus_t 64 { 65 CPA_CY_KPT_SUCCESS = 0, 66 /**< Generic success status for all KPT wrapping key handling functions */ 67 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_VFID, 68 /**< SWK count exceeds the configured maximum value per VFID */ 69 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_PASID, 70 /**< SWK count exceeds the configured maximum value per PASID */ 71 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED, 72 /**< SWK count exceeds the configured maximum value when not scoped to 73 * VFID or PASID */ 74 CPA_CY_KPT_SWK_FAIL_NOT_FOUND, 75 /**< Unable to find SWK entry by handle */ 76 CPA_CY_KPT_FAILED, 77 } CpaCyKptKeyManagementStatus; 78 79 /** 80 ***************************************************************************** 81 * @ingroup cpaCyKpt 82 * PKCS#1 v2.2 RSA-3K signature output length in bytes. 83 * @see CpaCyKptValidationKey 84 * 85 *****************************************************************************/ 86 #define CPA_CY_RSA3K_SIG_SIZE_INBYTES 384 87 88 /** 89 ***************************************************************************** 90 * @ingroup cpaCyKpt 91 * KPT device credentials key certificate 92 * @description 93 * This structure defines the key format for use with KPT. 94 * @see 95 * cpaCyKptQueryDeviceCredentials 96 * 97 *****************************************************************************/ 98 typedef struct CpaCyKptValidationKey_t 99 { 100 CpaCyRsaPublicKey publicKey; 101 /**< Key */ 102 Cpa8U signature[CPA_CY_RSA3K_SIG_SIZE_INBYTES]; 103 /**< Signature of key */ 104 } CpaCyKptValidationKey; 105 106 /** 107 ***************************************************************************** 108 * @ingroup cpaCyKpt 109 * Cipher algorithms used to generate a wrapped private key (WPK) from 110 * the clear private key. 111 * 112 * @description 113 * This enumeration lists supported cipher algorithms and modes. 114 * 115 *****************************************************************************/ 116 typedef enum CpaCyKptWrappingKeyType_t 117 { 118 CPA_CY_KPT_WRAPPING_KEY_TYPE_AES256_GCM = 0 119 } CpaCyKptWrappingKeyType; 120 121 /** 122 ***************************************************************************** 123 * @ingroup cpaCyKpt 124 * KPT Loading key format specification. 125 * @description 126 * This structure defines the format of the symmetric wrapping key to be 127 * loaded into KPT. Application sets these parameters through the 128 * cpaCyKptLoadKey calls. 129 * 130 *****************************************************************************/ 131 typedef struct CpaCyKptLoadKey_t 132 { 133 CpaFlatBuffer eSWK; 134 /**< Encrypted SWK */ 135 CpaCyKptWrappingKeyType wrappingAlgorithm; 136 /**< Symmetric wrapping algorithm */ 137 } CpaCyKptLoadKey; 138 139 /** 140 ***************************************************************************** 141 * @ingroup cpaCyKpt 142 * Max length of initialization vector 143 * @description 144 * Defines the permitted max iv length in bytes that may be used in 145 * private key wrapping/unwrapping.For AEC-GCM, iv length is 12 bytes. 146 * 147 *@see cpaCyKptUnwrapContext 148 * 149 *****************************************************************************/ 150 #define CPA_CY_KPT_MAX_IV_LENGTH (12) 151 152 /** 153 ***************************************************************************** 154 * @ingroup cpaCyKpt 155 * Max length of Additional Authenticated Data 156 * @description 157 * Defines the permitted max aad length in bytes that may be used in 158 * private key wrapping/unwrapping. 159 * 160 *@see cpaCyKptUnwrapContext 161 * 162 *****************************************************************************/ 163 #define CPA_CY_KPT_MAX_AAD_LENGTH (16) 164 165 /** 166 ***************************************************************************** 167 * @file cpa_cy_kpt.h 168 * @ingroup cpaCyKpt 169 * Structure of KPT unwrapping context. 170 * @description 171 * This structure is a parameter of KPT crypto APIs, it contains data 172 * relating to KPT WPK unwrapping, the application needs to fill in this 173 * information. 174 * 175 *****************************************************************************/ 176 typedef struct CpaCyKptUnwrapContext_t 177 { 178 CpaCyKptHandle kptHandle; 179 /**< This is application's unique handle that identifies its 180 * (symmetric) wrapping key*/ 181 Cpa8U iv[CPA_CY_KPT_MAX_IV_LENGTH]; 182 /**< Initialization Vector */ 183 Cpa8U additionalAuthData[CPA_CY_KPT_MAX_AAD_LENGTH]; 184 /**< A buffer holding the Additional Authenticated Data.*/ 185 Cpa32U aadLenInBytes; 186 /**< Number of bytes representing the size of AAD within additionalAuthData 187 * buffer. */ 188 } CpaCyKptUnwrapContext; 189 190 /** 191 ***************************************************************************** 192 * @file cpa_cy_kpt.h 193 * @ingroup cpaCyKpt 194 * RSA Private Key Structure For Representation 1. 195 * @description 196 * This structure contains the first representation that can be used for 197 * describing the RSA private key, represented by the tuple of the 198 * modulus (N) and the private exponent (D). 199 * The representation is encrypted as follows: 200 * Encrypt - AES-256-GCM (Key, AAD, Input) 201 * "||" - denotes concatenation 202 * Key = SWK 203 * AAD = DER(OID) 204 * Input = (D || N) 205 * Encrypt (SWK, AAD, (D || N)) 206 * Output (AuthTag, (D || N)') 207 * EncryptedRSAKey = (D || N)' 208 * 209 * privateKey = (EncryptedRSAKey || AuthTag) 210 * 211 * OID's that shall be supported by KPT implementation: 212 * OID DER(OID) 213 * 1.2.840.113549.1.1 06 08 2A 86 48 86 F7 0D 01 01 214 * 215 * Permitted lengths for N and D are: 216 * - 512 bits (64 bytes), 217 * - 1024 bits (128 bytes), 218 * - 1536 bits (192 bytes), 219 * - 2048 bits (256 bytes), 220 * - 3072 bits (384 bytes), 221 * - 4096 bits (512 bytes), or 222 * - 8192 bits (1024 bytes). 223 * 224 * AuthTag is 128 bits (16 bytes) 225 * 226 * @note It is important that the value D is big enough. It is STRONGLY 227 * recommended that this value is at least half the length of the modulus 228 * N to protect against the Wiener attack. 229 * 230 *****************************************************************************/ 231 typedef struct CpaCyKptRsaPrivateKeyRep1_t 232 { 233 CpaFlatBuffer privateKey; 234 /**< The EncryptedRSAKey concatenated with AuthTag */ 235 } CpaCyKptRsaPrivateKeyRep1; 236 237 /** 238 ***************************************************************************** 239 * @file cpa_cy_kpt.h 240 * @ingroup cpaCyKpt 241 * KPT RSA Private Key Structure For Representation 2. 242 * @description 243 * This structure contains the second representation that can be used for 244 * describing the RSA private key. The quintuple of p, q, dP, dQ, and qInv 245 * (explained below and in the spec) are required for the second 246 * representation. For KPT the parameters are Encrypted 247 * with the associated SWK as follows: 248 * Encrypt - AES-256-GCM (Key, AAD, Input) 249 * "||" - denotes concatenation 250 * Key = SWK 251 * AAD = DER(OID) 252 * Input = (P || Q || dP || dQ || Qinv || publicExponentE) 253 * Expanded Description: 254 * Encrypt (SWK, AAD, 255 * (P || Q || dP || dQ || Qinv || publicExponentE)) 256 * EncryptedRSAKey = (P || Q || dP || dQ || Qinv || publicExponentE)' 257 * Output (AuthTag, EncryptedRSAKey) 258 * 259 * privateKey = EncryptedRSAKey || AuthTag 260 * 261 * OID's that shall be supported by KPT implementation: 262 * OID DER(OID) 263 * 1.2.840.113549.1.1 06 08 2A 86 48 86 F7 0D 01 01 264 * 265 * All of the encrypted parameters will be of equal size. The length of 266 * each will be equal to keySize in bytes/2. 267 * For example for a key size of 256 Bytes (2048 bits), the length of 268 * P, Q, dP, dQ, and Qinv are all 128 Bytes, plus the 269 * publicExponentE of 256 Bytes, giving a total size for 270 * EncryptedRSAKey of 896 Bytes. 271 * 272 * AuthTag is 128 bits (16 bytes) 273 * 274 * Permitted Key Sizes are: 275 * - 512 bits (64 bytes), 276 * - 1024 bits (128 bytes), 277 * - 1536 bits (192 bytes), 278 * - 2048 bits (256 bytes), 279 * - 3072 bits (384 bytes), 280 * - 4096 bits (512 bytes), or 281 * - 8192 bits (1024 bytes). 282 * 283 *****************************************************************************/ 284 typedef struct CpaCyKptRsaPrivateKeyRep2_t 285 { 286 CpaFlatBuffer privateKey; 287 /**< RSA private key representation 2 is built up from the 288 * tuple of p, q, dP, dQ, qInv, publicExponentE and AuthTag. 289 */ 290 } CpaCyKptRsaPrivateKeyRep2; 291 292 /** 293 ***************************************************************************** 294 * @file cpa_cy_kpt.h 295 * @ingroup cpaCyKpt 296 * RSA Private Key Structure. 297 * @description 298 * This structure contains the two representations that can be used for 299 * describing the RSA private key. The privateKeyRepType will be used to 300 * identify which representation is to be used. Typically, using the 301 * second representation results in faster decryption operations. 302 * 303 *****************************************************************************/ 304 typedef struct CpaCyKptRsaPrivateKey_t 305 { 306 CpaCyRsaVersion version; 307 /**< Indicates the version of the PKCS #1 specification that is 308 * supported. 309 * Note that this applies to both representations. */ 310 CpaCyRsaPrivateKeyRepType privateKeyRepType; 311 /**< This value is used to identify which of the private key 312 * representation types in this structure is relevant. 313 * When performing key generation operations for Type 2 representations, 314 * memory must also be allocated for the type 1 representations, and values 315 * for both will be returned. */ 316 CpaCyKptRsaPrivateKeyRep1 privateKeyRep1; 317 /**< This is the first representation of the RSA private key as 318 * defined in the PKCS #1 V2.2 specification. */ 319 CpaCyKptRsaPrivateKeyRep2 privateKeyRep2; 320 /**< This is the second representation of the RSA private key as 321 * defined in the PKCS #1 V2.2 specification. */ 322 } CpaCyKptRsaPrivateKey; 323 324 /** 325 ***************************************************************************** 326 * @file cpa_cy_kpt.h 327 * @ingroup cpaCyKpt 328 * KPT RSA Decryption Primitive Operation Data 329 * @description 330 * This structure lists the different items that are required in the 331 * cpaCyKptRsaDecrypt function. As the RSA decryption primitive and 332 * signature primitive operations are mathematically identical this 333 * structure may also be used to perform an RSA signature primitive 334 * operation. 335 * When performing an RSA decryption primitive operation, the input data 336 * is the cipher text and the output data is the message text. 337 * When performing an RSA signature primitive operation, the input data 338 * is the message and the output data is the signature. 339 * The client MUST allocate the memory for this structure. When the 340 * structure is passed into the function, ownership of the memory passes 341 * to he function. Ownership of the memory returns to the client when 342 * this structure is returned in the CpaCyGenFlatBufCbFunc 343 * callback function. 344 * 345 * @note 346 * If the client modifies or frees the memory referenced in this structure 347 * after it has been submitted to the cpaCyKptRsaDecrypt function, and 348 * before it has been returned in the callback, undefined behavior will 349 * result. 350 * All values in this structure are required to be in Most Significant Byte 351 * first order, e.g. inputData.pData[0] = MSB. 352 * 353 *****************************************************************************/ 354 typedef struct CpaCyKptRsaDecryptOpData_t 355 { 356 CpaCyKptRsaPrivateKey *pRecipientPrivateKey; 357 /**< Pointer to the recipient's RSA private key. */ 358 CpaFlatBuffer inputData; 359 /**< The input data that the RSA decryption primitive operation is 360 * performed on. The data pointed to is an integer that MUST be in big- 361 * endian order. The value MUST be between 0 and the modulus n - 1. */ 362 } CpaCyKptRsaDecryptOpData; 363 364 365 /** 366 ***************************************************************************** 367 * @file cpa_cy_kpt.h 368 * @ingroup cpaCyKpt 369 * KPT ECDSA Sign R & S Operation Data. 370 * 371 * @description 372 * This structure contains the operation data for the cpaCyKptEcdsaSignRS 373 * function. The client MUST allocate the memory for this structure and the 374 * items pointed to by this structure. When the structure is passed into 375 * the function, ownership of the memory passes to the function. Ownership 376 * of the memory returns to the client when this structure is returned in 377 * the callback function. 378 * This key structure is encrypted when passed into cpaCyKptEcdsaSignRS 379 * Encrypt - AES-256-GCM (Key, AAD, Input) 380 * "||" - denotes concatenation 381 * 382 * Key = SWK 383 * AAD = DER(OID) 384 * Input = (d) 385 * Encrypt (SWK, AAD, (d)) 386 * Output (AuthTag, EncryptedECKey) 387 * 388 * privatekey == EncryptedECKey || AuthTag 389 * 390 * OID's that shall be supported by KPT implementation: 391 * Curve OID DER(OID) 392 * secp256r1 1.2.840.10045.3.1.7 06 08 2A 86 48 CE 3D 03 01 07 393 * secp384r1 1.3.132.0.34 06 05 2B 81 04 00 22 394 * secp521r1 1.3.132.0.35 06 05 2B 81 04 00 23 395 * 396 * Expected private key (d) sizes: 397 * secp256r1 256 bits 398 * secp384r1 384 bits 399 * secp521r1 576 bits (rounded up to a multiple of 64-bit quadword) 400 * 401 * AuthTag is 128 bits (16 bytes) 402 * 403 * For optimal performance all data buffers SHOULD be 8-byte aligned. 404 * 405 * @note 406 * If the client modifies or frees the memory referenced in this 407 * structure after it has been submitted to the cpaCyKptEcdsaSignRS 408 * function, and before it has been returned in the callback, undefined 409 * behavior will result. 410 * 411 * @see 412 * cpaCyEcdsaSignRS() 413 * 414 *****************************************************************************/ 415 typedef struct CpaCyKptEcdsaSignRSOpData_t 416 { 417 CpaFlatBuffer privateKey; 418 /**< Encrypted private key data of the form 419 * EncryptECKey || AuthTag */ 420 CpaFlatBuffer m; 421 /**< digest of the message to be signed */ 422 } CpaCyKptEcdsaSignRSOpData; 423 424 /** 425 ***************************************************************************** 426 * Discovery and Provisioning APIs for KPT 427 * 428 *****************************************************************************/ 429 430 /** 431 ***************************************************************************** 432 * @file cpa_cy_kpt.h 433 * @ingroup cpaCyKpt 434 * Query KPT's issuing public key(R_Pu) and signature from QAT driver. 435 * @description 436 * This function is to query the RSA3K issuing key and its 437 * PKCS#1 v2.2 SHA-384 signature from the QAT driver. 438 * @context 439 * This function may sleep, and MUST NOT be called in interrupt context. 440 * @assumptions 441 * None 442 * @sideEffects 443 * None 444 * @blocking 445 * This function is synchronous and blocking. 446 * @param[in] instanceHandle Instance handle. 447 * @param[out] pIssueCert KPT-2.0 Issuing certificate in PEM format 448 as defined in RFC#7468 449 * @param[out] pKptStatus One of the status codes denoted in the 450 * enumerate type CpaCyKptKeyManagementStatus 451 * CPA_CY_KPT_SUCCESS Issuing key retrieved successfully 452 * CPA_CY_KPT_FAILED Operation failed 453 * 454 * @retval CPA_STATUS_SUCCESS Function executed successfully. 455 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 456 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 457 * is to shutdown and restart. 458 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 459 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 460 * Resubmit the request. 461 * 462 * @pre 463 * The component has been initialized via cpaCyStartInstance function. 464 * @post 465 * None 466 * @note 467 * Note that this is a synchronous function and has no completion callback 468 * associated with it. 469 * @see 470 * 471 *****************************************************************************/ 472 CpaStatus 473 cpaCyKptQueryIssuingKeys(const CpaInstanceHandle instanceHandle, 474 CpaFlatBuffer *pPublicX509IssueCert, 475 CpaCyKptKeyManagementStatus *pKptStatus); 476 477 /** 478 ***************************************************************************** 479 * @file cpa_cy_kpt.h 480 * @ingroup cpaCyKpt 481 * Query KPT's Per-Part public key(I_pu) and signature from QAT 482 * device 483 * @description 484 * This function is to query RSA3K Per-Part public key and its 485 * PKCS#1 v2.2 SHA-384 signature from the QAT device. 486 * @context 487 * This function may sleep, and MUST NOT be called in interrupt context. 488 * @assumptions 489 * None 490 * @sideEffects 491 * None 492 * @blocking 493 * This function is synchronous and blocking. 494 * @param[in] instanceHandle Instance handle. 495 * @param[out] pDevCredential Device Per-Part public key 496 * @param[out] pKptStatus One of the status codes denoted in the 497 * enumerate type CpaCyKptKeyManagementStatus 498 * CPA_CY_KPT_SUCCESS Device credentials retrieved successfully 499 * CPA_CY_KPT_FAILED Operation failed 500 * 501 * @retval CPA_STATUS_SUCCESS Function executed successfully. 502 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 503 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 504 * is to shutdown and restart. 505 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 506 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 507 * Resubmit the request. 508 * 509 * @pre 510 * The component has been initialized via cpaCyStartInstance function. 511 * @post 512 * None 513 * @note 514 * Note that this is a synchronous function and has no completion callback 515 * associated with it. 516 * @see 517 * 518 *****************************************************************************/ 519 CpaStatus 520 cpaCyKptQueryDeviceCredentials(const CpaInstanceHandle instanceHandle, 521 CpaCyKptValidationKey *pDevCredential, 522 CpaCyKptKeyManagementStatus *pKptStatus); 523 524 /** 525 ***************************************************************************** 526 * @file cpa_cy_kpt.h 527 * @ingroup cpaCyKpt 528 * Perform KPT key loading function. 529 * 530 * @description 531 * This function is invoked by a QAT application to load an encrypted 532 * symmetric wrapping key. 533 * @context 534 * This is a synchronous function and it can sleep. It MUST NOT be 535 * executed in a context that DOES NOT permit sleeping. 536 * @assumptions 537 * None 538 * @sideEffects 539 * None 540 * @blocking 541 * This function is synchronous and blocking. 542 * @reentrant 543 * No 544 * @threadSafe 545 * Yes 546 * 547 * @param[in] instanceHandle QAT service instance handle. 548 * @param[in] pSWK Encrypted SWK 549 * @param[out] keyHandle A 64-bit handle value created by KPT 550 * @param[out] pKptStatus One of the status codes denoted in the 551 * enumerate type CpaCyKptKeyManagementStatus 552 * CPA_CY_KPT_SUCCESS Key Loaded successfully 553 * CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_VFID 554 * SWK count exceeds the configured maximum value per VFID 555 * CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_PASID 556 * SWK count exceeds the configured maximum value per PASID 557 * CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED 558 * SWK count exceeds the configured maximum value when not scoped to 559 * VFID or PASID 560 * CPA_CY_KPT_FAILED Operation failed due to unspecified reason 561 * 562 * @retval CPA_STATUS_SUCCESS Function executed successfully. 563 * @retval CPA_STATUS_FAIL Function failed. 564 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 565 * @retval CPA_STATUS_RESOURCE Error related to system resources. 566 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 567 * Resubmit the request. 568 * @retval CPA_STATUS_UNSUPPORTED KPT-2.0 is not supported. 569 * 570 * @pre 571 * Component has been initialized. 572 * @post 573 * None 574 * @note 575 * None 576 * @see 577 * None 578 *****************************************************************************/ 579 CpaStatus 580 cpaCyKptLoadKey(CpaInstanceHandle instanceHandle, 581 CpaCyKptLoadKey *pSWK, 582 CpaCyKptHandle *keyHandle, 583 CpaCyKptKeyManagementStatus *pKptStatus); 584 585 /** 586 ***************************************************************************** 587 * @file cpa_cy_kpt.h 588 * @ingroup cpaCyKpt 589 * Perform KPT delete keys function according to key handle 590 * 591 * @description 592 * Before closing a QAT session(instance), an application that has 593 * previously stored its wrapping key in a QAT device using the KPT 594 * framework executes this call to delete its wrapping key in the QAT 595 * device. 596 * @context 597 * This is a synchronous function and it can sleep. It MUST NOT be 598 * executed in a context that DOES NOT permit sleeping. 599 * @assumptions 600 * None 601 * @sideEffects 602 * None 603 * @blocking 604 * This function is synchronous and blocking. 605 * @reentrant 606 * No 607 * @threadSafe 608 * Yes 609 * 610 * @param[in] instanceHandle QAT service instance handle. 611 * @param[in] keyHandle A 64-bit handle value 612 * @param[out] pkptstatus One of the status codes denoted in the 613 * enumerate type CpaCyKptKeyManagementStatus 614 * CPA_CY_KPT_SUCCESS Key Deleted successfully 615 * CPA_CY_KPT_SWK_FAIL_NOT_FOUND For any reason the input handle cannot be 616 * found. 617 * CPA_CY_KPT_FAILED Operation failed due to unspecified reason 618 * 619 * @retval CPA_STATUS_SUCCESS Function executed successfully. 620 * @retval CPA_STATUS_FAIL Function failed. 621 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 622 * @retval CPA_STATUS_RESOURCE Error related to system resources. 623 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 624 * Resubmit the request. 625 * @pre 626 * Component has been initialized. 627 * @post 628 * None 629 * @note 630 * None 631 * @see 632 * None 633 *****************************************************************************/ 634 CpaStatus 635 cpaCyKptDeleteKey(CpaInstanceHandle instanceHandle, 636 CpaCyKptHandle keyHandle, 637 CpaCyKptKeyManagementStatus *pKptStatus); 638 639 /** 640 ***************************************************************************** 641 * Usage APIs for KPT 642 * 643 *****************************************************************************/ 644 645 /** 646 ***************************************************************************** 647 * @file cpa_cy_kpt.h 648 * @ingroup cpaCyKpt 649 * Perform KPT-2.0 mode RSA decrypt primitive operation on the input data. 650 * 651 * @description 652 * This function is a variant of cpaCyRsaDecrypt, which will perform 653 * an RSA decryption primitive operation on the input data using the 654 * specified RSA private key which are encrypted. As the RSA decryption 655 * primitive and signing primitive operations are mathematically 656 * identical this function may also be used to perform an RSA signing 657 * primitive operation. 658 * 659 * @context 660 * When called as an asynchronous function it cannot sleep. It can be 661 * executed in a context that does not permit sleeping. 662 * When called as a synchronous function it may sleep. It MUST NOT be 663 * executed in a context that DOES NOT permit sleeping. 664 * @assumptions 665 * None 666 * @sideEffects 667 * None 668 * @blocking 669 * Yes when configured to operate in synchronous mode. 670 * @reentrant 671 * No 672 * @threadSafe 673 * Yes 674 * 675 * @param[in] instanceHandle Instance handle. 676 * @param[in] pRsaDecryptCb Pointer to callback function to be invoked 677 * when the operation is complete. If this is 678 * set to a NULL value the function will operate 679 * synchronously. 680 * @param[in] pCallbackTag Opaque User Data for this specific call. 681 * Will be returned unchanged in the callback. 682 * @param[in] pDecryptOpData Structure containing all the data needed to 683 * perform the RSA decrypt operation. The 684 * client code allocates the memory for this 685 * structure. This component takes ownership 686 * of the memory until it is returned in the 687 * callback. 688 * @param[out] pOutputData Pointer to structure into which the result of 689 * the RSA decryption primitive is written. The 690 * client MUST allocate this memory. The data 691 * pointed to is an integer in big-endian order. 692 * The value will be between 0 and the modulus 693 * n - 1. 694 * On invocation the callback function will 695 * contain this parameter in the pOut parameter. 696 * @param[in] pKptUnwrapContext Pointer of structure into which the content 697 * of KptUnwrapContext is kept. The client MUST 698 * allocate this memory and copy structure 699 * KptUnwrapContext into this flat buffer. 700 * 701 * @retval CPA_STATUS_SUCCESS Function executed successfully. 702 * @retval CPA_STATUS_FAIL Function failed. 703 * @retval CPA_STATUS_RETRY Resubmit the request. 704 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 705 * @retval CPA_STATUS_RESOURCE Error related to system resources. 706 * @retval CPA_STATUS_RESTARTING API implementation is restarting.Resubmit 707 * the request. 708 * @pre 709 * The component has been initialized via cpaCyStartInstance function. 710 * @post 711 * None 712 * @note 713 * By virtue of invoking cpaSyKptRsaDecrypt, the implementation understands 714 * that pDecryptOpData contains an encrypted private key that requires 715 * unwrapping. KptUnwrapContext contains a 'KptHandle' field that points 716 * to the unwrapping key in the WKT. 717 * When pRsaDecryptCb is non-NULL an asynchronous callback is generated in 718 * response to this function call. 719 * Any errors generated during processing are reported as part of the 720 * callback status code. For optimal performance, data pointers SHOULD be 721 * 8-byte aligned. 722 * In KPT release, private key field in CpaCyKptRsaDecryptOpData is a 723 * concatenation of cipher text and hash tag. 724 * For optimal performance, data pointers SHOULD be 8-byte aligned. 725 * @see 726 * CpaCyKptRsaDecryptOpData, 727 * CpaCyGenFlatBufCbFunc, 728 * 729 *****************************************************************************/ 730 CpaStatus 731 cpaCyKptRsaDecrypt(const CpaInstanceHandle instanceHandle, 732 const CpaCyGenFlatBufCbFunc pRsaDecryptCb, 733 void *pCallbackTag, 734 const CpaCyKptRsaDecryptOpData *pDecryptOpData, 735 CpaFlatBuffer *pOutputData, 736 CpaCyKptUnwrapContext *pKptUnwrapContext); 737 738 /** 739 ***************************************************************************** 740 * @ingroup cpaCyKpt 741 * Generate ECDSA Signature R & S. 742 * @description 743 * This function is a variant of cpaCyEcdsaSignRS, it generates ECDSA 744 * signature R & S as per ANSI X9.62 2005 section 7.3. 745 * @context 746 * When called as an asynchronous function it cannot sleep. It can be 747 * executed in a context that does not permit sleeping. 748 * When called as a synchronous function it may sleep. It MUST NOT be 749 * executed in a context that DOES NOT permit sleeping. 750 * @assumptions 751 * None 752 * @sideEffects 753 * None 754 * @blocking 755 * Yes when configured to operate in synchronous mode. 756 * @reentrant 757 * No 758 * @threadSafe 759 * Yes 760 * 761 * @param[in] instanceHandle Instance handle. 762 * @param[in] pCb Callback function pointer. If this is set to 763 * a NULL value the function will operate 764 * synchronously. 765 * @param[in] pCallbackTag User-supplied value to help identify request. 766 * @param[in] pOpData Structure containing all the data needed to 767 * perform the operation. The client code 768 * allocates the memory for this structure. This 769 * component takes ownership of the memory until 770 * it is returned in the callback. 771 * @param[out] pSignStatus In synchronous mode, the multiply output is 772 * valid (CPA_TRUE) or the output is invalid 773 * (CPA_FALSE). 774 * @param[out] pR ECDSA message signature r. 775 * @param[out] pS ECDSA message signature s. 776 * @param[in] pKptUnwrapContext Pointer of structure into which the content 777 * of KptUnwrapContext is kept,The client MUST 778 * allocate this memory and copy structure 779 * KptUnwrapContext into this flat buffer. 780 * 781 * @retval CPA_STATUS_SUCCESS Function executed successfully. 782 * @retval CPA_STATUS_FAIL Function failed. 783 * @retval CPA_STATUS_RETRY Resubmit the request. 784 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 785 * @retval CPA_STATUS_RESOURCE Error related to system resources. 786 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 787 * the request. 788 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 789 * 790 * @pre 791 * The component has been initialized via cpaCyStartInstance function. 792 * @post 793 * None 794 * @note 795 * By virtue of invoking the cpaCyKptEcdsaSignRS, the implementation 796 * understands CpaCyEcdsaSignRSOpData contains an encrypted private key that 797 * requires unwrapping. KptUnwrapContext contains a 'KptHandle' field 798 * that points to the unwrapping key in the WKT. 799 * When pCb is non-NULL an asynchronous callback of type 800 * CpaCyEcdsaSignRSCbFunc generated in response to this function 801 * call. 802 * In KPT release, private key field in CpaCyEcdsaSignRSOpData is a 803 * concatenation of cipher text and hash tag. 804 * @see 805 * None 806 *****************************************************************************/ 807 CpaStatus 808 cpaCyKptEcdsaSignRS(const CpaInstanceHandle instanceHandle, 809 const CpaCyEcdsaSignRSCbFunc pCb, 810 void *pCallbackTag, 811 const CpaCyKptEcdsaSignRSOpData *pOpData, 812 CpaBoolean *pSignStatus, 813 CpaFlatBuffer *pR, 814 CpaFlatBuffer *pS, 815 CpaCyKptUnwrapContext *pKptUnwrapContext); 816 817 #ifdef __cplusplus 818 } /* close the extern "C" { */ 819 #endif 820 #endif 821