/***************************************************************************
 *
 *   SPDX-License-Identifier: BSD-3-Clause
 *   Copyright(c) 2007-2026 Intel Corporation
 * 
 *   These contents may have been developed with support from one or more
 *   Intel-operated generative artificial intelligence solutions.
 *
 ***************************************************************************/

/*
 *****************************************************************************
 * Doxygen group definitions
 ****************************************************************************/

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 *
 * @defgroup cpaCyKpt Intel(R) Key Protection Technology (KPT) Cryptographic API
 *
 * @ingroup cpaCy
 *
 * @description
 *     These functions specify the APIs for Key Protection Technology (KPT)
 *     Cryptographic services.
 *
 * @note
 *     These functions implement the KPT Cryptographic API.
 *     This API is experimental and subject to change.
 *
 *****************************************************************************/

#ifndef __CPA_CY_KPT_H__
#define __CPA_CY_KPT_H__

#ifdef __cplusplus
extern "C" {
#endif
#include "cpa_cy_common.h"
#include "cpa_cy_rsa.h"
#include "cpa_cy_ecdsa.h"
#include "cpa_cy_ec.h"

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      KPT wrapping key handle
 *
 * @description
 *      Handle to a unique wrapping key in wrapping key table. Application
 *      creates it in KPT key transfer phase and maintains it for KPT Crypto
 *      service. For each KPT Crypto service API invocation, this handle will
 *      be used to get a SWK(Symmetric Wrapping Key) to unwrap
 *      WPK(Wrapped Private Key) before performing the requested crypto
 *      service.
 *
 *****************************************************************************/
typedef Cpa64U CpaCyKptHandle;

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      Return Status
 * @description
 *      This enumeration lists all the possible return status after completing
 *      KPT APIs.
 *
 *****************************************************************************/
typedef enum
{
    CPA_CY_KPT_SUCCESS = 0,
    /**< Generic success status for all KPT wrapping key handling functions */
    CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_VFID,
    /**< SWK count exceeds the configured maximum value per VFID */
    CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_PASID,
    /**< SWK count exceeds the configured maximum value per PASID */
    CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED,
    /**< SWK count exceeds the configured maximum value when not scoped to
     * VFID or PASID */
    CPA_CY_KPT_SWK_FAIL_NOT_FOUND,
    /**< Unable to find SWK entry by handle */
    CPA_CY_KPT_FAILED,
} CpaCyKptKeyManagementStatus;

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      PKCS#1 v2.2 RSA-3K signature output length in bytes.
 * @see  CpaCyKptValidationKey
 *
 *****************************************************************************/
#define CPA_CY_RSA3K_SIG_SIZE_INBYTES 384

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      KPT device credentials key certificate
 * @description
 *      This structure defines the key format for use with KPT.
 * @see
 *      cpaCyKptQueryDeviceCredentials
 *
 *****************************************************************************/
typedef struct
{
    CpaCyRsaPublicKey publicKey;
    /**< Key */
    Cpa8U signature[CPA_CY_RSA3K_SIG_SIZE_INBYTES];
    /**< Signature of key */
} CpaCyKptValidationKey;

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      Cipher algorithms used to generate a wrapped private key (WPK) from
 *      the clear private key.
 *
 * @description
 *      This enumeration lists supported cipher algorithms and modes.
 *
 *****************************************************************************/
typedef enum
{
    CPA_CY_KPT_WRAPPING_KEY_TYPE_AES256_GCM = 0
} CpaCyKptWrappingKeyType;

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      KPT Loading key format specification.
 * @description
 *      This structure defines the format of the symmetric wrapping key to be
 *      loaded into KPT. Application sets these parameters through the
 *      cpaCyKptLoadKey calls.
 *
 *****************************************************************************/
typedef struct
{
    CpaFlatBuffer eSWK;
    /**< Encrypted SWK */
    CpaCyKptWrappingKeyType wrappingAlgorithm;
    /**< Symmetric wrapping algorithm */
} CpaCyKptLoadKey;

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      Max length of initialization vector
 * @description
 *      Defines the permitted max iv length in bytes that may be used in
 *      private key wrapping/unwrapping.For AEC-GCM, iv length is 12 bytes.
 *
 *@see  cpaCyKptUnwrapContext
 *
 *****************************************************************************/
#define CPA_CY_KPT_MAX_IV_LENGTH (12)

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      Max length of Additional Authenticated Data
 * @description
 *      Defines the permitted max aad length in bytes that may be used in
 *      private key wrapping/unwrapping.
 *
 *@see  cpaCyKptUnwrapContext
 *
 *****************************************************************************/
#define CPA_CY_KPT_MAX_AAD_LENGTH (16)

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Structure of KPT unwrapping context.
 * @description
 *      This structure is a parameter of KPT crypto APIs, it contains data
 *      relating to KPT WPK unwrapping, the application needs to fill in this
 *      information.
 *
 *****************************************************************************/
typedef struct
{
    CpaCyKptHandle kptHandle;
    /**< This is application's unique handle that identifies its
     * (symmetric) wrapping key*/
    Cpa8U iv[CPA_CY_KPT_MAX_IV_LENGTH];
    /**< Initialization Vector - which must be a nonce */
    Cpa8U additionalAuthData[CPA_CY_KPT_MAX_AAD_LENGTH];
    /**< A buffer holding the Additional Authenticated Data.*/
    Cpa32U aadLenInBytes;
    /**< Number of bytes representing the size of AAD within additionalAuthData
     *   buffer. */
} CpaCyKptUnwrapContext;

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      RSA Private Key Structure For Representation 1.
 * @description
 *      This structure contains the first representation that can be used for
 *      describing the RSA private key, represented by the tuple of the
 *      modulus (N) and the private exponent (D).
 *      The representation is encrypted as follows:
 *      Encrypt - AES-256-GCM (Key, AAD, Input)
 *      "||" - denotes concatenation
 *      Key = SWK
 *      AAD = DER(OID)
 *      IV = nonce
 *      Input = (D || N)
 *      Encrypt (SWK, AAD, IV, (D || N))
 *      Output (AuthTag, (D || N)')
 *      EncryptedRSAKey = (D || N)'
 *
 *      privateKey = (EncryptedRSAKey || AuthTag)
 *
 *      OID's that shall be supported by KPT implementation:
 *            OID                  DER(OID)
 *            1.2.840.113549.1.1   06 08 2A 86 48 86 F7 0D 01 01
 *
 *      Permitted lengths for N and D are:
 *      - 512 bits (64 bytes),
 *      - 1024 bits (128 bytes),
 *      - 1536 bits (192 bytes),
 *      - 2048 bits (256 bytes),
 *      - 3072 bits (384 bytes),
 *      - 4096 bits (512 bytes), or
 *      - 8192 bits (1024 bytes).
 *
 *      AuthTag is 128 bits (16 bytes)
 *
 * @note It is important that the value D is big enough. It is STRONGLY
 *      recommended that this value is at least half the length of the modulus
 *      N to protect against the Wiener attack.
 *      It is critical a unique nonce is used for each SWK encrypt operation.
 *
 *****************************************************************************/
typedef struct
{
    CpaFlatBuffer privateKey;
    /**< The EncryptedRSAKey concatenated with AuthTag */
} CpaCyKptRsaPrivateKeyRep1;

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      KPT RSA Private Key Structure For Representation 2.
 * @description
 *      This structure contains the second representation that can be used for
 *      describing the RSA private key. The quintuple of p, q, dP, dQ, and qInv
 *      (explained below and in the spec) are required for the second
 *      representation. For KPT the parameters are Encrypted
 *      with the associated SWK as follows:
 *      Encrypt - AES-256-GCM (Key, AAD, Input)
 *      "||" - denotes concatenation
 *      Key = SWK
 *      IV = nonce
 *      AAD = DER(OID)
 *      Input = (P || Q || dP || dQ || Qinv || publicExponentE)
 *      Expanded Description:
 *         Encrypt (SWK, AAD, IV,
 *                     (P || Q || dP || dQ || Qinv || publicExponentE))
 *         EncryptedRSAKey = (P || Q || dP || dQ || Qinv || publicExponentE)'
 *      Output (AuthTag, EncryptedRSAKey)
 *
 *      privateKey = EncryptedRSAKey || AuthTag
 *
 *      OID's that shall be supported by KPT implementation:
 *            OID                  DER(OID)
 *            1.2.840.113549.1.1   06 08 2A 86 48 86 F7 0D 01 01
 *
 *      All of the encrypted parameters will be of equal size. The length of
 *      each will be equal to keySize in bytes/2.
 *      For example for a key size of 256 Bytes (2048 bits), the length of
 *      P, Q, dP, dQ, and Qinv are all 128 Bytes, plus the
 *      publicExponentE of 256 Bytes, giving a total size for
 *      EncryptedRSAKey of 896 Bytes.
 *
 *      AuthTag is 128 bits (16 bytes)
 *
 *      Permitted Key Sizes are:
 *      - 512 bits (64 bytes),
 *      - 1024 bits (128 bytes),
 *      - 1536 bits (192 bytes),
 *      - 2048 bits (256 bytes),
 *      - 3072 bits (384 bytes),
 *      - 4096 bits (512 bytes), or
 *      - 8192 bits (1024 bytes).
 *
 * @note It is critical a unique nonce is used for each SWK encrypt operation.
 *
 *****************************************************************************/
typedef struct
{
    CpaFlatBuffer privateKey;
    /**< RSA private key representation 2 is built up from the
     *   tuple of p, q, dP, dQ, qInv, publicExponentE and AuthTag.
     */
} CpaCyKptRsaPrivateKeyRep2;

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      RSA Private Key Structure.
 * @description
 *      This structure contains the two representations that can be used for
 *      describing the RSA private key. The privateKeyRepType will be used to
 *      identify which representation is to be used. Typically, using the
 *      second representation results in faster decryption operations.
 *
 *****************************************************************************/
typedef struct
{
    CpaCyRsaVersion version;
    /**< Indicates the version of the PKCS #1 specification that is
     * supported.
     * Note that this applies to both representations. */
    CpaCyRsaPrivateKeyRepType privateKeyRepType;
    /**< This value is used to identify which of the private key
     * representation types in this structure is relevant.
     * When performing key generation operations for Type 2 representations,
     * memory must also be allocated for the type 1 representations, and values
     * for both will be returned. */
    CpaCyKptRsaPrivateKeyRep1 privateKeyRep1;
    /**< This is the first representation of the RSA private key as
     * defined in the PKCS #1 V2.2 specification. */
    CpaCyKptRsaPrivateKeyRep2 privateKeyRep2;
    /**< This is the second representation of the RSA private key as
     * defined in the PKCS #1 V2.2 specification. */
} CpaCyKptRsaPrivateKey;

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      KPT RSA Decryption Primitive Operation Data
 * @description
 *      This structure lists the different items that are required in the
 *      cpaCyKptRsaDecrypt function. As the RSA decryption primitive and
 *      signature primitive operations are mathematically identical this
 *      structure may also be used to perform an RSA signature primitive
 *      operation.
 *      When performing an RSA decryption primitive operation, the input data
 *      is the cipher text and the output data is the message text.
 *      When performing an RSA signature primitive operation, the input data
 *      is the message and the output data is the signature.
 *      The client MUST allocate the memory for this structure. When the
 *      structure is passed into the function, ownership of the memory passes
 *      to he function. Ownership of the memory returns to the client when
 *      this structure is returned in the CpaCyGenFlatBufCbFunc
 *      callback function.
 *
 * @note
 *      If the client modifies or frees the memory referenced in this structure
 *      after it has been submitted to the cpaCyKptRsaDecrypt function, and
 *      before it has been returned in the callback, undefined behavior will
 *      result.
 *      All values in this structure are required to be in Most Significant Byte
 *      first order, e.g. inputData.pData[0] = MSB.
 *
 *****************************************************************************/
typedef struct
{
    CpaCyKptRsaPrivateKey *pRecipientPrivateKey;
    /**< Pointer to the recipient's RSA private key. */
    CpaFlatBuffer inputData;
    /**< The input data that the RSA decryption primitive operation is
     * performed on. The data pointed to is an integer that MUST be in big-
     * endian order. The value MUST be between 0 and the modulus n - 1. */
} CpaCyKptRsaDecryptOpData;

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      KPT ECDSA Sign R & S Operation Data.
 *
 * @description
 *      This structure contains the operation data for the cpaCyKptEcdsaSignRS
 *      function. The client MUST allocate the memory for this structure and the
 *      items pointed to by this structure. When the structure is passed into
 *      the function, ownership of the memory passes to the function. Ownership
 *      of the memory returns to the client when this structure is returned in
 *      the callback function.
 *      This key structure is encrypted when passed into cpaCyKptEcdsaSignRS
 *      Encrypt - AES-256-GCM (Key, AAD, Input)
 *      "||" - denotes concatenation
 *
 *      Key = SWK
 *      AAD = DER(OID)
 *      IV = nonce
 *      Input = (d)
 *      Encrypt (SWK, AAD, IV, (d))
 *      Output (AuthTag, EncryptedECKey)
 *
 *      privatekey == EncryptedECKey || AuthTag
 *
 *      OID's that shall be supported by KPT implementation:
 *          Curve      OID                  DER(OID)
 *          secp256r1  1.2.840.10045.3.1.7  06 08 2A 86 48 CE 3D 03 01 07
 *          secp384r1  1.3.132.0.34         06 05 2B 81 04 00 22
 *          secp521r1  1.3.132.0.35         06 05 2B 81 04 00 23
 *
 *      Expected private key (d) sizes:
 *          secp256r1   256 bits
 *          secp384r1   384 bits
 *          secp521r1   576 bits (rounded up to a multiple of 64-bit quadword)
 *
 *      AuthTag is 128 bits (16 bytes)
 *
 *      For optimal performance all data buffers SHOULD be 8-byte aligned.
 *
 * @note
 *      If the client modifies or frees the memory referenced in this
 *      structure after it has been submitted to the cpaCyKptEcdsaSignRS
 *      function, and before it has been returned in the callback, undefined
 *      behavior will result.
 *
 * @see
 *      cpaCyEcdsaSignRS()
 *
 *****************************************************************************/
typedef struct
{
    CpaFlatBuffer privateKey;
    /**< Encrypted private key data of the form
     * EncryptECKey || AuthTag */
    CpaFlatBuffer m;
    /**< digest of the message to be signed */
} CpaCyKptEcdsaSignRSOpData;

/**
 *****************************************************************************
 * Discovery and Provisioning APIs for KPT
 *
 *****************************************************************************/

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Query KPT's issuing public key(R_Pu) and signature from QAT driver.
 * @description
 *      This function is to query the RSA3K issuing key and its
 *      PKCS#1 v2.2 SHA-384 signature from the QAT driver.
 * @context
 *      This function may sleep, and  MUST NOT be called in interrupt context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @param[in]  instanceHandle       Instance handle.
 * @param[out] pIssueCert           KPT-2.0 Issuing certificate in PEM format
                                    as defined in RFC#7468
 * @param[out] pKptStatus           One of the status codes denoted in the
 *                                  enumerate type CpaCyKptKeyManagementStatus
 *                                  CPA_CY_KPT_SUCCESS: Issuing key retrieved
                                    successfully
 *                                  CPA_CY_KPT_FAILED: Operation failed
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_FAIL          Function failed. Suggested course of action
 *                                  is to shutdown and restart.
 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting.
 *                                  Resubmit the request.
 *
 * @pre
 *      The component has been initialized via cpaCyStartInstance function.
 * @post
 *      None
 * @note
 *      Note that this is a synchronous function and has no completion callback
 *      associated with it.
 * @see
 *
 *****************************************************************************/
CpaStatus cpaCyKptQueryIssuingKeys(const CpaInstanceHandle instanceHandle,
                                   CpaFlatBuffer *pPublicX509IssueCert,
                                   CpaCyKptKeyManagementStatus *pKptStatus);

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Query KPT's Per-Part public key(I_pu) and signature from QAT
 *      device
 * @description
 *      This function is to query RSA3K Per-Part public key and its
 *      PKCS#1 v2.2 SHA-384 signature from the QAT device.
 * @context
 *      This function may sleep, and  MUST NOT be called in interrupt context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @param[in]  instanceHandle       Instance handle.
 * @param[out] pDevCredential       Device Per-Part public key
 * @param[out] pKptStatus           One of the status codes denoted in the
 *                                  enumerate type CpaCyKptKeyManagementStatus
 *                                  CPA_CY_KPT_SUCCESS: Device credentials
 *                                  retrieved successfully
 *                                  CPA_CY_KPT_FAILED: Operation failed
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_FAIL          Function failed. Suggested course of action
 *                                  is to shutdown and restart.
 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting.
 *                                  Resubmit the request.
 *
 * @pre
 *      The component has been initialized via cpaCyStartInstance function.
 * @post
 *      None
 * @note
 *      Note that this is a synchronous function and has no completion callback
 *      associated with it.
 * @see
 *
 *****************************************************************************/
CpaStatus cpaCyKptQueryDeviceCredentials(
    const CpaInstanceHandle instanceHandle,
    CpaCyKptValidationKey *pDevCredential,
    CpaCyKptKeyManagementStatus *pKptStatus);

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Perform KPT key loading function.
 *
 * @description
 *      This function is invoked by a QAT application to load an encrypted
 *      symmetric wrapping key.
 * @context
 *      This is a synchronous function and it can sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle      QAT service instance handle.
 * @param[in]  pSWK                Encrypted SWK
 * @param[out] keyHandle           A 64-bit handle value created by KPT
 * @param[out] pKptStatus          One of the status codes denoted in the
 *                                 enumerate type CpaCyKptKeyManagementStatus
 *                                 CPA_CY_KPT_SUCCESS:
 *                                 Key Loaded successfully
 *                                 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_VFID:
 *                                 SWK count exceeds the configured maximum
 *                                 value per VFID
 *                                 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_PASID:
 *                                 SWK count exceeds the configured maximum
 *                                 value per PASID
 *                                 CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED: SWK
 *                                 count exceeds the configured maximum value
 *                                 when not scoped to VFID or
 *                                 PASID CPA_CY_KPT_FAILED: Operation failed due
 *                                 to unspecified reason
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_FAIL          Function failed.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting.
 *                                  Resubmit the request.
 * @retval CPA_STATUS_UNSUPPORTED   KPT-2.0 is not supported.
 *
 * @pre
 *      Component has been initialized.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      None
 *****************************************************************************/
CpaStatus cpaCyKptLoadKey(CpaInstanceHandle instanceHandle,
                          CpaCyKptLoadKey *pSWK,
                          CpaCyKptHandle *keyHandle,
                          CpaCyKptKeyManagementStatus *pKptStatus);

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Perform KPT delete keys function according to key handle
 *
 * @description
 *      Before closing a QAT session(instance), an application that has
 *      previously stored its wrapping key in a QAT device using the KPT
 *      framework executes this call to delete its wrapping key in the QAT
 *      device.
 * @context
 *      This is a synchronous function and it can sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle       QAT service instance handle.
 * @param[in]  keyHandle            A 64-bit handle value
 * @param[out] pkptstatus           One of the status codes denoted in the
 *                                  enumerate type CpaCyKptKeyManagementStatus
 *                                  CPA_CY_KPT_SUCCESS: Key Deleted successfully
 *                                  CPA_CY_KPT_SWK_FAIL_NOT_FOUND: For any
 *                                  reason the input handle cannot be found.
 *                                  CPA_CY_KPT_FAILED: Operation failed due to
 *                                  unspecified reason
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE       Error related to system resources.
 * @retval CPA_STATUS_RESTARTING     API implementation is restarting.
 *                                   Resubmit the request.
 * @pre
 *      Component has been initialized.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      None
 *****************************************************************************/
CpaStatus cpaCyKptDeleteKey(CpaInstanceHandle instanceHandle,
                            CpaCyKptHandle keyHandle,
                            CpaCyKptKeyManagementStatus *pKptStatus);

/**
*****************************************************************************
* Usage APIs for KPT
*
*****************************************************************************/

/**
 *****************************************************************************
 * @file cpa_cy_kpt.h
 * @ingroup cpaCyKpt
 *      Perform KPT-2.0 mode RSA decrypt primitive operation on the input data.
 *
 * @description
 *      This function is a variant of cpaCyRsaDecrypt, which will perform
 *      an RSA decryption primitive operation on the input data using the
 *      specified RSA private key which are encrypted. As the RSA decryption
 *      primitive and signing primitive operations are mathematically
 *      identical this function may also be used to perform an RSA signing
 *      primitive operation.
 *
 * @context
 *      When called as an asynchronous function it cannot sleep. It can be
 *      executed in a context that does not permit sleeping.
 *      When called as a synchronous function it may sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      Yes when configured to operate in synchronous mode.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle     Instance handle.
 * @param[in]  pRsaDecryptCb      Pointer to callback function to be invoked
 *                                when the operation is complete. If this is
 *                                set to a NULL value the function will operate
 *                                synchronously.
 * @param[in]  pCallbackTag       Opaque User Data for this specific call.
 *                                Will be returned unchanged in the callback.
 * @param[in]  pDecryptOpData     Structure containing all the data needed to
 *                                perform the RSA decrypt operation. The
 *                                client code allocates the memory for this
 *                                structure. This component takes ownership
 *                                of the memory until it is returned in the
 *                                callback.
 * @param[out] pOutputData        Pointer to structure into which the result of
 *                                the RSA decryption primitive is written. The
 *                                client MUST allocate this memory. The data
 *                                pointed to is an integer in big-endian order.
 *                                The value will be between 0 and the modulus
 *                                n - 1.
 *                                On invocation the callback function will
 *                                contain this parameter in the pOut parameter.
 * @param[in]  pKptUnwrapContext  Pointer of structure into which the content
 *                                of KptUnwrapContext is kept. The client MUST
 *                                allocate this memory and copy structure
 *                                KptUnwrapContext into this flat buffer.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_RETRY          Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE       Error related to system resources.
 * @retval CPA_STATUS_RESTARTING     API implementation is restarting.Resubmit
 *                                   the request.
 * @pre
 *      The component has been initialized via cpaCyStartInstance function.
 * @post
 *      None
 * @note
 *      By virtue of invoking cpaSyKptRsaDecrypt, the implementation understands
 *      that pDecryptOpData contains an encrypted private key that requires
 *      unwrapping. KptUnwrapContext contains a 'KptHandle' field that points
 *      to the unwrapping key in the WKT.
 *      When pRsaDecryptCb is non-NULL an asynchronous callback is generated in
 *      response to this function call.
 *      Any errors generated during processing are reported as part of the
 *      callback status code. For optimal performance, data pointers SHOULD be
 *      8-byte aligned.
 *      In KPT release, private key field in CpaCyKptRsaDecryptOpData is a
 *      concatenation of cipher text and hash tag.
 *      For optimal performance, data pointers SHOULD be 8-byte aligned.
 * @see
 *      CpaCyKptRsaDecryptOpData,
 *      CpaCyGenFlatBufCbFunc,
 *
 *****************************************************************************/
CpaStatus cpaCyKptRsaDecrypt(const CpaInstanceHandle instanceHandle,
                             const CpaCyGenFlatBufCbFunc pRsaDecryptCb,
                             void *pCallbackTag,
                             const CpaCyKptRsaDecryptOpData *pDecryptOpData,
                             CpaFlatBuffer *pOutputData,
                             CpaCyKptUnwrapContext *pKptUnwrapContext);

/**
 *****************************************************************************
 * @ingroup cpaCyKpt
 *      Generate ECDSA Signature R & S.
 * @description
 *      This function is a variant of cpaCyEcdsaSignRS, it generates ECDSA
 *      signature R & S as per ANSI X9.62 2005 section 7.3.
 * @context
 *      When called as an asynchronous function it cannot sleep. It can be
 *      executed in a context that does not permit sleeping.
 *      When called as a synchronous function it may sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      Yes when configured to operate in synchronous mode.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle     Instance handle.
 * @param[in]  pCb                Callback function pointer. If this is set to
 *                                a NULL value the function will operate
 *                                synchronously.
 * @param[in]  pCallbackTag       User-supplied value to help identify request.
 * @param[in]  pOpData            Structure containing all the data needed to
 *                                perform the operation. The client code
 *                                allocates the memory for this structure. This
 *                                component takes ownership of the memory until
 *                                it is returned in the callback.
 * @param[out] pSignStatus        In synchronous mode, the multiply output is
 *                                valid (CPA_TRUE) or the output is invalid
 *                                (CPA_FALSE).
 * @param[out] pR                 ECDSA message signature r.
 * @param[out] pS                 ECDSA message signature s.
 * @param[in]  pKptUnwrapContext  Pointer of structure into which the content
 *                                of KptUnwrapContext is kept,The client MUST
 *                                allocate this memory and copy structure
 *                                KptUnwrapContext into this flat buffer.
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_FAIL          Function failed.
 * @retval CPA_STATUS_RETRY         Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
 *                                  the request.
 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
 *
 * @pre
 *      The component has been initialized via cpaCyStartInstance function.
 * @post
 *      None
 * @note
 *      By virtue of invoking the cpaCyKptEcdsaSignRS, the implementation
 *      understands CpaCyEcdsaSignRSOpData contains an encrypted private key
 *      that requires unwrapping. KptUnwrapContext contains a 'KptHandle' field
 *      that points to the unwrapping key in the WKT. When pCb is non-NULL an
 *      asynchronous callback of type CpaCyEcdsaSignRSCbFunc generated in
 *      response to this function call.
 *      In KPT release, private key field in CpaCyEcdsaSignRSOpData is a
 *      concatenation of cipher text and hash tag.
 * @see
 *      None
 *****************************************************************************/
CpaStatus cpaCyKptEcdsaSignRS(const CpaInstanceHandle instanceHandle,
                              const CpaCyEcdsaSignRSCbFunc pCb,
                              void *pCallbackTag,
                              const CpaCyKptEcdsaSignRSOpData *pOpData,
                              CpaBoolean *pSignStatus,
                              CpaFlatBuffer *pR,
                              CpaFlatBuffer *pS,
                              CpaCyKptUnwrapContext *pKptUnwrapContext);

#ifdef __cplusplus
} /* close the extern "C" { */
#endif
#endif
