/* SPDX-License-Identifier: BSD-3-Clause */ /* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_dsa.h * * @defgroup cpaCyDsa Digital Signature Algorithm (DSA) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) Digital Signature Algorithm (DSA) operations. * * Support is provided for FIPS PUB 186-2 with Change Notice 1 * specification, and optionally for FIPS PUB 186-3. If an * implementation does not support FIPS PUB 186-3, then the * corresponding functions may return a status of @ref * CPA_STATUS_FAIL. * * Support for FIPS PUB 186-2 with Change Notice 1 implies supporting * the following choice for the pair L and N: * - L = 1024, N = 160 * * Support for FIPS PUB 186-3 implies supporting the following choices * for the pair L and N: * * - L = 1024, N = 160 * - L = 2048, N = 224 * - L = 2048, N = 256 * - L = 3072, N = 256 * * Only the modular math aspects of DSA parameter generation and message * signature generation and verification are implemented here. For full * DSA support, this DSA API SHOULD be used in conjunction with other * parts of this overall Cryptographic API. In particular the Symmetric * functions (for hashing), the Random Number Generation functions, and * the Prime Number Test functions will be required. * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). *****************************************************************************/ #ifndef CPA_CY_DSA_H #define CPA_CY_DSA_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyDsa * DSA P Parameter Generation Operation Data. * @description * This structure contains the operation data for the cpaCyDsaGenPParam * 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. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. X.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaGenPParam * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaGenPParam() * *****************************************************************************/ typedef struct _CpaCyDsaPParamGenOpData { CpaFlatBuffer X; /**< 2^(L-1) <= X < 2^L (from FIPS 186-3) */ CpaFlatBuffer Q; /**< DSA group parameter q */ } CpaCyDsaPParamGenOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA G Parameter Generation Operation Data. * @description * This structure contains the operation data for the cpaCyDsaGenGParam * 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. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. P.pData[0] = MSB. * * All numbers MUST be stored in big-endian order. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaGenGParam * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaGenGParam() * *****************************************************************************/ typedef struct _CpaCyDsaGParamGenOpData { CpaFlatBuffer P; /**< DSA group parameter p */ CpaFlatBuffer Q; /**< DSA group parameter q */ CpaFlatBuffer H; /**< any integer with 1 < h < p - 1 */ } CpaCyDsaGParamGenOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA Y Parameter Generation Operation Data. * @description * This structure contains the operation data for the cpaCyDsaGenYParam * 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. * * For optimal performance all data SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. P.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaGenYParam * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaGenYParam() * *****************************************************************************/ typedef struct _CpaCyDsaYParamGenOpData { CpaFlatBuffer P; /**< DSA group parameter p */ CpaFlatBuffer G; /**< DSA group parameter g */ CpaFlatBuffer X; /**< DSA private key x */ } CpaCyDsaYParamGenOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA R Sign Operation Data. * @description * This structure contains the operation data for the cpaCyDsaSignR * 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. * * For optimal performance all data SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. P.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaSignR * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaSignR() * *****************************************************************************/ typedef struct _CpaCyDsaRSignOpData { CpaFlatBuffer P; /**< DSA group parameter p */ CpaFlatBuffer Q; /**< DSA group parameter q */ CpaFlatBuffer G; /**< DSA group parameter g */ CpaFlatBuffer K; /**< DSA secret parameter k for signing */ } CpaCyDsaRSignOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA S Sign Operation Data. * @description * This structure contains the operation data for the cpaCyDsaSignS * 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. * * For optimal performance all data SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. Q.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaSignS * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaSignS() * *****************************************************************************/ typedef struct _CpaCyDsaSSignOpData { CpaFlatBuffer Q; /**< DSA group parameter q */ CpaFlatBuffer X; /**< DSA private key x */ CpaFlatBuffer K; /**< DSA secret parameter k for signing */ CpaFlatBuffer R; /**< DSA message signature r */ CpaFlatBuffer Z; /**< The leftmost min(N, outlen) bits of Hash(M), where: * - N is the bit length of q * - outlen is the bit length of the hash function output block * - M is the message to be signed */ } CpaCyDsaSSignOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA R & S Sign Operation Data. * @description * This structure contains the operation data for the cpaCyDsaSignRS * 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. * * For optimal performance all data SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. P.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaSignRS * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaSignRS() * *****************************************************************************/ typedef struct _CpaCyDsaRSSignOpData { CpaFlatBuffer P; /**< DSA group parameter p */ CpaFlatBuffer Q; /**< DSA group parameter q */ CpaFlatBuffer G; /**< DSA group parameter g */ CpaFlatBuffer X; /**< DSA private key x */ CpaFlatBuffer K; /**< DSA secret parameter k for signing */ CpaFlatBuffer Z; /**< The leftmost min(N, outlen) bits of Hash(M), where: * - N is the bit length of q * - outlen is the bit length of the hash function output block * - M is the message to be signed */ } CpaCyDsaRSSignOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * DSA Verify Operation Data. * @description * This structure contains the operation data for the cpaCyDsaVerify * 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. * * For optimal performance all data SHOULD be 8-byte aligned. * * All values in this structure are required to be in Most Significant Byte * first order, e.g. P.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyDsaVerify * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyDsaVerify() * *****************************************************************************/ typedef struct _CpaCyDsaVerifyOpData { CpaFlatBuffer P; /**< DSA group parameter p */ CpaFlatBuffer Q; /**< DSA group parameter q */ CpaFlatBuffer G; /**< DSA group parameter g */ CpaFlatBuffer Y; /**< DSA public key y */ CpaFlatBuffer Z; /**< The leftmost min(N, outlen) bits of Hash(M'), where: * - N is the bit length of q * - outlen is the bit length of the hash function output block * - M is the message to be signed */ CpaFlatBuffer R; /**< DSA message signature r */ CpaFlatBuffer S; /**< DSA message signature s */ } CpaCyDsaVerifyOpData; /** ***************************************************************************** * @ingroup cpaCyDsa * Cryptographic DSA Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyDsaStats64. * @description * This structure contains statistics on the Cryptographic DSA * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. ****************************************************************************/ typedef struct _CpaCyDsaStats { Cpa32U numDsaPParamGenRequests; /**< Total number of successful DSA P parameter generation requests. */ Cpa32U numDsaPParamGenRequestErrors; /**< Total number of DSA P parameter generation requests that had an * error and could not be processed. */ Cpa32U numDsaPParamGenCompleted; /**< Total number of DSA P parameter generation operations that * completed successfully. */ Cpa32U numDsaPParamGenCompletedErrors; /**< Total number of DSA P parameter generation operations that could * not be completed successfully due to errors. */ Cpa32U numDsaGParamGenRequests; /**< Total number of successful DSA G parameter generation requests. */ Cpa32U numDsaGParamGenRequestErrors; /**< Total number of DSA G parameter generation requests that had an * error and could not be processed. */ Cpa32U numDsaGParamGenCompleted; /**< Total number of DSA G parameter generation operations that * completed successfully. */ Cpa32U numDsaGParamGenCompletedErrors; /**< Total number of DSA G parameter generation operations that could * not be completed successfully due to errors. */ Cpa32U numDsaYParamGenRequests; /**< Total number of successful DSA Y parameter generation requests. */ Cpa32U numDsaYParamGenRequestErrors; /**< Total number of DSA Y parameter generation requests that had an * error and could not be processed. */ Cpa32U numDsaYParamGenCompleted; /**< Total number of DSA Y parameter generation operations that * completed successfully. */ Cpa32U numDsaYParamGenCompletedErrors; /**< Total number of DSA Y parameter generation operations that could * not be completed successfully due to errors. */ Cpa32U numDsaRSignRequests; /**< Total number of successful DSA R sign generation requests. */ Cpa32U numDsaRSignRequestErrors; /**< Total number of DSA R sign requests that had an error and could * not be processed. */ Cpa32U numDsaRSignCompleted; /**< Total number of DSA R sign operations that completed * successfully. */ Cpa32U numDsaRSignCompletedErrors; /**< Total number of DSA R sign operations that could not be completed * successfully due to errors. */ Cpa32U numDsaSSignRequests; /**< Total number of successful DSA S sign generation requests. */ Cpa32U numDsaSSignRequestErrors; /**< Total number of DSA S sign requests that had an error and could * not be processed. */ Cpa32U numDsaSSignCompleted; /**< Total number of DSA S sign operations that completed * successfully. */ Cpa32U numDsaSSignCompletedErrors; /**< Total number of DSA S sign operations that could not be completed * successfully due to errors. */ Cpa32U numDsaRSSignRequests; /**< Total number of successful DSA RS sign generation requests. */ Cpa32U numDsaRSSignRequestErrors; /**< Total number of DSA RS sign requests that had an error and could * not be processed. */ Cpa32U numDsaRSSignCompleted; /**< Total number of DSA RS sign operations that completed * successfully. */ Cpa32U numDsaRSSignCompletedErrors; /**< Total number of DSA RS sign operations that could not be completed * successfully due to errors. */ Cpa32U numDsaVerifyRequests; /**< Total number of successful DSA verify generation requests. */ Cpa32U numDsaVerifyRequestErrors; /**< Total number of DSA verify requests that had an error and could * not be processed. */ Cpa32U numDsaVerifyCompleted; /**< Total number of DSA verify operations that completed * successfully. */ Cpa32U numDsaVerifyCompletedErrors; /**< Total number of DSA verify operations that could not be completed * successfully due to errors. */ Cpa32U numDsaVerifyFailures; /**< Total number of DSA verify operations that executed successfully * but the outcome of the test was that the verification failed. * Note that this does not indicate an error. */ } CpaCyDsaStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyDsa * Cryptographic DSA Statistics (64-bit version). * @description * This structure contains 64-bit version of the statistics on the * Cryptographic DSA operations. * Statistics are set to zero when the component is * initialized, and are collected per instance. ****************************************************************************/ typedef struct _CpaCyDsaStats64 { Cpa64U numDsaPParamGenRequests; /**< Total number of successful DSA P parameter generation requests. */ Cpa64U numDsaPParamGenRequestErrors; /**< Total number of DSA P parameter generation requests that had an * error and could not be processed. */ Cpa64U numDsaPParamGenCompleted; /**< Total number of DSA P parameter generation operations that * completed successfully. */ Cpa64U numDsaPParamGenCompletedErrors; /**< Total number of DSA P parameter generation operations that could * not be completed successfully due to errors. */ Cpa64U numDsaGParamGenRequests; /**< Total number of successful DSA G parameter generation requests. */ Cpa64U numDsaGParamGenRequestErrors; /**< Total number of DSA G parameter generation requests that had an * error and could not be processed. */ Cpa64U numDsaGParamGenCompleted; /**< Total number of DSA G parameter generation operations that * completed successfully. */ Cpa64U numDsaGParamGenCompletedErrors; /**< Total number of DSA G parameter generation operations that could * not be completed successfully due to errors. */ Cpa64U numDsaYParamGenRequests; /**< Total number of successful DSA Y parameter generation requests. */ Cpa64U numDsaYParamGenRequestErrors; /**< Total number of DSA Y parameter generation requests that had an * error and could not be processed. */ Cpa64U numDsaYParamGenCompleted; /**< Total number of DSA Y parameter generation operations that * completed successfully. */ Cpa64U numDsaYParamGenCompletedErrors; /**< Total number of DSA Y parameter generation operations that could * not be completed successfully due to errors. */ Cpa64U numDsaRSignRequests; /**< Total number of successful DSA R sign generation requests. */ Cpa64U numDsaRSignRequestErrors; /**< Total number of DSA R sign requests that had an error and could * not be processed. */ Cpa64U numDsaRSignCompleted; /**< Total number of DSA R sign operations that completed * successfully. */ Cpa64U numDsaRSignCompletedErrors; /**< Total number of DSA R sign operations that could not be completed * successfully due to errors. */ Cpa64U numDsaSSignRequests; /**< Total number of successful DSA S sign generation requests. */ Cpa64U numDsaSSignRequestErrors; /**< Total number of DSA S sign requests that had an error and could * not be processed. */ Cpa64U numDsaSSignCompleted; /**< Total number of DSA S sign operations that completed * successfully. */ Cpa64U numDsaSSignCompletedErrors; /**< Total number of DSA S sign operations that could not be completed * successfully due to errors. */ Cpa64U numDsaRSSignRequests; /**< Total number of successful DSA RS sign generation requests. */ Cpa64U numDsaRSSignRequestErrors; /**< Total number of DSA RS sign requests that had an error and could * not be processed. */ Cpa64U numDsaRSSignCompleted; /**< Total number of DSA RS sign operations that completed * successfully. */ Cpa64U numDsaRSSignCompletedErrors; /**< Total number of DSA RS sign operations that could not be completed * successfully due to errors. */ Cpa64U numDsaVerifyRequests; /**< Total number of successful DSA verify generation requests. */ Cpa64U numDsaVerifyRequestErrors; /**< Total number of DSA verify requests that had an error and could * not be processed. */ Cpa64U numDsaVerifyCompleted; /**< Total number of DSA verify operations that completed * successfully. */ Cpa64U numDsaVerifyCompletedErrors; /**< Total number of DSA verify operations that could not be completed * successfully due to errors. */ Cpa64U numDsaVerifyFailures; /**< Total number of DSA verify operations that executed successfully * but the outcome of the test was that the verification failed. * Note that this does not indicate an error. */ } CpaCyDsaStats64; /** ***************************************************************************** * @ingroup cpaCyDsa * Definition of a generic callback function invoked for a number of the * DSA API functions.. * * @description * This is the prototype for the cpaCyDsaGenCbFunc callback function. * * @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 User-supplied value to help identify request. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] pOpData Opaque pointer to Operation data supplied in * request. * @param[in] protocolStatus The result passes/fails the DSA protocol * related checks. * @param[in] pOut Output data from the request. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyDsaGenPParam() * cpaCyDsaGenGParam() * cpaCyDsaSignR() * cpaCyDsaSignS() * *****************************************************************************/ typedef void (*CpaCyDsaGenCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean protocolStatus, CpaFlatBuffer *pOut); /** ***************************************************************************** * @ingroup cpaCyDsa * Definition of callback function invoked for cpaCyDsaSignRS * requests. * * @description * This is the prototype for the cpaCyDsaSignRS callback function, which * will provide the DSA message signature r and s parameters. * * @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 User-supplied value to help identify request. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] pOpData Operation data pointer supplied in request. * @param[in] protocolStatus The result passes/fails the DSA protocol * related checks. * @param[in] pR DSA message signature r. * @param[in] pS DSA message signature s. * * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyDsaSignRS() * *****************************************************************************/ typedef void (*CpaCyDsaRSSignCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean protocolStatus, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyDsa * Definition of callback function invoked for cpaCyDsaVerify * requests. * * @description * This is the prototype for the cpaCyDsaVerify callback function. * * @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 User-supplied value to help identify request. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] pOpData Operation data pointer supplied in request. * @param[in] verifyStatus The verification passed or failed. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyDsaVerify() * *****************************************************************************/ typedef void (*CpaCyDsaVerifyCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean verifyStatus); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA P Parameter. * * @description * * This function performs FIPS 186-3 Appendix A.1.1.2 steps 11.4 and 11.5, * and part of step 11.7: * * 11.4. c = X mod 2q. * 11.5. p = X - (c - 1). * 11.7. Test whether or not p is prime as specified in Appendix C.3. * [Note that a GCD test against ~1400 small primes is performed * on p to eliminate ~94% of composites - this is NOT a "robust" * primality test, as specified in Appendix C.3.] * * The protocol status, returned in the callback function as parameter * protocolStatus (or, in the case of synchronous invocation, in the * parameter *pProtocolStatus) is used to indicate whether the value p is * in the right range and has passed the limited primality test. * * Specifically, (protocolStatus == CPA_TRUE) means p is in the right range * and SHOULD be subjected to a robust primality test as specified in * FIPS 186-3 Appendix C.3 (for example, 40 rounds of Miller-Rabin). * Meanwhile, (protocolStatus == CPA_FALSE) means p is either composite, * or p < 2^(L-1), in which case the value of p gets set to zero. * * @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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pP Candidate for DSA parameter p, p odd and * 2^(L-1) < p < X * 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. * @post * None * @note * When pCb is non-NULL an asynchronous callback of type * CpaCyDsaPParamGenCbFunc is generated in response to this * function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaPParamGenOpData, * CpaCyDsaGenCbFunc * *****************************************************************************/ CpaStatus cpaCyDsaGenPParam(const CpaInstanceHandle instanceHandle, const CpaCyDsaGenCbFunc pCb, void * pCallbackTag, const CpaCyDsaPParamGenOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pP); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA G Parameter. * * @description * This function performs FIPS 186-3 Appendix A.2.1, steps 1 and 3, * and part of step 4: * * 1. e = (p - 1)/q. * 3. Set g = h^e mod p. * 4. If (g = 1), then go to step 2. * Here, the implementation will check for g == 1, and return * status accordingly. * * * The protocol status, returned in the callback function as parameter * protocolStatus (or, in the case of synchronous invocation, in the * parameter *pProtocolStatus) is used to indicate whether the value g is * acceptable. * * Specifically, (protocolStatus == CPA_TRUE) means g is acceptable. * Meanwhile, (protocolStatus == CPA_FALSE) means g == 1, so a * different value of h SHOULD be used to generate another value of g. * * @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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pG g = h^((p-1)/q) mod p. * 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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaGParamGenCbFunc is generated in response to this * function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaGParamGenOpData, * CpaCyDsaGenCbFunc * *****************************************************************************/ CpaStatus cpaCyDsaGenGParam(const CpaInstanceHandle instanceHandle, const CpaCyDsaGenCbFunc pCb, void *pCallbackTag, const CpaCyDsaGParamGenOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pG); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA Y Parameter. * * @description * * This function performs modular exponentiation to generate y as * described in FIPS 186-3 section 4.1: * y = g^x mod p * * @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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pY y = g^x mod p* * 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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaYParamGenCbFunc is generated in response to this * function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaYParamGenOpData, * CpaCyDsaGenCbFunc * *****************************************************************************/ CpaStatus cpaCyDsaGenYParam(const CpaInstanceHandle instanceHandle, const CpaCyDsaGenCbFunc pCb, void *pCallbackTag, const CpaCyDsaYParamGenOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pY); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA R Signature. * * @description * This function generates the DSA R signature as described in FIPS 186-3 * Section 4.6: * r = (g^k mod p) mod q * * The protocol status, returned in the callback function as parameter * protocolStatus (or, in the case of synchronous invocation, in the * parameter *pProtocolStatus) is used to indicate whether the value r == 0. * * Specifically, (protocolStatus == CPA_TRUE) means r != 0, while * (protocolStatus == CPA_FALSE) means r == 0. * * Generation of signature r does not depend on the content of the message * being signed, so this operation can be done in advance for different * values of k. Then once each message becomes available only the * signature s needs to 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] 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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pR DSA message signature r. * 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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaRSignCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaRSignOpData, * CpaCyDsaGenCbFunc, * cpaCyDsaSignS(), * cpaCyDsaSignRS() * *****************************************************************************/ CpaStatus cpaCyDsaSignR(const CpaInstanceHandle instanceHandle, const CpaCyDsaGenCbFunc pCb, void *pCallbackTag, const CpaCyDsaRSignOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pR); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA S Signature. * * @description * This function generates the DSA S signature as described in FIPS 186-3 * Section 4.6: * s = (k^-1(z + xr)) mod q * * Here, z = the leftmost min(N, outlen) bits of Hash(M). This function * does not perform the SHA digest; z is computed by the caller and * passed as a parameter in the pOpData field. * * The protocol status, returned in the callback function as parameter * protocolStatus (or, in the case of synchronous invocation, in the * parameter *pProtocolStatus) is used to indicate whether the value s == 0. * * Specifically, (protocolStatus == CPA_TRUE) means s != 0, while * (protocolStatus == CPA_FALSE) means s == 0. * * If signature r has been generated in advance, then this function can be * used to generate the signature s once the message becomes available. * * @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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pS DSA message signature s. * 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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaSSignCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaSSignOpData, * CpaCyDsaGenCbFunc, * cpaCyDsaSignR(), * cpaCyDsaSignRS() * *****************************************************************************/ CpaStatus cpaCyDsaSignS(const CpaInstanceHandle instanceHandle, const CpaCyDsaGenCbFunc pCb, void *pCallbackTag, const CpaCyDsaSSignOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyDsa * Generate DSA R and S Signatures. * * @description * This function generates the DSA R and S signatures as described in * FIPS 186-3 Section 4.6: * * r = (g^k mod p) mod q * s = (k^-1(z + xr)) mod q * * Here, z = the leftmost min(N, outlen) bits of Hash(M). This function * does not perform the SHA digest; z is computed by the caller and * passed as a parameter in the pOpData field. * * The protocol status, returned in the callback function as parameter * protocolStatus (or, in the case of synchronous invocation, in the * parameter *pProtocolStatus) is used to indicate whether either of * the values r or s are zero. * * Specifically, (protocolStatus == CPA_TRUE) means neither is zero (i.e. * (r != 0) && (s != 0)), while (protocolStatus == CPA_FALSE) means that at * least one of r or s is zero (i.e. (r == 0) || (s == 0)). * * @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] pProtocolStatus The result passes/fails the DSA protocol * related checks. * @param[out] pR DSA message signature r. * @param[out] pS DSA message signature s. * * @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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaRSSignCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaRSSignOpData, * CpaCyDsaRSSignCbFunc, * cpaCyDsaSignR(), * cpaCyDsaSignS() * *****************************************************************************/ CpaStatus cpaCyDsaSignRS(const CpaInstanceHandle instanceHandle, const CpaCyDsaRSSignCbFunc pCb, void *pCallbackTag, const CpaCyDsaRSSignOpData *pOpData, CpaBoolean *pProtocolStatus, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyDsa * Verify DSA R and S signatures. * * @description * This function performs FIPS 186-3 Section 4.7: * w = (s')^-1 mod q * u1 = (zw) mod q * u2 = ((r')w) mod q * v = (((g)^u1 (y)^u2) mod p) mod q * * Here, z = the leftmost min(N, outlen) bits of Hash(M'). This function * does not perform the SHA digest; z is computed by the caller and * passed as a parameter in the pOpData field. * * A response status of ok (verifyStatus == CPA_TRUE) means v = r'. * A response status of not ok (verifyStatus == CPA_FALSE) means v != r'. * * @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] pVerifyStatus The verification passed or failed. * * @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 pCb is non-NULL an asynchronous callback of type * CpaCyDsaVerifyCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyDsaVerifyOpData, * CpaCyDsaVerifyCbFunc * *****************************************************************************/ CpaStatus cpaCyDsaVerify(const CpaInstanceHandle instanceHandle, const CpaCyDsaVerifyCbFunc pCb, void *pCallbackTag, const CpaCyDsaVerifyOpData *pOpData, CpaBoolean *pVerifyStatus); /** ***************************************************************************** * @ingroup cpaCyDsa * Query statistics for a specific DSA instance. * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyDsaQueryStats64(). * * @description * This function will query a specific instance of the DSA implementation * for statistics. The user MUST allocate the CpaCyDsaStats structure * and pass the reference to that structure into this function call. This * function writes the statistic results into the passed in * CpaCyDsaStats 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] pDsaStats 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 * CpaCyDsaStats *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyDsaQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCyDsaStats *pDsaStats); /** ***************************************************************************** * @ingroup cpaCyDsa * Query 64-bit statistics for a specific DSA instance. * * @description * This function will query a specific instance of the DSA implementation * for 64-bit statistics. The user MUST allocate the CpaCyDsaStats64 * structure and pass the reference to that structure into this function. * This function writes the statistic results into the passed in * CpaCyDsaStats64 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] pDsaStats 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 * CpaCyDsaStats *****************************************************************************/ CpaStatus cpaCyDsaQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyDsaStats64 *pDsaStats); /*****************************************************************************/ #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_DSA_H */
