/*************************************************************************** * * BSD LICENSE * * Copyright(c) 2007-2023 Intel Corporation. All rights reserved. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * Neither the name of Intel Corporation nor the names of its * contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * ***************************************************************************/ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_rsa.h * * @defgroup cpaCyRsa RSA API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) RSA operations. The PKCS #1 V2.1 specification is * supported, however the support is limited to "two-prime" mode. RSA * multi-prime is not supported. * * @note * These functions implement RSA cryptographic primitives. RSA padding * schemes are not implemented. For padding schemes that require the mgf * function see @ref cpaCyKeyGen. * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). *****************************************************************************/ #ifndef CPA_CY_RSA_H #define CPA_CY_RSA_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Version. * @description * This enumeration lists the version identifier for the PKCS #1 V2.1 * standard. * @note * Multi-prime (more than two primes) is not supported. * *****************************************************************************/ typedef enum _CpaCyRsaVersion { CPA_CY_RSA_VERSION_TWO_PRIME = 1 /**< The version supported is "two-prime". */ } CpaCyRsaVersion; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Public Key Structure. * @description * This structure contains the two components which comprise the RSA * public key as defined in the PKCS #1 V2.1 standard. * All values in this structure are required to be in Most Significant Byte * first order, e.g. modulusN.pData[0] = MSB. * *****************************************************************************/ typedef struct _CpaCyRsaPublicKey { CpaFlatBuffer modulusN; /**< The modulus (n). * For key generation operations, the client MUST allocate the memory * for this parameter; its value is generated. * For encrypt operations this parameter is an input. */ CpaFlatBuffer publicExponentE; /**< The public exponent (e). * For key generation operations, this field is unused. It is NOT * generated by the interface; it is the responsibility of the client * to set this to the same value as the corresponding parameter on * the CpaCyRsaKeyGenOpData structure before using the key for * encryption. * For encrypt operations this parameter is an input. */ } CpaCyRsaPublicKey; /** ***************************************************************************** * @ingroup cpaCyRsa * 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). * All values in this structure are required to be in Most Significant Byte * first order, e.g. modulusN.pData[0] = MSB. * *****************************************************************************/ typedef struct _CpaCyRsaPrivateKeyRep1 { CpaFlatBuffer modulusN; /**< The modulus (n). For key generation operations the memory MUST * be allocated by the client and the value is generated. For other * operations this is an input. Permitted lengths 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). */ CpaFlatBuffer privateExponentD; /**< The private exponent (d). For key generation operations the * memory MUST be allocated by the client and the value is generated. For * other operations this is an input. * 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. */ } CpaCyRsaPrivateKeyRep1; /** ***************************************************************************** * @ingroup cpaCyRsa * 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. The optional sequence of triplets are not included. * All values in this structure are required to be in Most Significant Byte * first order, e.g. prime1P.pData[0] = MSB. * *****************************************************************************/ typedef struct _CpaCyRsaPrivateKeyRep2 { CpaFlatBuffer prime1P; /**< The first large prime (p). * For key generation operations, this field is unused. */ CpaFlatBuffer prime2Q; /**< The second large prime (q). * For key generation operations, this field is unused. */ CpaFlatBuffer exponent1Dp; /**< The first factor CRT exponent (dP). d mod (p-1). */ CpaFlatBuffer exponent2Dq; /**< The second factor CRT exponent (dQ). d mod (q-1). */ CpaFlatBuffer coefficientQInv; /**< The (first) Chinese Remainder Theorem (CRT) coefficient (qInv). * (inverse of q) mod p. */ } CpaCyRsaPrivateKeyRep2; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA private key representation type. * @description * This enumeration lists which PKCS V2.1 representation of the private * key is being used. * *****************************************************************************/ typedef enum _CpaCyRsaPrivateKeyRepType { CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_1= 1, /**< The first representation of the RSA private key. */ CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_2 /**< The second representation of the RSA private key. */ } CpaCyRsaPrivateKeyRepType; /** ***************************************************************************** * @ingroup cpaCyRsa * 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 _CpaCyRsaPrivateKey { 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. */ CpaCyRsaPrivateKeyRep1 privateKeyRep1; /**< This is the first representation of the RSA private key as * defined in the PKCS #1 V2.1 specification. For key generation operations * the memory for this structure is allocated by the client and the * specific values are generated. For other operations this is an input * parameter. */ CpaCyRsaPrivateKeyRep2 privateKeyRep2; /**< This is the second representation of the RSA private key as * defined in the PKCS #1 V2.1 specification. For key generation operations * the memory for this structure is allocated by the client and the * specific values are generated. For other operations this is an input * parameter. */ } CpaCyRsaPrivateKey; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Key Generation Data. * @description * This structure lists the different items that are required in the * cpaCyRsaGenKey function. The client MUST allocate the memory for 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 * CpaCyRsaKeyGenCbFunc callback function. * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyRsaGenKey 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. prime1P.pData[0] = MSB. * * The following limitations on the permutations of the supported bit * lengths of p, q and n (written as {p, q, n}) apply: * * - {256, 256, 512} or * - {512, 512, 1024} or * - {768, 768, 1536} or * - {1024, 1024, 2048} or * - {1536, 1536, 3072} or * - {2048, 2048, 4096}. * *****************************************************************************/ typedef struct _CpaCyRsaKeyGenOpData { CpaFlatBuffer prime1P; /**< A large random prime number (p). This MUST be created by the * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048. * Limitations apply - refer to the description above for details. */ CpaFlatBuffer prime2Q; /**< A large random prime number (q). This MUST be created by the * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048. * Limitations apply - refer to the description above for details. If the * private key representation type is 2, then this pointer will be assigned * to the relevant structure member of the representation 2 private key. */ Cpa32U modulusLenInBytes; /**< The bit length of the modulus (n). This is the modulus length for * both the private and public keys. The length of the modulus N parameter * for the private key representation 1 structure and the public key * structures will be assigned to this value. References to the strength of * RSA actually refer to this bit length. Recommended minimum is 1024 bits. * Permitted lengths are: * - 512 bits (64 bytes), * - 1024 bits (128 bytes), * - 1536 bits (192 bytes), * - 2048 bits (256 bytes), * - 3072 bits (384 bytes), or * - 4096 bits (512 bytes). * Limitations apply - refer to description above for details. */ 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 is required to be generated. */ CpaFlatBuffer publicExponentE; /**< The public exponent (e). */ } CpaCyRsaKeyGenOpData; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Encryption Primitive Operation Data * @description * This structure lists the different items that are required in the * cpaCyRsaEncrypt function. As the RSA encryption primitive and * verification primitive operations are mathematically identical this * structure may also be used to perform an RSA verification primitive * operation. * When performing an RSA encryption primitive operation, the input data * is the message and the output data is the cipher text. * When performing an RSA verification primitive operation, the input data * is the signature and the output data is the message. * The client MUST allocate the memory for 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 CpaCyRsaEncryptCbFunc * callback function. * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyRsaEncrypt 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 _CpaCyRsaEncryptOpData { CpaCyRsaPublicKey *pPublicKey; /**< Pointer to the public key. */ CpaFlatBuffer inputData; /**< The input data that the RSA encryption 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. */ } CpaCyRsaEncryptOpData; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Decryption Primitive Operation Data * @description * This structure lists the different items that are required in the * cpaCyRsaDecrypt 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 CpaCyRsaDecryptCbFunc * callback function. * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyRsaDecrypt 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 _CpaCyRsaDecryptOpData { CpaCyRsaPrivateKey *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. */ } CpaCyRsaDecryptOpData; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyRsaStats64. * @description * This structure contains statistics on the RSA operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. ****************************************************************************/ typedef struct _CpaCyRsaStats { Cpa32U numRsaKeyGenRequests; /**< Total number of successful RSA key generation requests. */ Cpa32U numRsaKeyGenRequestErrors; /**< Total number of RSA key generation requests that had an error and * could not be processed. */ Cpa32U numRsaKeyGenCompleted; /**< Total number of RSA key generation operations that completed * successfully. */ Cpa32U numRsaKeyGenCompletedErrors; /**< Total number of RSA key generation operations that could not be * completed successfully due to errors. */ Cpa32U numRsaEncryptRequests; /**< Total number of successful RSA encrypt operation requests. */ Cpa32U numRsaEncryptRequestErrors; /**< Total number of RSA encrypt requests that had an error and could * not be processed. */ Cpa32U numRsaEncryptCompleted; /**< Total number of RSA encrypt operations that completed * successfully. */ Cpa32U numRsaEncryptCompletedErrors; /**< Total number of RSA encrypt operations that could not be * completed successfully due to errors. */ Cpa32U numRsaDecryptRequests; /**< Total number of successful RSA decrypt operation requests. */ Cpa32U numRsaDecryptRequestErrors; /**< Total number of RSA decrypt requests that had an error and could * not be processed. */ Cpa32U numRsaDecryptCompleted; /**< Total number of RSA decrypt operations that completed * successfully. */ Cpa32U numRsaDecryptCompletedErrors; /**< Total number of RSA decrypt operations that could not be * completed successfully due to errors. */ } CpaCyRsaStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyRsa * RSA Statistics (64-bit version). * @description * This structure contains 64-bit version of the statistics on the RSA * operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. ****************************************************************************/ typedef struct _CpaCyRsaStats64 { Cpa64U numRsaKeyGenRequests; /**< Total number of successful RSA key generation requests. */ Cpa64U numRsaKeyGenRequestErrors; /**< Total number of RSA key generation requests that had an error and * could not be processed. */ Cpa64U numRsaKeyGenCompleted; /**< Total number of RSA key generation operations that completed * successfully. */ Cpa64U numRsaKeyGenCompletedErrors; /**< Total number of RSA key generation operations that could not be * completed successfully due to errors. */ Cpa64U numRsaEncryptRequests; /**< Total number of successful RSA encrypt operation requests. */ Cpa64U numRsaEncryptRequestErrors; /**< Total number of RSA encrypt requests that had an error and could * not be processed. */ Cpa64U numRsaEncryptCompleted; /**< Total number of RSA encrypt operations that completed * successfully. */ Cpa64U numRsaEncryptCompletedErrors; /**< Total number of RSA encrypt operations that could not be * completed successfully due to errors. */ Cpa64U numRsaDecryptRequests; /**< Total number of successful RSA decrypt operation requests. */ Cpa64U numRsaDecryptRequestErrors; /**< Total number of RSA decrypt requests that had an error and could * not be processed. */ Cpa64U numRsaDecryptCompleted; /**< Total number of RSA decrypt operations that completed * successfully. */ Cpa64U numRsaDecryptCompletedErrors; /**< Total number of RSA decrypt operations that could not be * completed successfully due to errors. */ Cpa64U numKptRsaDecryptRequests; /**< Total number of successful KPT RSA decrypt operation requests. */ Cpa64U numKptRsaDecryptRequestErrors; /**< Total number of KPT RSA decrypt requests that had an error and could * not be processed. */ Cpa64U numKptRsaDecryptCompleted; /**< Total number of KPT RSA decrypt operations that completed * successfully. */ Cpa64U numKptRsaDecryptCompletedErrors; /**< Total number of KPT RSA decrypt operations that could not be * completed successfully due to errors. */ } CpaCyRsaStats64; /** ***************************************************************************** * @ingroup cpaCyRsa * Definition of the RSA key generation callback function. * * @description * This is the prototype for the RSA key generation callback function. The * callback function pointer is passed in as a parameter to the * cpaCyRsaGenKey function. It will be invoked once the request has * completed. * * @context * This callback function can be executed in a context that DOES NOT * permit sleeping to occur. * @assumptions * None * @sideEffects * None * @reentrant * No * @threadSafe * Yes * * @param[in] pCallbackTag Opaque value provided by user while making * individual function calls. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] pKeyGenOpData Structure with output params for callback. * @param[in] pPrivateKey Structure which contains pointers to the memory * into which the generated private key will be * written. * @param[in] pPublicKey Structure which contains pointers to the memory * into which the generated public key will be * written. The pointer to the public exponent (e) * that is returned in this structure is equal to * the input public exponent. * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * CpaCyRsaPrivateKey, * CpaCyRsaPublicKey, * cpaCyRsaGenKey() * *****************************************************************************/ typedef void (*CpaCyRsaKeyGenCbFunc)(void *pCallbackTag, CpaStatus status, void *pKeyGenOpData, CpaCyRsaPrivateKey *pPrivateKey, CpaCyRsaPublicKey *pPublicKey); /** ***************************************************************************** * @ingroup cpaCyRsa * Generate RSA keys. * * @description * This function will generate private and public keys for RSA as specified * in the PKCS #1 V2.1 standard. Both representation types of the private * key may be generated. * * @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] pRsaKeyGenCb Pointer to the 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] pKeyGenOpData Structure containing all the data needed to * perform the RSA key generation 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] pPrivateKey Structure which contains pointers to the memory * into which the generated private key will be * written. The client MUST allocate memory * for this structure, and for the pointers * within it, recursively; on return, these will * be populated. * @param[out] pPublicKey Structure which contains pointers to the memory * into which the generated public key will be * written. The memory for this structure and * for the modulusN parameter MUST be allocated * by the client, and will be populated on return * from the call. The field publicExponentE * is not modified or touched in any way; it is * the responsibility of the client to set this * to the same value as the corresponding * parameter on the CpaCyRsaKeyGenOpData * structure before using the key for encryption. * * @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 * When pRsaKeyGenCb is non-NULL, an asynchronous callback of type 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. * @see * CpaCyRsaKeyGenOpData, * CpaCyRsaKeyGenCbFunc, * cpaCyRsaEncrypt(), * cpaCyRsaDecrypt() * *****************************************************************************/ CpaStatus cpaCyRsaGenKey(const CpaInstanceHandle instanceHandle, const CpaCyRsaKeyGenCbFunc pRsaKeyGenCb, void *pCallbackTag, const CpaCyRsaKeyGenOpData *pKeyGenOpData, CpaCyRsaPrivateKey *pPrivateKey, CpaCyRsaPublicKey *pPublicKey); /** ***************************************************************************** * @ingroup cpaCyRsa * Perform the RSA encrypt (or verify) primitive operation on the input * data. * * @description * This function will perform an RSA encryption primitive operation on the * input data using the specified RSA public key. As the RSA encryption * primitive and verification primitive operations are mathematically * identical this function may also be used to perform an RSA verification * 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] pRsaEncryptCb 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] pEncryptOpData Structure containing all the data needed to * perform the RSA encryption 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 encryption 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. * * @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 * When pRsaEncryptCb is non-NULL an asynchronous callback of type 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. * @see * CpaCyGenFlatBufCbFunc * CpaCyRsaEncryptOpData * cpaCyRsaGenKey() * cpaCyRsaDecrypt() * *****************************************************************************/ CpaStatus cpaCyRsaEncrypt(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pRsaEncryptCb, void *pCallbackTag, const CpaCyRsaEncryptOpData *pEncryptOpData, CpaFlatBuffer *pOutputData); /** ***************************************************************************** * @ingroup cpaCyRsa * Perform the RSA decrypt (or sign) primitive operation on the input * data. * * @description * This function will perform an RSA decryption primitive operation on the * input data using the specified RSA private key. 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. * * @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 * 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. * @see * CpaCyRsaDecryptOpData, * CpaCyGenFlatBufCbFunc, * cpaCyRsaGenKey(), * cpaCyRsaEncrypt() * *****************************************************************************/ CpaStatus cpaCyRsaDecrypt(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pRsaDecryptCb, void *pCallbackTag, const CpaCyRsaDecryptOpData *pDecryptOpData, CpaFlatBuffer * pOutputData); /** ***************************************************************************** * @ingroup cpaCyRsa * Query statistics for a specific RSA instance. * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyRsaQueryStats64(). * * @description * This function will query a specific instance for RSA statistics. The * user MUST allocate the CpaCyRsaStats structure and pass the * reference to that into this function call. This function will write the * statistic results into the passed in CpaCyRsaStats structure. * * Note: statistics returned by this function do not interrupt current data * processing and as such can be slightly out of sync with operations that * are in progress during the statistics retrieval process. * * @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 Instance handle. * @param[out] pRsaStats Pointer to memory into which the statistics * will be written. * * @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 Function is not supported. * * @pre * Component has been initialized. * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * @see * CpaCyRsaStats * *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyRsaQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCyRsaStats *pRsaStats); /** ***************************************************************************** * @ingroup cpaCyRsa * Query statistics (64-bit version) for a specific RSA instance. * * @description * This function will query a specific instance for RSA statistics. The * user MUST allocate the CpaCyRsaStats64 structure and pass the * reference to that into this function call. This function will write the * statistic results into the passed in CpaCyRsaStats64 structure. * * Note: statistics returned by this function do not interrupt current data * processing and as such can be slightly out of sync with operations that * are in progress during the statistics retrieval process. * * @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 Instance handle. * @param[out] pRsaStats Pointer to memory into which the statistics * will be written. * * @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 Function is not supported. * * @pre * Component has been initialized. * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * @see * CpaCyRsaStats64 *****************************************************************************/ CpaStatus cpaCyRsaQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyRsaStats64 *pRsaStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_RSA_H */