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