diff --git a/sys/dev/qat/qat_api/include/cpa.h b/sys/dev/qat/qat_api/include/cpa.h index f91de67caf5a..a3e32e4ef1d4 100644 --- a/sys/dev/qat/qat_api/include/cpa.h +++ b/sys/dev/qat/qat_api/include/cpa.h @@ -1,799 +1,766 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa.h * * @defgroup cpa CPA API * * @description * This is the top level API definition for Intel(R) QuickAssist Technology. * It contains structures, data types and definitions that are common * across the interface. * *****************************************************************************/ /** ***************************************************************************** * @defgroup cpa_BaseDataTypes Base Data Types * @file cpa.h * * @ingroup cpa * * @description * The base data types for the Intel CPA API. * *****************************************************************************/ #ifndef CPA_H #define CPA_H #ifdef __cplusplus extern "C" { #endif #include "cpa_types.h" /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance handle type. * * @description * Handle used to uniquely identify an instance. * * @note * Where only a single instantiation exists this field may be set to * @ref CPA_INSTANCE_HANDLE_SINGLE. * *****************************************************************************/ typedef void * CpaInstanceHandle; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Default instantiation handle value where there is only a single instance * * @description * Used as an instance handle value where only one instance exists. * *****************************************************************************/ #define CPA_INSTANCE_HANDLE_SINGLE ((CpaInstanceHandle)0) /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Physical memory address. * @description * Type for physical memory addresses. *****************************************************************************/ typedef Cpa64U CpaPhysicalAddr; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Virtual to physical address conversion routine. * * @description * This function is used to convert virtual addresses to physical * addresses. * * @context * The function shall not be called in an interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] pVirtualAddr Virtual address to be converted. * * @return * Returns the corresponding physical address. * On error, the value NULL is returned. * * @post * None * @see * None * *****************************************************************************/ typedef CpaPhysicalAddr (*CpaVirtualToPhysical)(void * pVirtualAddr); /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Flat buffer structure containing a pointer and length member. * * @description * A flat buffer structure. The data pointer, pData, is a virtual address. * An API instance may require the actual data to be in contiguous * physical memory as determined by @ref CpaInstanceInfo2. * *****************************************************************************/ typedef struct _CpaFlatBuffer { Cpa32U dataLenInBytes; /**< Data length specified in bytes. * When used as an input parameter to a function, the length specifies * the current length of the buffer. * When used as an output parameter to a function, the length passed in * specifies the maximum length of the buffer on return (i.e. the allocated * length). The implementation will not write past this length. On return, * the length is always unchanged. */ Cpa8U *pData; /**< The data pointer is a virtual address, however the actual data pointed * to is required to be in contiguous physical memory unless the field requiresPhysicallyContiguousMemory in CpaInstanceInfo2 is false. */ } CpaFlatBuffer; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Scatter/Gather buffer list containing an array of flat buffers. * * @description * A scatter/gather buffer list structure. This buffer structure is * typically used to represent a region of memory which is not * physically contiguous, by describing it as a collection of * buffers, each of which is physically contiguous. * * @note * The memory for the pPrivateMetaData member must be allocated * by the client as physically contiguous memory. When allocating * memory for pPrivateMetaData, a call to the corresponding * BufferListGetMetaSize function (e.g. cpaCyBufferListGetMetaSize) * MUST be made to determine the size of the Meta Data Buffer. The * returned size (in bytes) may then be passed in a memory allocation * routine to allocate the pPrivateMetaData memory. *****************************************************************************/ typedef struct _CpaBufferList { Cpa32U numBuffers; /**< Number of buffers in the list */ CpaFlatBuffer *pBuffers; /**< Pointer to an unbounded array containing the number of CpaFlatBuffers * defined by numBuffers */ void *pUserData; /**< This is an opaque field that is not read or modified internally. */ void *pPrivateMetaData; /**< Private representation of this buffer list. The memory for this * buffer needs to be allocated by the client as contiguous data. * The amount of memory required is returned with a call to * the corresponding BufferListGetMetaSize function. If that function * returns a size of zero then no memory needs to be allocated, and this * parameter can be NULL. */ } CpaBufferList; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Flat buffer structure with physical address. * * @description * Functions taking this structure do not need to do any virtual to * physical address translation before writing the buffer to hardware. *****************************************************************************/ typedef struct _CpaPhysFlatBuffer { Cpa32U dataLenInBytes; /**< Data length specified in bytes. * When used as an input parameter to a function, the length specifies * the current length of the buffer. * When used as an output parameter to a function, the length passed in * specifies the maximum length of the buffer on return (i.e. the allocated * length). The implementation will not write past this length. On return, * the length is always unchanged. */ Cpa32U reserved; /**< Reserved for alignment */ CpaPhysicalAddr bufferPhysAddr; /**< The physical address at which the data resides. The data pointed * to is required to be in contiguous physical memory. */ } CpaPhysFlatBuffer; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Scatter/gather list containing an array of flat buffers with * physical addresses. * * @description * Similar to @ref CpaBufferList, this buffer structure is typically * used to represent a region of memory which is not physically * contiguous, by describing it as a collection of buffers, each of * which is physically contiguous. The difference is that, in this * case, the individual "flat" buffers are represented using * physical, rather than virtual, addresses. *****************************************************************************/ typedef struct _CpaPhysBufferList { Cpa64U reserved0; /**< Reserved for internal usage */ Cpa32U numBuffers; /**< Number of buffers in the list */ Cpa32U reserved1; /**< Reserved for alignment */ CpaPhysFlatBuffer flatBuffers[]; /**< Array of flat buffer structures, of size numBuffers */ } CpaPhysBufferList; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Special value which can be taken by length fields on some of the * "data plane" APIs to indicate that the buffer in question is of * type CpaPhysBufferList, rather than simply an array of bytes. ****************************************************************************/ #define CPA_DP_BUFLIST ((Cpa32U)0xFFFFFFFF) /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * API status value type definition * * @description * This type definition is used for the return values used in all the * API functions. Common values are defined, for example see * @ref CPA_STATUS_SUCCESS, @ref CPA_STATUS_FAIL, etc. *****************************************************************************/ typedef Cpa32S CpaStatus; #define CPA_STATUS_SUCCESS (0) /**< * @ingroup cpa_BaseDataTypes * Success status value. */ #define CPA_STATUS_FAIL (-1) /**< * @ingroup cpa_BaseDataTypes * Fail status value. */ #define CPA_STATUS_RETRY (-2) /**< * @ingroup cpa_BaseDataTypes * Retry status value. */ #define CPA_STATUS_RESOURCE (-3) /**< * @ingroup cpa_BaseDataTypes * The resource that has been requested is unavailable. Refer * to relevant sections of the API for specifics on what the suggested * course of action is. */ #define CPA_STATUS_INVALID_PARAM (-4) /**< * @ingroup cpa_BaseDataTypes * Invalid parameter has been passed in. */ #define CPA_STATUS_FATAL (-5) /**< * @ingroup cpa_BaseDataTypes * A serious error has occurred. Recommended course of action * is to shutdown and restart the component. */ #define CPA_STATUS_UNSUPPORTED (-6) /**< * @ingroup cpa_BaseDataTypes * The function is not supported, at least not with the specific * parameters supplied. This may be because a particular * capability is not supported by the current implementation. */ #define CPA_STATUS_RESTARTING (-7) /**< * @ingroup cpa_BaseDataTypes * The API implementation is restarting. This may be reported if, for example, * a hardware implementation is undergoing a reset. Recommended course of * action is to retry the request. */ /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * API status string type definition * @description * This type definition is used for the generic status text strings * provided by cpaXxGetStatusText API functions. Common values are * defined, for example see @ref CPA_STATUS_STR_SUCCESS, * @ref CPA_STATUS_FAIL, etc., as well as the maximum size * @ref CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. *****************************************************************************/ #define CPA_STATUS_MAX_STR_LENGTH_IN_BYTES (255) /**< * @ingroup cpa_BaseDataTypes * Maximum length of the Overall Status String (including generic and specific * strings returned by calls to cpaXxGetStatusText) */ #define CPA_STATUS_STR_SUCCESS ("Operation was successful:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_SUCCESS. */ #define CPA_STATUS_STR_FAIL ("General or unspecified error occurred:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_FAIL. */ #define CPA_STATUS_STR_RETRY ("Recoverable error occurred:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_RETRY. */ #define CPA_STATUS_STR_RESOURCE ("Required resource unavailable:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_RESOURCE. */ #define CPA_STATUS_STR_INVALID_PARAM ("Invalid parameter supplied:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_INVALID_PARAM. */ #define CPA_STATUS_STR_FATAL ("Fatal error has occurred:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_FATAL. */ #define CPA_STATUS_STR_UNSUPPORTED ("Operation not supported:") /**< * @ingroup cpa_BaseDataTypes * Status string for @ref CPA_STATUS_UNSUPPORTED. */ /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance Types * * @deprecated * As of v1.3 of the Crypto API, this enum has been deprecated, * replaced by @ref CpaAccelerationServiceType. * * @description * Enumeration of the different instance types. * *****************************************************************************/ typedef enum _CpaInstanceType { CPA_INSTANCE_TYPE_CRYPTO = 0, /**< Cryptographic instance type */ CPA_INSTANCE_TYPE_DATA_COMPRESSION, /**< Data compression instance type */ CPA_INSTANCE_TYPE_RAID, /**< RAID instance type */ CPA_INSTANCE_TYPE_XML, /**< XML instance type */ CPA_INSTANCE_TYPE_REGEX /**< Regular Expression instance type */ } CpaInstanceType CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Service Type * @description * Enumeration of the different service types. * *****************************************************************************/ typedef enum _CpaAccelerationServiceType { CPA_ACC_SVC_TYPE_CRYPTO = CPA_INSTANCE_TYPE_CRYPTO, /**< Cryptography */ CPA_ACC_SVC_TYPE_DATA_COMPRESSION = CPA_INSTANCE_TYPE_DATA_COMPRESSION, /**< Data Compression */ CPA_ACC_SVC_TYPE_PATTERN_MATCH = CPA_INSTANCE_TYPE_REGEX, /**< Pattern Match */ CPA_ACC_SVC_TYPE_RAID = CPA_INSTANCE_TYPE_RAID, /**< RAID */ CPA_ACC_SVC_TYPE_XML = CPA_INSTANCE_TYPE_XML, /**< XML */ CPA_ACC_SVC_TYPE_VIDEO_ANALYTICS, /**< Video Analytics */ CPA_ACC_SVC_TYPE_CRYPTO_ASYM, /**< Cryptography - Asymmetric service */ CPA_ACC_SVC_TYPE_CRYPTO_SYM /**< Cryptography - Symmetric service */ } CpaAccelerationServiceType; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance State * * @deprecated * As of v1.3 of the Crypto API, this enum has been deprecated, * replaced by @ref CpaOperationalState. * * @description * Enumeration of the different instance states that are possible. * *****************************************************************************/ typedef enum _CpaInstanceState { CPA_INSTANCE_STATE_INITIALISED = 0, /**< Instance is in the initialized state and ready for use. */ CPA_INSTANCE_STATE_SHUTDOWN /**< Instance is in the shutdown state and not available for use. */ } CpaInstanceState CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance operational state * @description * Enumeration of the different operational states that are possible. * *****************************************************************************/ typedef enum _CpaOperationalState { CPA_OPER_STATE_DOWN= 0, /**< Instance is not available for use. May not yet be initialized, * or stopped. */ CPA_OPER_STATE_UP /**< Instance is available for use. Has been initialized and started. */ } CpaOperationalState; #define CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 64 /**< * @ingroup cpa_BaseDataTypes * Maximum instance info name string length in bytes */ #define CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES 128 /**< * @ingroup cpa_BaseDataTypes * Maximum instance info id string length in bytes */ #define CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES 64 /**< * @ingroup cpa_BaseDataTypes * Maximum instance info version string length in bytes */ /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance Info Structure * * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by CpaInstanceInfo2. * * @description * Structure that contains the information to describe the instance. * *****************************************************************************/ typedef struct _CpaInstanceInfo { enum _CpaInstanceType type; /**< Type definition for this instance. */ enum _CpaInstanceState state; /**< Operational state of the instance. */ Cpa8U name[CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES]; /**< Simple text string identifier for the instance. */ Cpa8U version[CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES]; /**< Version string. There may be multiple versions of the same type of * instance accessible through a particular library. */ } CpaInstanceInfo CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Physical Instance ID * @description * Identifies the physical instance of an accelerator execution * engine. * * Accelerators grouped into "packages". Each accelerator can in * turn contain one or more execution engines. Implementations of * this API will define the packageId, acceleratorId, * executionEngineId and busAddress as appropriate for the * implementation. For example, for hardware-based accelerators, * the packageId might identify the chip, which might contain * multiple accelerators, each of which might contain multiple * execution engines. The combination of packageId, acceleratorId * and executionEngineId uniquely identifies the instance. * * Hardware based accelerators implementing this API may also provide * information on the location of the accelerator in the busAddress * field. This field will be defined as appropriate for the * implementation. For example, for PCIe attached accelerators, * the busAddress may contain the PCIe bus, device and function * number of the accelerators. * *****************************************************************************/ typedef struct _CpaPhysicalInstanceId { Cpa16U packageId; /**< Identifies the package within which the accelerator is * contained. */ Cpa16U acceleratorId; /**< Identifies the specific accelerator within the package. */ Cpa16U executionEngineId; /**< Identifies the specific execution engine within the * accelerator. */ Cpa16U busAddress; /**< Identifies the bus address associated with the accelerator * execution engine. */ Cpa32U kptAcHandle; /**< Identifies the achandle of the accelerator. */ } CpaPhysicalInstanceId; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance Info Structure, version 2 * @description * Structure that contains the information to describe the instance. * *****************************************************************************/ typedef struct _CpaInstanceInfo2 { CpaAccelerationServiceType accelerationServiceType; /**< Type of service provided by this instance. */ #define CPA_INST_VENDOR_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES /**< Maximum length of the vendor name. */ Cpa8U vendorName[CPA_INST_VENDOR_NAME_SIZE]; /**< String identifying the vendor of the accelerator. */ #define CPA_INST_PART_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES /**< Maximum length of the part name. */ Cpa8U partName[CPA_INST_PART_NAME_SIZE]; /**< String identifying the part (name and/or number). */ #define CPA_INST_SW_VERSION_SIZE CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES /**< Maximum length of the software version string. */ Cpa8U swVersion[CPA_INST_SW_VERSION_SIZE]; /**< String identifying the version of the software associated with * the instance. For hardware-based implementations of the API, * this should be the driver version. For software-based * implementations of the API, this should be the version of the * library. * * Note that this should NOT be used to store the version of the * API, nor should it be used to report the hardware revision * (which can be captured as part of the @ref partName, if required). */ #define CPA_INST_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES /**< Maximum length of the instance name. */ Cpa8U instName[CPA_INST_NAME_SIZE]; /**< String identifying the name of the instance. */ #define CPA_INST_ID_SIZE CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES Cpa8U instID[CPA_INST_ID_SIZE]; /**< String containing a unique identifier for the instance */ CpaPhysicalInstanceId physInstId; /**< Identifies the "physical instance" of the accelerator. */ #define CPA_MAX_CORES 4096 /**< Maximum number of cores to support in the coreAffinity bitmap. */ CPA_BITMAP(coreAffinity, CPA_MAX_CORES); /**< A bitmap identifying the core or cores to which the instance * is affinitized in an SMP operating system. * * The term core here is used to mean a "logical" core - for example, * in a dual-processor, quad-core system with hyperthreading (two * threads per core), there would be 16 such cores (2 processors x * 4 cores/processor x 2 threads/core). The numbering of these cores * and the corresponding bit positions is OS-specific. Note that Linux * refers to this as "processor affinity" or "CPU affinity", and refers * to the bitmap as a "cpumask". * * The term "affinity" is used to mean that this is the core on which * the callback function will be invoked when using the asynchronous * mode of the API. In a hardware-based implementation of the API, * this might be the core to which the interrupt is affinitized. * In a software-based implementation, this might be the core to which * the process running the algorithm is affinitized. Where there is * no affinity, the bitmap can be set to all zeroes. * * This bitmap should be manipulated using the macros @ref * CPA_BITMAP_BIT_SET, @ref CPA_BITMAP_BIT_CLEAR and @ref * CPA_BITMAP_BIT_TEST. */ Cpa32U nodeAffinity; /**< Identifies the processor complex, or node, to which the accelerator * is physically connected, to help identify locality in NUMA systems. * * The values taken by this attribute will typically be in the range * 0..n-1, where n is the number of nodes (processor complexes) in the * system. For example, in a dual-processor configuration, n=2. The * precise values and their interpretation are OS-specific. */ CpaOperationalState operState; /**< Operational state of the instance. */ CpaBoolean requiresPhysicallyContiguousMemory; /**< Specifies whether the data pointed to by flat buffers * (CpaFlatBuffer::pData) supplied to this instance must be in * physically contiguous memory. */ CpaBoolean isPolled; /**< Specifies whether the instance must be polled, or is event driven. * For hardware accelerators, the alternative to polling would be * interrupts. */ CpaBoolean isOffloaded; /**< Identifies whether the instance uses hardware offload, or is a * software-only implementation. */ } CpaInstanceInfo2; /** ***************************************************************************** * @ingroup cpa_BaseDataTypes * Instance Events * @description * Enumeration of the different events that will cause the registered * Instance notification callback function to be invoked. * *****************************************************************************/ typedef enum _CpaInstanceEvent { CPA_INSTANCE_EVENT_RESTARTING = 0, /**< Event type that triggers the registered instance notification callback * function when and instance is restarting. The reason why an instance is * restarting is implementation specific. For example a hardware * implementation may send this event if the hardware device is about to * be reset. */ CPA_INSTANCE_EVENT_RESTARTED, /**< Event type that triggers the registered instance notification callback * function when and instance has restarted. The reason why an instance has * restarted is implementation specific. For example a hardware * implementation may send this event after the hardware device has * been reset. */ CPA_INSTANCE_EVENT_FATAL_ERROR /**< Event type that triggers the registered instance notification callback * function when an error has been detected that requires the device * to be reset. * This event will be sent by all instances using the device, both on the * host and guests. */ } CpaInstanceEvent; /*****************************************************************************/ /* CPA Instance Management Functions */ /*****************************************************************************/ /** ***************************************************************************** * @file cpa.h * @ingroup cpa * Get the number of Acceleration Service instances that are supported by * the API implementation. * * @description * This function will get the number of instances that are supported * for the required Acceleration Service by an implementation of the CPA * API. This number is then used to determine the size of the array that * must be passed to @ref cpaGetInstances(). * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] accelerationServiceType Acceleration Service required * @param[out] pNumInstances Pointer to where the number of * instances 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaGetInstances * *****************************************************************************/ CpaStatus cpaGetNumInstances( const CpaAccelerationServiceType accelerationServiceType, Cpa16U *pNumInstances); /** ***************************************************************************** * @file cpa.h * @ingroup cpa * Get the handles to the required Acceleration Service instances that are * supported by the API implementation. * * @description * This function will return handles to the required Acceleration Service * instances that are supported by an implementation of the CPA API. These * instance handles can then be used as input parameters with other * API functions. * * This function will populate an array that has been allocated by the * caller. The size of this array will have been determined by the * cpaGetNumInstances() function. * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] accelerationServiceType Acceleration Service requested * @param[in] numInstances Size of the array. If the value is * greater than the number of instances * supported, then an error (@ref * CPA_STATUS_INVALID_PARAM) is returned. * @param[in,out] cpaInstances Pointer to where the instance * handles 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaGetNumInstances * *****************************************************************************/ CpaStatus cpaGetInstances( const CpaAccelerationServiceType accelerationServiceType, Cpa16U numInstances, CpaInstanceHandle *cpaInstances); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_H */ diff --git a/sys/dev/qat/qat_api/include/cpa_dev.h b/sys/dev/qat/qat_api/include/cpa_dev.h index bb6dd1d76f2a..9c1c7ccff45e 100644 --- a/sys/dev/qat/qat_api/include/cpa_dev.h +++ b/sys/dev/qat/qat_api/include/cpa_dev.h @@ -1,144 +1,111 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_dev.h * * @defgroup cpaDev Device API * * @ingroup cpa * * @description * These functions specify the API for device level operation. * * @remarks * * *****************************************************************************/ #ifndef CPA_DEV_H #define CPA_DEV_H #ifdef __cplusplus extern"C" { #endif #ifndef CPA_H #include "cpa.h" #endif /***************************************************************************** * @ingroup cpaDev * Returns device information * * @description * This data structure contains the device information. The device * information are available to both Physical and Virtual Functions. * Depending on the resource partitioning configuration, the services * available may changes. This configuration will impact the size of the * Security Association Database (SADB). Other properties such device SKU * and device ID are also reported. * *****************************************************************************/ typedef struct _CpaDeviceInfo { Cpa32U sku; /**< Identifies the SKU of the device. */ Cpa16U bdf; /**< Identifies the Bus Device Function of the device. * Format is reported as follow: * - bits<2:0> represent the function number. * - bits<7:3> represent the device * - bits<15:8> represent the bus */ Cpa32U deviceId; /**< Returns the device ID. */ Cpa32U numaNode; /**< Return the local NUMA node mapped to the device. */ CpaBoolean isVf; /**< Return whether the device is currently used in a virtual function * or not. */ CpaBoolean dcEnabled; /**< Compression service enabled */ CpaBoolean cySymEnabled; /**< Symmetric crypto service enabled */ CpaBoolean cyAsymEnabled; /**< Asymmetric crypto service enabled */ CpaBoolean inlineEnabled; /**< Inline service enabled */ Cpa32U deviceMemorySizeAvailable; /**< Return the size of the device memory available. This device memory * section could be used for the intermediate buffers in the * compression service. */ } CpaDeviceInfo; /***************************************************************************** * @ingroup cpaDev * Returns number devices. * * @description * This API returns the number of devices available to the application. * If used on the host, it will return the number of physical devices. * If used on the guest, it will return the number of function mapped * to the virtual machine. * *****************************************************************************/ CpaStatus cpaGetNumDevices (Cpa16U *numDevices); /***************************************************************************** * @ingroup cpaDev * Returns device information for a given device index. * * @description * Returns device information for a given device index. This API must * be used with cpaGetNumDevices(). *****************************************************************************/ CpaStatus cpaGetDeviceInfo (Cpa16U device, CpaDeviceInfo *deviceInfo); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_DEV_H */ diff --git a/sys/dev/qat/qat_api/include/cpa_types.h b/sys/dev/qat/qat_api/include/cpa_types.h index 93bed46f3730..712f1cf88b93 100644 --- a/sys/dev/qat/qat_api/include/cpa_types.h +++ b/sys/dev/qat/qat_api/include/cpa_types.h @@ -1,229 +1,196 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_types.h * * @defgroup cpa_Types CPA Type Definition * * @ingroup cpa * * @description * This is the CPA Type Definitions. * *****************************************************************************/ #ifndef CPA_TYPES_H #define CPA_TYPES_H #ifdef __cplusplus extern "C" { #endif #if defined (__FreeBSD__) && defined (_KERNEL) /* FreeBSD kernel mode */ #include #include #include #else /* Linux, FreeBSD, or Windows user mode */ #include #include #include #endif #if defined (WIN32) || defined (_WIN64) /* nonstandard extension used : zero-sized array in struct/union */ #pragma warning (disable: 4200) #endif typedef uint8_t Cpa8U; /**< * @file cpa_types.h * @ingroup cpa_Types * Unsigned byte base type. */ typedef int8_t Cpa8S; /**< * @file cpa_types.h * @ingroup cpa_Types * Signed byte base type. */ typedef uint16_t Cpa16U; /**< * @file cpa_types.h * @ingroup cpa_Types * Unsigned double-byte base type. */ typedef int16_t Cpa16S; /**< * @file cpa_types.h * @ingroup cpa_Types * Signed double-byte base type. */ typedef uint32_t Cpa32U; /**< * @file cpa_types.h * @ingroup cpa_Types * Unsigned quad-byte base type. */ typedef int32_t Cpa32S; /**< * @file cpa_types.h * @ingroup cpa_Types * Signed quad-byte base type. */ typedef uint64_t Cpa64U; /**< * @file cpa_types.h * @ingroup cpa_Types * Unsigned double-quad-byte base type. */ typedef int64_t Cpa64S; /**< * @file cpa_types.h * @ingroup cpa_Types * Signed double-quad-byte base type. */ /***************************************************************************** * Generic Base Data Type definitions *****************************************************************************/ #ifndef NULL #define NULL (0) /**< * @file cpa_types.h * @ingroup cpa_Types * NULL definition. */ #endif /** ***************************************************************************** * @ingroup cpa_Types * Boolean type. * * @description * Functions in this API use this type for Boolean variables that take * true or false values. * *****************************************************************************/ typedef enum _CpaBoolean { CPA_FALSE = (0==1), /**< False value */ CPA_TRUE = (1==1) /**< True value */ } CpaBoolean; /** ***************************************************************************** * @ingroup cpa_Types * Declare a bitmap of specified size (in bits). * * @description * This macro is used to declare a bitmap of arbitrary size. * * To test whether a bit in the bitmap is set, use @ref * CPA_BITMAP_BIT_TEST. * * While most uses of bitmaps on the API are read-only, macros are also * provided to set (see @ref CPA_BITMAP_BIT_SET) and clear (see @ref * CPA_BITMAP_BIT_CLEAR) bits in the bitmap. *****************************************************************************/ #define CPA_BITMAP(name, sizeInBits) \ Cpa32U name[((sizeInBits)+31)/32] #define CPA_BITMAP_BIT_TEST(bitmask, bit) \ ((bitmask[(bit)/32]) & (0x1 << ((bit)%32))) /**< * @ingroup cpa_Types * Test a specified bit in the specified bitmap. The bitmap may have been * declared using @ref CPA_BITMAP. Returns a Boolean (true if the bit is * set, false otherwise). */ #define CPA_BITMAP_BIT_SET(bitmask, bit) \ (bitmask[(bit)/32] |= (0x1 << ((bit)%32))) /**< * @file cpa_types.h * @ingroup cpa_Types * Set a specified bit in the specified bitmap. The bitmap may have been * declared using @ref CPA_BITMAP. */ #define CPA_BITMAP_BIT_CLEAR(bitmask, bit) \ (bitmask[(bit)/32] &= ~(0x1 << ((bit)%32))) /**< * @ingroup cpa_Types * Clear a specified bit in the specified bitmap. The bitmap may have been * declared using @ref CPA_BITMAP. */ /** ********************************************************************** * * @ingroup cpa_Types * * @description * Declare a function or type and mark it as deprecated so that * usages get flagged with a warning. * ********************************************************************** */ #if defined(__GNUC__) || defined(__INTEL_COMPILER) || defined(_WIN64) /* * gcc and icc support the __attribute__ ((deprecated)) syntax for marking * functions and other constructs as deprecated. */ /* * Uncomment the deprecated macro if you need to see which structs are deprecated */ #define CPA_DEPRECATED /*#define CPA_DEPRECATED __attribute__ ((deprecated)) */ #else /* * for all other compilers, define deprecated to do nothing * */ /* #define CPA_DEPRECATED_FUNC(func) func; #pragma deprecated(func) */ #pragma message("WARNING: You need to implement the CPA_DEPRECATED macro for this compiler") #define CPA_DEPRECATED #endif #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_TYPES_H */ diff --git a/sys/dev/qat/qat_api/include/dc/cpa_dc.h b/sys/dev/qat/qat_api/include/dc/cpa_dc.h index 3002c62776c5..d1751fc7ee16 100644 --- a/sys/dev/qat/qat_api/include/dc/cpa_dc.h +++ b/sys/dev/qat/qat_api/include/dc/cpa_dc.h @@ -1,3255 +1,3222 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_dc.h * * @defgroup cpaDc Data Compression API * * @ingroup cpa * * @description * These functions specify the API for Data Compression operations. * * The Data Compression API has the following: * 1) Session based API functions * These functions require a session to be created before performing any * DC operations. Subsequent DC API functions make use of the returned * Session Handle within their structures or function prototypes. * 2) Session-less or No-Session (Ns) based API functions. * These functions do not require a session to be initialized before * performing DC operations. They are "one-shot" API function calls * that submit DC requests directly using the supplied parameters. * * @remarks * * *****************************************************************************/ #ifndef CPA_DC_H #define CPA_DC_H #ifdef __cplusplus extern"C" { #endif #ifndef CPA_H #include "cpa.h" #endif /** ***************************************************************************** * @ingroup cpaDc * CPA Dc Major Version Number * @description * The CPA_DC API major version number. This number will be incremented * when significant churn to the API has occurred. The combination of the * major and minor number definitions represent the complete version number * for this interface. * *****************************************************************************/ #define CPA_DC_API_VERSION_NUM_MAJOR (3) /** ***************************************************************************** * @ingroup cpaDc * CPA DC Minor Version Number * @description * The CPA_DC API minor version number. This number will be incremented * when minor changes to the API has occurred. The combination of the major * and minor number definitions represent the complete version number for * this interface. * *****************************************************************************/ #define CPA_DC_API_VERSION_NUM_MINOR (2) /** ***************************************************************************** * @file cpa_dc.h * @ingroup cpaDc * CPA DC API version at least * @description * The minimal supported CPA_DC API version. Allow to check if the API * version is equal or above some version to avoid compilation issues * with an older API version. * *****************************************************************************/ #define CPA_DC_API_VERSION_AT_LEAST(major, minor) \ (CPA_DC_API_VERSION_NUM_MAJOR > major || \ (CPA_DC_API_VERSION_NUM_MAJOR == major && \ CPA_DC_API_VERSION_NUM_MINOR >= minor)) /** ***************************************************************************** * @file cpa_dc.h * @ingroup cpaDc * CPA DC API version less than * @description * The maximum supported CPA_DC API version. Allow to check if the API * version is below some version to avoid compilation issues with a newer * API version. * *****************************************************************************/ #define CPA_DC_API_VERSION_LESS_THAN(major, minor) \ (CPA_DC_API_VERSION_NUM_MAJOR < major || \ (CPA_DC_API_VERSION_NUM_MAJOR == major && \ CPA_DC_API_VERSION_NUM_MINOR < minor)) /** ***************************************************************************** * @ingroup cpaDc * Size of bitmap needed for compression chaining capabilities. * * @description * Defines the number of bits in the bitmap to represent supported * chaining capabilities @ref dcChainCapInfo. Should be set to * at least one greater than the largest value in the enumerated type * @ref CpaDcChainOperations, so that the value of the enum constant * can also be used as the bit position in the bitmap. * * A larger value was chosen to allow for extensibility without the need * to change the size of the bitmap (to ease backwards compatibility in * future versions of the API). * *****************************************************************************/ #define CPA_DC_CHAIN_CAP_BITMAP_SIZE (32) /** ***************************************************************************** * @ingroup cpaDc * Compression API session handle type * * @description * Handle used to uniquely identify a Compression API session handle. This * handle is established upon registration with the API using * cpaDcInitSession(). * * * *****************************************************************************/ typedef void * CpaDcSessionHandle; /** ***************************************************************************** * @ingroup cpaDc * Supported flush flags * * @description * This enumerated list identifies the types of flush that can be * specified for stateful and stateless cpaDcCompressData and * cpaDcDecompressData functions. * *****************************************************************************/ typedef enum _CpaDcFlush { CPA_DC_FLUSH_NONE = 0, /**< No flush request. */ CPA_DC_FLUSH_FINAL, /**< Indicates that the input buffer contains all of the data for the compression session allowing any buffered data to be released. For Deflate, BFINAL is set in the compression header.*/ CPA_DC_FLUSH_SYNC, /**< Used for stateful deflate compression to indicate that all pending output is flushed, byte aligned, to the output buffer. The session state is not reset.*/ CPA_DC_FLUSH_FULL /**< Used for deflate compression to indicate that all pending output is flushed to the output buffer and the session state is reset.*/ } CpaDcFlush; /** ***************************************************************************** * @ingroup cpaDc * Supported Huffman Tree types * * @description * This enumeration lists support for Huffman Tree types. * Selecting Static Huffman trees generates compressed blocks with an RFC * 1951 header specifying "compressed with fixed Huffman trees". * * Selecting Full Dynamic Huffman trees generates compressed blocks with * an RFC 1951 header specifying "compressed with dynamic Huffman codes". * The headers are calculated on the data being compressed, requiring two * passes. * * Selecting Precompiled Huffman Trees generates blocks with RFC 1951 * dynamic headers. The headers are pre-calculated and are specified by * the file type. * *****************************************************************************/ typedef enum _CpaDcHuffType { CPA_DC_HT_STATIC = 0, /**< Static Huffman Trees */ CPA_DC_HT_PRECOMP, /**< Precompiled Huffman Trees */ CPA_DC_HT_FULL_DYNAMIC /**< Full Dynamic Huffman Trees */ } CpaDcHuffType; /** ***************************************************************************** * @ingroup cpaDc * Supported compression types * * @description * This enumeration lists the supported data compression algorithms. * In combination with CpaDcChecksum it is used to decide on the file * header and footer format. * *****************************************************************************/ typedef enum _CpaDcCompType { CPA_DC_DEFLATE = 3, /**< Deflate Compression */ CPA_DC_LZ4, /**< LZ4 Compression */ CPA_DC_LZ4S /**< LZ4S Compression */ } CpaDcCompType; /** ***************************************************************************** * @ingroup cpaDc * Support for defined algorithm window sizes * * @description * This enumerated list defines the valid window sizes that can be * used with the supported algorithms *****************************************************************************/ typedef enum _CpaDcCompWindowSize { CPA_DC_WINSIZE_4K = 0, /**< Window size of 4KB */ CPA_DC_WINSIZE_8K, /**< Window size of 8KB */ CPA_DC_WINSIZE_16K, /**< Window size of 16KB */ CPA_DC_WINSIZE_32K /**< Window size of 32KB */ } CpaDcCompWindowSize; /** ***************************************************************************** * @ingroup cpaDc * Min match size in bytes * @description * This is the min match size that will be used for the search algorithm. * It is only configurable for LZ4S. *****************************************************************************/ typedef enum _CpaDcCompMinMatch { CPA_DC_MIN_3_BYTE_MATCH = 0, /**< Min Match of 3 bytes */ CPA_DC_MIN_4_BYTE_MATCH /**< Min Match of 4 bytes */ } CpaDcCompMinMatch; /** ***************************************************************************** * @ingroup cpaDc * Maximum LZ4 output block size * @description * Maximum LZ4 output block size *****************************************************************************/ typedef enum _CpaDcCompLZ4BlockMaxSize { CPA_DC_LZ4_MAX_BLOCK_SIZE_64K = 0, /**< Maximum block size 64K */ CPA_DC_LZ4_MAX_BLOCK_SIZE_256K, /**< Maximum block size 256K */ CPA_DC_LZ4_MAX_BLOCK_SIZE_1M, /**< Maximum block size 1M */ CPA_DC_LZ4_MAX_BLOCK_SIZE_4M, /**< Maximum block size 4M */ } CpaDcCompLZ4BlockMaxSize; /** ***************************************************************************** * @ingroup cpaDc * Supported checksum algorithms * * @description * This enumeration lists the supported checksum algorithms * Used to decide on file header and footer specifics. * *****************************************************************************/ typedef enum _CpaDcChecksum { CPA_DC_NONE = 0, /**< No checksum required */ CPA_DC_CRC32, /**< Application requires a CRC32 checksum */ CPA_DC_ADLER32, /**< Application requires Adler-32 checksum */ CPA_DC_CRC32_ADLER32, /**< Application requires both CRC32 and Adler-32 checksums */ CPA_DC_XXHASH32, /**< Application requires xxHash-32 checksum */ } CpaDcChecksum; /** ***************************************************************************** * @ingroup cpaDc * Supported session directions * * @description * This enumerated list identifies the direction of a session. * A session can be compress, decompress or both. * *****************************************************************************/ typedef enum _CpaDcSessionDir { CPA_DC_DIR_COMPRESS = 0, /**< Session will be used for compression */ CPA_DC_DIR_DECOMPRESS, /**< Session will be used for decompression */ CPA_DC_DIR_COMBINED /**< Session will be used for both compression and decompression */ } CpaDcSessionDir; typedef CpaDcSessionDir CpaDcDir; /** ***************************************************************************** * @ingroup cpaDc * Supported session state settings * * @description * This enumerated list identifies the stateful setting of a session. * A session can be either stateful or stateless. * * Stateful sessions are limited to have only one in-flight message per * session. This means a compress or decompress request must be complete * before a new request can be started. This applies equally to sessions * that are uni-directional in nature and sessions that are combined * compress and decompress. Completion occurs when the synchronous function * returns, or when the asynchronous callback function has completed. * *****************************************************************************/ typedef enum _CpaDcSessionState { CPA_DC_STATEFUL = 0, /**< Session will be stateful, implying that state may need to be saved in some situations */ CPA_DC_STATELESS /**< Session will be stateless, implying no state will be stored*/ } CpaDcSessionState; typedef CpaDcSessionState CpaDcState; /** ***************************************************************************** * @ingroup cpaDc * Supported compression levels * * @description * This enumerated lists the supported compressed levels. * Lower values will result in less compressibility in less time. * * *****************************************************************************/ typedef enum _CpaDcCompLvl { CPA_DC_L1 = 1, /**< Compression level 1 */ CPA_DC_L2, /**< Compression level 2 */ CPA_DC_L3, /**< Compression level 3 */ CPA_DC_L4, /**< Compression level 4 */ CPA_DC_L5, /**< Compression level 5 */ CPA_DC_L6, /**< Compression level 6 */ CPA_DC_L7, /**< Compression level 7 */ CPA_DC_L8, /**< Compression level 8 */ CPA_DC_L9, /**< Compression level 9 */ CPA_DC_L10, /**< Compression level 10 */ CPA_DC_L11, /**< Compression level 11 */ CPA_DC_L12 /**< Compression level 12 */ } CpaDcCompLvl; /** ***************************************************************************** * @ingroup cpaDc * Supported additional details from accelerator * * @description * This enumeration lists the supported additional details from the * accelerator. These may be useful in determining the best way to * recover from a failure. * * *****************************************************************************/ typedef enum _CpaDcReqStatus { CPA_DC_OK = 0, /**< No error detected by compression slice */ CPA_DC_INVALID_BLOCK_TYPE = -1, /**< Invalid block type (type == 3) */ CPA_DC_BAD_STORED_BLOCK_LEN = -2, /**< Stored block length did not match one's complement */ CPA_DC_TOO_MANY_CODES = -3, /**< Too many length or distance codes */ CPA_DC_INCOMPLETE_CODE_LENS = -4, /**< Code length codes incomplete */ CPA_DC_REPEATED_LENS = -5, /**< Repeated lengths with no first length */ CPA_DC_MORE_REPEAT = -6, /**< Repeat more than specified lengths */ CPA_DC_BAD_LITLEN_CODES = -7, /**< Invalid literal/length code lengths */ CPA_DC_BAD_DIST_CODES = -8, /**< Invalid distance code lengths */ CPA_DC_INVALID_CODE = -9, /**< Invalid literal/length or distance code in fixed or dynamic block */ CPA_DC_INVALID_DIST = -10, /**< Distance is too far back in fixed or dynamic block */ CPA_DC_OVERFLOW = -11, /**< Overflow detected. This is an indication that output buffer has overflowed. * For stateful sessions, this is a warning (the input can be adjusted and * resubmitted). * For stateless sessions this is an error condition */ CPA_DC_SOFTERR = -12, /**< Other non-fatal detected */ CPA_DC_FATALERR = -13, /**< Fatal error detected */ CPA_DC_MAX_RESUBITERR = -14, /**< On an error being detected, the firmware attempted to correct and resubmitted the * request, however, the maximum resubmit value was exceeded */ CPA_DC_INCOMPLETE_FILE_ERR = -15, /**< The input file is incomplete. Note this is an indication that the request was * submitted with a CPA_DC_FLUSH_FINAL, however, a BFINAL bit was not found in the * request */ CPA_DC_WDOG_TIMER_ERR = -16, /**< The request was not completed as a watchdog timer hardware event occurred */ CPA_DC_EP_HARDWARE_ERR = -17, /**< Request was not completed as an end point hardware error occurred (for * example, a parity error) */ CPA_DC_VERIFY_ERROR = -18, /**< Error detected during "compress and verify" operation */ CPA_DC_EMPTY_DYM_BLK = -19, /**< Decompression request contained an empty dynamic stored block * (not supported) */ CPA_DC_CRC_INTEG_ERR = -20, /**< A data integrity CRC error was detected */ CPA_DC_REGION_OUT_OF_BOUNDS = -21, /**< Error returned when decompression ends before the specified partial * decompression region was produced */ CPA_DC_LZ4_MAX_BLOCK_SIZE_EXCEEDED = -93, /**< LZ4 max block size exceeded */ CPA_DC_LZ4_BLOCK_OVERFLOW_ERR = -95, /**< LZ4 Block Overflow Error */ CPA_DC_LZ4_TOKEN_IS_ZERO_ERR = -98, /**< LZ4 Decoded token offset or token length is zero */ CPA_DC_LZ4_DISTANCE_OUT_OF_RANGE_ERR = -100, /**< LZ4 Distance out of range for len/distance pair */ } CpaDcReqStatus; /** ***************************************************************************** * @ingroup cpaDc * Supported modes for automatically selecting the best compression type. * * @description * This enumeration lists the supported modes for automatically selecting * the best encoding which would lead to the best compression results. * * When CPA_DC_ASB_ENABLED is used the output will be a format compliant * block, whether the data is compressed or not. * * The following values are deprecated and should not be used. They * will be removed in a future version of this file. * - CPA_DC_ASB_STATIC_DYNAMIC * - CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_STORED_HDRS * - CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS * *****************************************************************************/ typedef enum _CpaDcAutoSelectBest { CPA_DC_ASB_DISABLED = 0, /**< Auto select best mode is disabled */ CPA_DC_ASB_STATIC_DYNAMIC = 1, /**< Auto select between static and dynamic compression */ CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_STORED_HDRS = 2, /**< Auto select between uncompressed, static and dynamic compression, * using stored block deflate headers if uncompressed is selected */ CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS = 3, /**< Auto select between uncompressed, static and dynamic compression, * using no deflate headers if uncompressed is selected */ CPA_DC_ASB_ENABLED = 4, /**< Auto select best mode is enabled */ } CpaDcAutoSelectBest; /** ***************************************************************************** * @ingroup cpaDc * Supported modes for skipping regions of input or output buffers. * * @description * This enumeration lists the supported modes for skipping regions of * input or output buffers. * *****************************************************************************/ typedef enum _CpaDcSkipMode { CPA_DC_SKIP_DISABLED = 0, /**< Skip mode is disabled */ CPA_DC_SKIP_AT_START = 1, /**< Skip region is at the start of the buffer. */ CPA_DC_SKIP_AT_END = 2, /**< Skip region is at the end of the buffer. */ CPA_DC_SKIP_STRIDE = 3 /**< Skip region occurs at regular intervals within the buffer. CpaDcSkipData.strideLength specifies the number of bytes between each skip region. */ } CpaDcSkipMode; /** ***************************************************************************** * @ingroup cpaDc * Service specific return codes * * @description * Compression specific return codes * * *****************************************************************************/ #define CPA_DC_BAD_DATA (-100) /**consumed arg. * -# The implementation communicates the amount of data in the * destination buffer list via pResults->produced arg. * * Source Buffer Setup Rules * -# The buffer list must have the correct number of flat buffers. This * is specified by the numBuffers element of the CpaBufferList. * -# Each flat buffer must have a pointer to contiguous memory that has * been allocated by the calling application. The * number of octets to be compressed or decompressed must be stored * in the dataLenInBytes element of the flat buffer. * -# It is permissible to have one or more flat buffers with a zero length * data store. This function will process all flat buffers until the * destination buffer is full or all source data has been processed. * If a buffer has zero length, then no data will be processed from * that buffer. * * Source Buffer Processing Rules. * -# The buffer list is processed in index order - SrcBuff->pBuffers[0] * will be completely processed before SrcBuff->pBuffers[1] begins to * be processed. * -# The application must drain the destination buffers. * If the source data was not completely consumed, the application * must resubmit the request. * -# On return, the pResults->consumed will indicate the number of bytes * consumed from the input buffers. * * Destination Buffer Setup Rules * -# The destination buffer list must have storage for processed data. * This implies at least one flat buffer must exist in the buffer list. * -# For each flat buffer in the buffer list, the dataLenInBytes element * must be set to the size of the buffer space. * -# It is permissible to have one or more flat buffers with a zero length * data store. * If a buffer has zero length, then no data will be added to * that buffer. * * Destination Buffer Processing Rules. * -# The buffer list is processed in index order - DestBuff->pBuffers[0] * will be completely processed before DestBuff->pBuffers[1] begins to * be processed. * -# On return, the pResults->produced will indicate the number of bytes * written to the output buffers. * -# If processing has not been completed, the application must drain the * destination buffers and resubmit the request. The application must * reset the dataLenInBytes for each flat buffer in the destination * buffer list. * * Checksum rules. * If a checksum is specified in the session setup data, then: * -# For the first request for a particular data segment the checksum * is initialised internally by the implementation. * -# The checksum is maintained by the implementation between calls * until the flushFlag is set to CPA_DC_FLUSH_FINAL indicating the * end of a particular data segment. * -# Intermediate checksum values are returned to the application, * via the CpaDcRqResults structure, in response to each request. * However these checksum values are not guaranteed to the valid * until the call with flushFlag set to CPA_DC_FLUSH_FINAL * completes successfully. * * The application should set flushFlag to * CPA_DC_FLUSH_FINAL to indicate processing a particular data segment * is complete. It should be noted that this function may have to be * called more than once to process data after the flushFlag parameter has * been set to CPA_DC_FLUSH_FINAL if the destination buffer fills. Refer * to buffer processing rules. * * For stateful operations, when the function is invoked with flushFlag * set to CPA_DC_FLUSH_NONE or CPA_DC_FLUSH_SYNC, indicating more data * is yet to come, the function may or may not retain data. When the * function is invoked with flushFlag set to CPA_DC_FLUSH_FULL or * CPA_DC_FLUSH_FINAL, the function will process all buffered data. * * For stateless operations, CPA_DC_FLUSH_FINAL will cause the BFINAL * bit to be set for deflate compression. The initial checksum for the * stateless operation should be set to 0. CPA_DC_FLUSH_NONE and * CPA_DC_FLUSH_SYNC should not be used for stateless operations. * * It is possible to maintain checksum and length information across * cpaDcCompressData() calls with a stateless session without maintaining * the full history state that is maintained by a stateful session. In this * mode of operation, an initial checksum value of 0 is passed into the * first cpaDcCompressData() call with the flush flag set to * CPA_DC_FLUSH_FULL. On subsequent calls to cpaDcCompressData() for this * session, the checksum passed to cpaDcCompressData should be set to the * checksum value produced by the previous call to cpaDcCompressData(). * When the last block of input data is passed to cpaDcCompressData(), the * flush flag should be set to CPA_DC_FLUSH_FINAL. This will cause the BFINAL * bit to be set in a deflate stream. It is the responsibility of the calling * application to maintain overall lengths across the stateless requests * and to pass the checksum produced by one request into the next request. * * When an instance supports compressAndVerifyAndRecover, it is enabled by * default when using cpaDcCompressData(). If this feature needs to be * disabled, cpaDcCompressData2() must be used. * * Synchronous or Asynchronous operation of the API is determined by * the value of the callbackFn parameter passed to cpaDcInitSession() * when the sessionHandle was setup. If a non-NULL value was specified * then the supplied callback function will be invoked asynchronously * with the response of this request. * * Response ordering: * For each session, the implementation must maintain the order of * responses. That is, if in asynchronous mode, the order of the callback * functions must match the order of jobs submitted by this function. * In a simple synchronous mode implementation, the practice of submitting * a request and blocking on its completion ensure ordering is preserved. * * This limitation does not apply if the application employs multiple * threads to service a single session. * * If this API is invoked asynchronous, the return code represents * the success or not of asynchronously scheduling the request. * The results of the operation, along with the amount of data consumed * and produced become available when the callback function is invoked. * As such, pResults->consumed and pResults->produced are available * only when the operation is complete. * * The application must not use either the source or destination buffers * until the callback has completed. * * @see * None * *****************************************************************************/ CpaStatus cpaDcCompressData( CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcRqResults *pResults, CpaDcFlush flushFlag, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Submit a request to compress a buffer of data. * * @description * This API consumes data from the input buffer and generates compressed * data in the output buffer. This API is very similar to * cpaDcCompressData() except it provides a CpaDcOpData structure for * passing additional input parameters not covered in cpaDcCompressData(). * * @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] dcInstance Target service instance. * @param[in,out] pSessionHandle Session handle. * @param[in] pSrcBuff Pointer to data buffer for compression. * @param[in] pDestBuff Pointer to buffer space for data after * compression. * @param[in,out] pOpData Additional parameters. * @param[in,out] pResults Pointer to results structure * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_DC_BAD_DATA The input data was not properly formed. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * @post * pSessionHandle has session related state information * @note * This function passes control to the compression service for processing * * @see * cpaDcCompressData() * *****************************************************************************/ CpaStatus cpaDcCompressData2( CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcOpData *pOpData, CpaDcRqResults *pResults, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Submit a request to compress a buffer of data without requiring a * session to be created. This is a No-Session (Ns) variant of the * cpaDcCompressData function. * * @description * This API consumes data from the input buffer and generates compressed * data in the output buffer. Unlike the other compression APIs this * does not use a previously created session. This is a "one-shot" API * that requests can be directly submitted to. * * @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] dcInstance Target service instance. * @param[in] pSetupData Configuration structure for compression. * @param[in] pSrcBuff Pointer to data buffer for compression. * @param[in] pDestBuff Pointer to buffer space for data after * compression. * @param[in] pOpData Additional input parameters. * @param[in,out] pResults Pointer to results structure * @param[in] callbackFn For synchronous operation this callback * shall be a null pointer. * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * * @pre * None * @post * None * @note * This function passes control to the compression service for processing * * Checksum rules. * The checksum rules are the same as those for the session based APIs * (cpaDcCompressData or cpaDcCompressData2) with the following exception. * -# If the algorithm specified is CPA_DC_LZ4 or CPA_DC_LZ4S the xxHash32 * checksum will not be maintained across calls to the API. The * implication is that the xxHash32 value will only be valid for the * output of a single request, no state will be saved. If an LZ4 frame is * required, even in recoverable error scenarios such as CPA_DC_OVERFLOW, * the checksum will not be continued. If that is required the session * based API must be used. * * @see * None * *****************************************************************************/ CpaStatus cpaDcNsCompressData( CpaInstanceHandle dcInstance, CpaDcNsSetupData *pSetupData, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcOpData *pOpData, CpaDcRqResults *pResults, CpaDcCallbackFn callbackFn, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Submit a request to decompress a buffer of data. * * @description * This API consumes compressed data from the input buffer and generates * uncompressed data in the output buffer. * * @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] dcInstance Target service instance. * @param[in,out] pSessionHandle Session handle. * @param[in] pSrcBuff Pointer to data buffer for compression. * @param[in] pDestBuff Pointer to buffer space for data * after decompression. * @param[in,out] pResults Pointer to results structure * @param[in] flushFlag When set to CPA_DC_FLUSH_FINAL, indicates * that the input buffer contains all of * the data for the compression session, * allowing the function to release * history data. * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_DC_BAD_DATA The input data was not properly formed. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * @post * pSessionHandle has session related state information * @note * This function passes control to the compression service for * decompression. The function returns the status from the service. * * This function may be called repetitively with input until all of the * input has been provided and all the output has been consumed. * * This function has identical buffer processing rules as * cpaDcCompressData(). * * This function has identical checksum processing rules as * cpaDcCompressData(). * * The application should set flushFlag to * CPA_DC_FLUSH_FINAL to indicate processing a particular compressed * data segment is complete. It should be noted that this function may * have to be called more than once to process data after flushFlag * has been set if the destination buffer fills. Refer to * buffer processing rules in cpaDcCompressData(). * * Synchronous or Asynchronous operation of the API is determined by * the value of the callbackFn parameter passed to cpaDcInitSession() * when the sessionHandle was setup. If a non-NULL value was specified * then the supplied callback function will be invoked asynchronously * with the response of this request, along with the callbackTag * specified in the function. * * The same response ordering constraints identified in the * cpaDcCompressData API apply to this function. * * @see * cpaDcCompressData() * *****************************************************************************/ CpaStatus cpaDcDecompressData( CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcRqResults *pResults, CpaDcFlush flushFlag, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Submit a request to decompress a buffer of data. * * @description * This API consumes compressed data from the input buffer and generates * uncompressed data in the output buffer. This API is very similar to * cpaDcDecompressData() except it provides a CpaDcOpData structure for * passing additional input parameters not covered in cpaDcDecompressData(). * * @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] dcInstance Target service instance. * @param[in,out] pSessionHandle Session handle. * @param[in] pSrcBuff Pointer to data buffer for compression. * @param[in] pDestBuff Pointer to buffer space for data * after decompression. * @param[in] pOpData Additional input parameters. * @param[in,out] pResults Pointer to results structure * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_DC_BAD_DATA The input data was not properly formed. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * @post * pSessionHandle has session related state information * @note * This function passes control to the compression service for * decompression. The function returns the status from the service. * * @see * cpaDcDecompressData() * cpaDcCompressData2() * cpaDcCompressData() * *****************************************************************************/ CpaStatus cpaDcDecompressData2( CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcOpData *pOpData, CpaDcRqResults *pResults, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Submit a request to decompress a buffer of data without requiring a * session to be created. This is a No-Session (Ns) variant of the * cpaDcDecompressData function. * * @description * This API consumes data from the input buffer and generates decompressed * data in the output buffer. Unlike the other decompression APIs this * does not use a previously created session. This is a "one-shot" API * that requests can be directly submitted to. * * @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] dcInstance Target service instance. * @param[in] pSetupData Configuration structure for decompression.. * @param[in] pSrcBuff Pointer to data buffer for decompression. * @param[in] pDestBuff Pointer to buffer space for data * after decompression. * @param[in] pOpData Additional input parameters. * @param[in,out] pResults Pointer to results structure * @param[in] callbackFn For synchronous operation this callback * shall be a null pointer. * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * * @pre * None * @post * None * @note * This function passes control to the decompression service. The function * returns the status from the service. * * @see * cpaDcDecompressData() * cpaDcCompressData2() * cpaDcCompressData() * *****************************************************************************/ CpaStatus cpaDcNsDecompressData( CpaInstanceHandle dcInstance, CpaDcNsSetupData *pSetupData, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcOpData *pOpData, CpaDcRqResults *pResults, CpaDcCallbackFn callbackFn, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDc * Generate compression header. * * @description * This function generates the gzip header, zlib header or LZ4 frame * header and stores it in the destination buffer. The type of header * created is determined using the compression algorithm selected using * CpaDcSessionSetupData.compType, for the session associated with the * session handle. * * @context * This function may be call from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] pSessionHandle Session handle. * @param[in] pDestBuff Pointer to data buffer where the * compression header will go. * @param[out] count Pointer to counter filled in with * header size. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * * @note * When the deflate compression algorithm is used, this function can output * a 10 byte gzip header or 2 byte zlib header to the destination buffer. * The session properties are used to determine the header type. To * output a Gzip or a Zlib header the session must have been initialized * with CpaDcCompType CPA_DC_DEFLATE. * To output a gzip header the session must have been initialized with * CpaDcChecksum CPA_DC_CRC32. To output a zlib header the session must * have been initialized with CpaDcChecksum CPA_DC_ADLER32. * For CpaDcChecksum CPA_DC_NONE no header is output. * * If the compression requires a gzip header, then this header requires * at a minimum the following fields, defined in RFC1952: * ID1: 0x1f * ID2: 0x8b * CM: Compression method = 8 for deflate * * The zlib header is defined in RFC1950 and this function must implement * as a minimum: * CM: four bit compression method - 8 is deflate with window size to * 32k * CINFO: four bit window size (see RFC1950 for details), 7 is 32k * window * FLG: defined as: * - Bits 0 - 4: check bits for CM, CINFO and FLG (see RFC1950) * - Bit 5: FDICT 0 = default, 1 is preset dictionary * - Bits 6 - 7: FLEVEL, compression level (see RFC 1950) * * When LZ4 algorithm is used, this function can output a 7 byte frame * header. This function will set the LZ4 frame header with: * - Magic number 0x184D2204 * - The LZ4 max block size defined in the CpaDcSessionSetupData * - Flag byte as: * * Version = 1 * * Block independence = 0 * * Block checksum = 0 * * Content size present = 0 * * Content checksum present = 1 * * Dictionary ID present = 0 * - Content size = 0 * - Dictionary ID = 0 * - Header checksum = 1 byte representing the second byte of the * XXH32 of the frame descriptor field. * * The counter parameter will be set to the number of bytes added to the * buffer. The pData will be not be changed. * * For any of the compression algorithms used, the application is * responsible to offset the pData pointer in CpaBufferList by the length * of the header before calling the CpaDcCompressData() or * CpaDcCompressData2() functions. * @see * None * *****************************************************************************/ CpaStatus cpaDcGenerateHeader( CpaDcSessionHandle pSessionHandle, CpaFlatBuffer *pDestBuff, Cpa32U *count ); /** ***************************************************************************** * @ingroup cpaDc * Generate compression footer. * * @description * This function generates the footer for gzip, zlib or LZ4. * The generated footer is stored it in the destination buffer. * The type of footer created is determined using the compression * algorithm selected for the session associated with the session handle. * * @context * This function may be call from any context. * @assumptions * None * @sideEffects * All session variables are reset * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in,out] pSessionHandle Session handle. * @param[in] pDestBuff Pointer to data buffer where the * compression footer will go. * @param[in,out] pResults Pointer to results structure filled by * CpaDcCompressData. Updated with the * results of this API call * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * pResults structure has been filled by CpaDcCompressData(). * * @note * Depending on the session variables, this function can add the * alder32 footer to the zlib compressed data as defined in RFC1950. * If required, it can also add the gzip footer, which is the crc32 of the * uncompressed data and the length of the uncompressed data. * This section is defined in RFC1952. The session variables used to * determine the header type are CpaDcCompType and CpaDcChecksum, see * cpaDcGenerateHeader for more details. * * For LZ4 compression, this function adds the LZ4 frame footer * using XXH32 algorithm of the uncompressed data. The XXH32 checksum is * added after the end mark. This section is defined in the documentation * of the LZ4 frame format at: * https://github.com/lz4/lz4/blob/dev/doc/lz4_Frame_format.md * * An artifact of invoking this function for writing the footer data is * that all opaque session specific data is re-initialized. If the * compression level and file types are consistent, the upper level * application can continue processing compression requests using the * same session handle. * * The produced element of the pResults structure will be incremented by * the numbers bytes added to the buffer. The pointer to the buffer will * not be modified. It is necessary for the application to ensure that * there is always sufficient memory in the destination buffer to append * the footer. In the event that the destination buffer would be too small * to accept the footer, overflow will not be reported. * * @see * None * *****************************************************************************/ CpaStatus cpaDcGenerateFooter( CpaDcSessionHandle pSessionHandle, CpaFlatBuffer *pDestBuff, CpaDcRqResults *pResults ); /** ***************************************************************************** * @ingroup cpaDc * Generate compression header without requiring a session to be created. * This is a No-Session (Ns) variant of the cpaDcGenerateHeader function. * * @description * This API generates the required compression format header and stores it * in the output buffer. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] pSetupData Pointer to Ns Configuration structure. * @param[in] pDestBuff Pointer to data buffer where the * compression header will go. * @param[out] count Pointer to counter filled in with * header size. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None * * @note * This function outputs the required compression format header to * the destination buffer. The CpaDcNsSetupData structure fields are used to * determine the header type. * * To output an LZ4 header the structure must have been initialized with * with CpaDcCompType CPA_DC_LZ4. * To output a gzip or zlib header the structure must have been initialized * with CpaDcCompType CPA_DC_DEFLATE. * To output a gzip header the structure must have been initialized with * CpaDcChecksum CPA_DC_CRC32. * To output a zlib header the structure must have been initialized with * CpaDcChecksum CPA_DC_ADLER32. * For CpaDcChecksum CPA_DC_NONE no header is output. * * The counter parameter will be set to the number of bytes added to the * buffer. * * @see * cpaDcGenerateHeader * *****************************************************************************/ CpaStatus cpaDcNsGenerateHeader( CpaDcNsSetupData *pSetupData, CpaFlatBuffer *pDestBuff, Cpa32U *count ); /** ***************************************************************************** * @ingroup cpaDc * Generate compression footer without requiring a session to be created. * This is a No-Session (Ns) variant of the cpaDcGenerateFooter function. * * @description * This API generates the footer for the required format and stores it in * the destination buffer. * @context * This function may be call from any context. * @assumptions * None * @sideEffects * All session variables are reset * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] pSetupData Pointer to Ns Configuration structure. * @param[in] totalLength Total accumulated length of input data * processed. See description for formats * that make use of this parameter. * @param[in] pDestBuff Pointer to data buffer where the * compression footer will go. * @param[in,out] pResults Pointer to results structure filled by * CpaDcNsCompressData. Updated with the * results of this API call * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * pResults structure has been filled by CpaDcNsCompressData(). * * @note * This function outputs the required compression format footer to * the destination buffer. The CpaDcNsSetupData structure fields are used to * determine the footer type created. * * To output an LZ4 footer the structure must have been initialized with * with CpaDcCompType CPA_DC_LZ4. * To output a gzip or zlib footer the structure must have been initialized * with CpaDcCompType CPA_DC_DEFLATE. * To output a gzip footer the structure must have been initialized with * CpaDcChecksum CPA_DC_CRC32 and the totalLength parameter initialized to * the total accumulated length of data processed. * To output a zlib footer the structure must have been initialized with * CpaDcChecksum CPA_DC_ADLER32. * For CpaDcChecksum CPA_DC_NONE no footer is output. * * The produced element of the pResults structure will be incremented by the * number of bytes added to the buffer. The pointer to the buffer * will not be modified. * * @see * CpaDcNsSetupData * cpaDcNsGenerateHeader * cpaDcGenerateFooter * *****************************************************************************/ CpaStatus cpaDcNsGenerateFooter( CpaDcNsSetupData *pSetupData, Cpa64U totalLength, CpaFlatBuffer *pDestBuff, CpaDcRqResults *pResults ); /** ***************************************************************************** * @ingroup cpaDc * Retrieve statistics * * @description * This API retrieves the current statistics for a compression instance. * * @context * This function may be call from any context. * @assumptions * None * @sideEffects * None * @blocking * Yes * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle. * @param[out] pStatistics Pointer to statistics structure. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * * @see * None * *****************************************************************************/ CpaStatus cpaDcGetStats( CpaInstanceHandle dcInstance, CpaDcStats *pStatistics ); /*****************************************************************************/ /* Instance Discovery Functions */ /** ***************************************************************************** * @ingroup cpaDc * Get the number of device instances that are supported by the API * implementation. * * @description * * This function will get the number of device instances that are supported * by an implementation of the compression API. This number is then used to * determine the size of the array that must be passed to * cpaDcGetInstances(). * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[out] pNumInstances Pointer to where the number of * instances 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaDcGetInstances * *****************************************************************************/ CpaStatus cpaDcGetNumInstances(Cpa16U* pNumInstances); /** ***************************************************************************** * @ingroup cpaDc * Get the handles to the device instances that are supported by the * API implementation. * * @description * * This function will return handles to the device instances that are * supported by an implementation of the compression API. These instance * handles can then be used as input parameters with other compression API * functions. * * This function will populate an array that has been allocated by the * caller. The size of this API is determined by the * cpaDcGetNumInstances() function. * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] numInstances Size of the array. * @param[out] dcInstances Pointer to where the instance * handles 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaDcGetInstances * *****************************************************************************/ CpaStatus cpaDcGetInstances(Cpa16U numInstances, CpaInstanceHandle* dcInstances); /** ***************************************************************************** * @ingroup cpaDc * Compression Component utility function to determine the number of * intermediate buffers required by an implementation. * * @description * This function will determine the number of intermediate buffer lists * required by an implementation for a compression instance. These buffers * should then be allocated and provided when calling @ref cpaDcStartInstance() * to start a compression instance that will use dynamic compression. * * @context * This function may sleep, and MUST NOT be called in interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * @param[in,out] instanceHandle Handle to an instance of this API to be * initialized. * @param[out] pNumBuffers When the function returns, this will * specify the number of buffer lists that * should be used as intermediate buffers * when calling cpaDcStartInstance(). * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Suggested course of action * is to shutdown and restart. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * cpaDcStartInstance() * *****************************************************************************/ CpaStatus cpaDcGetNumIntermediateBuffers(CpaInstanceHandle instanceHandle, Cpa16U *pNumBuffers); /** ***************************************************************************** * @ingroup cpaDc * Compression Component Initialization and Start function. * * @description * This function will initialize and start the compression component. * It MUST be called before any other compress function is called. This * function SHOULD be called only once (either for the very first time, * or after an cpaDcStopInstance call which succeeded) per instance. * Subsequent calls will have no effect. * * If required by an implementation, this function can be provided with * instance specific intermediate buffers. The intent is to provide an * instance specific location to store intermediate results during dynamic * instance Huffman tree compression requests. The memory should be * accessible by the compression engine. The buffers are to support * deflate compression with dynamic Huffman Trees. Each buffer list * should be similar in size to twice the destination buffer size passed * to the compress API. The number of intermediate buffer lists may vary * between implementations and so @ref cpaDcGetNumIntermediateBuffers() * should be called first to determine the number of intermediate * buffers required by the implementation. * * If not required, this parameter can be passed in as NULL. * * @context * This function may sleep, and MUST NOT be called in interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * @param[in,out] instanceHandle Handle to an instance of this API to be * initialized. * @param[in] numBuffers Number of buffer lists represented by * the pIntermediateBuffers parameter. * Note: @ref cpaDcGetNumIntermediateBuffers() * can be used to determine the number of * intermediate buffers that an implementation * requires. * @param[in] pIntermediateBuffers Optional pointer to Instance specific * DRAM buffer. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Suggested course of action * is to shutdown and restart. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * cpaDcStopInstance() * cpaDcGetNumIntermediateBuffers() * *****************************************************************************/ CpaStatus cpaDcStartInstance(CpaInstanceHandle instanceHandle, Cpa16U numBuffers, CpaBufferList **pIntermediateBuffers); /** ***************************************************************************** * @ingroup cpaDc * Compress Component Stop function. * * @description * This function will stop the Compression component and free * all system resources associated with it. The client MUST ensure that * all outstanding operations have completed before calling this function. * The recommended approach to ensure this is to deregister all session or * callback handles before calling this function. If outstanding * operations still exist when this function is invoked, the callback * function for each of those operations will NOT be invoked and the * shutdown will continue. If the component is to be restarted, then a * call to cpaDcStartInstance is required. * * @context * This function may sleep, and so MUST NOT be called in interrupt * context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * @param[in] instanceHandle Handle to an instance of this API to be * shutdown. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Suggested course of action * is to ensure requests are not still being * submitted and that all sessions are * deregistered. If this does not help, then * forcefully remove the component from the * system. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaDcStartInstance * @post * None * @note * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * cpaDcStartInstance() * *****************************************************************************/ CpaStatus cpaDcStopInstance(CpaInstanceHandle instanceHandle); /** ***************************************************************************** * @ingroup cpaDc * Function to get information on a particular instance. * * @description * This function will provide instance specific information through a * @ref CpaInstanceInfo2 structure. * * @context * This function will be executed in a context that requires that sleeping * MUST NOT be permitted. * @assumptions * None * @sideEffects * None * @blocking * Yes * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API to be * initialized. * @param[out] pInstanceInfo2 Pointer to the memory location allocated by * the client into which the CpaInstanceInfo2 * structure 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_UNSUPPORTED Function is not supported. * * @pre * The client has retrieved an instanceHandle from successive calls to * @ref cpaDcGetNumInstances and @ref cpaDcGetInstances. * @post * None * @note * None * @see * cpaDcGetNumInstances, * cpaDcGetInstances, * CpaInstanceInfo2 * *****************************************************************************/ CpaStatus cpaDcInstanceGetInfo2(const CpaInstanceHandle instanceHandle, CpaInstanceInfo2 * pInstanceInfo2); /*****************************************************************************/ /* Instance Notification Functions */ /*****************************************************************************/ /** ***************************************************************************** * @ingroup cpaDc * Callback function for instance notification support. * * @description * This is the prototype for the instance notification callback function. * The callback function is passed in as a parameter to the * @ref cpaDcInstanceSetNotificationCb function. * * @context * This function will be executed in a context that requires that sleeping * MUST NOT be permitted. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pCallbackTag Opaque value provided by user while making * individual function calls. * @param[in] instanceEvent The event that will trigger this function to * get invoked. * * @retval * None * @pre * Component has been initialized and the notification function has been * set via the cpaDcInstanceSetNotificationCb function. * @post * None * @note * None * @see * cpaDcInstanceSetNotificationCb(), * *****************************************************************************/ typedef void (*CpaDcInstanceNotificationCbFunc)( const CpaInstanceHandle instanceHandle, void * pCallbackTag, const CpaInstanceEvent instanceEvent); /** ***************************************************************************** * @ingroup cpaDc * Subscribe for instance notifications. * * @description * Clients of the CpaDc interface can subscribe for instance notifications * by registering a @ref CpaDcInstanceNotificationCbFunc function. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pInstanceNotificationCb Instance notification callback * function pointer. * @param[in] pCallbackTag Opaque value provided by user while * making individual function calls. * * @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_UNSUPPORTED Function is not supported. * * @pre * Instance has been initialized. * @post * None * @note * None * @see * CpaDcInstanceNotificationCbFunc * *****************************************************************************/ CpaStatus cpaDcInstanceSetNotificationCb( const CpaInstanceHandle instanceHandle, const CpaDcInstanceNotificationCbFunc pInstanceNotificationCb, void *pCallbackTag); /** ***************************************************************************** * @ingroup cpaDc * Get the size of the memory required to hold the session information. * * @description * * The client of the Data Compression API is responsible for * allocating sufficient memory to hold session information and the context * data. This function provides a means for determining the size of the * session information and the size of the context data. * * @context * No restrictions * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle. * @param[in] pSessionData Pointer to a user instantiated structure * containing session data. * @param[out] pSessionSize On return, this parameter will be the size * of the memory that will be * required by cpaDcInitSession() for session * data. * @param[out] pContextSize On return, this parameter will be the size * of the memory that will be required * for context data. Context data is * save/restore data including history and * any implementation specific data that is * required for a save/restore operation. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * Only a synchronous version of this function is provided. * * It is expected that context data is comprised of the history and * any data stores that are specific to the history such as linked * lists or hash tables. * For stateless sessions the context size returned from this function * will be zero. For stateful sessions the context size returned will * depend on the session setup data and may be zero. * * Session data is expected to include interim checksum values, various * counters and other session related data that needs to persist * between invocations. * For a given implementation of this API, it is safe to assume that * cpaDcGetSessionSize() will always return the same session size and * that the size will not be different for different setup data * parameters. However, it should be noted that the size may change: * (1) between different implementations of the API (e.g. between software * and hardware implementations or between different hardware * implementations) * (2) between different releases of the same API implementation. * * @see * cpaDcInitSession() * *****************************************************************************/ CpaStatus cpaDcGetSessionSize(CpaInstanceHandle dcInstance, CpaDcSessionSetupData* pSessionData, Cpa32U* pSessionSize, Cpa32U* pContextSize ); /** ***************************************************************************** * @ingroup cpaDc * Function to return the size of the memory which must be allocated for * the pPrivateMetaData member of CpaBufferList. * * @description * This function is used to obtain the size (in bytes) required to allocate * a buffer descriptor for the pPrivateMetaData member in the * CpaBufferList structure. * Should the function return zero then no meta data is required for the * buffer list. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[in] numBuffers The number of pointers in the CpaBufferList. * This is the maximum number of CpaFlatBuffers * which may be contained in this CpaBufferList. * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be * allocated when the client wishes to allocate * a cpaFlatBuffer. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * None * @see * cpaDcGetInstances() * *****************************************************************************/ CpaStatus cpaDcBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, Cpa32U numBuffers, Cpa32U *pSizeInBytes); /** ***************************************************************************** * @ingroup cpaDc * Function to return a string indicating the specific error that occurred * within the system. * * @description * When a function returns any error including CPA_STATUS_SUCCESS, the * client can invoke this function to get a string which describes the * general error condition, and if available additional information on * the specific error. * The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for the buffer * string. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Handle to an instance of this API. * @param[in] errStatus The error condition that occurred. * @param[in,out] pStatusText Pointer to the string buffer that will * be updated with the status text. The invoking * application MUST allocate this buffer to be * exactly CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Note, in this scenario * it is INVALID to call this function a * second time. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * None * @see * CpaStatus * *****************************************************************************/ CpaStatus cpaDcGetStatusText(const CpaInstanceHandle dcInstance, const CpaStatus errStatus, Cpa8S * pStatusText); /** ***************************************************************************** * @ingroup cpaDc * Set Address Translation function * * @description * This function is used to set the virtual to physical address * translation routine for the instance. The specified routine * is used by the instance to perform any required translation of * a virtual address to a physical address. If the application * does not invoke this function, then the instance will use its * default method, such as virt2phys, for address translation. * * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Data Compression API instance handle. * @param[in] virtual2Physical Routine that performs virtual to * physical address translation. * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @see * None * *****************************************************************************/ CpaStatus cpaDcSetAddressTranslation(const CpaInstanceHandle instanceHandle, CpaVirtualToPhysical virtual2Physical); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_DC_H */ diff --git a/sys/dev/qat/qat_api/include/dc/cpa_dc_bp.h b/sys/dev/qat/qat_api/include/dc/cpa_dc_bp.h index 67a70c7193a7..3243f46d0518 100644 --- a/sys/dev/qat/qat_api/include/dc/cpa_dc_bp.h +++ b/sys/dev/qat/qat_api/include/dc/cpa_dc_bp.h @@ -1,320 +1,287 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_dc_bp.h * * @defgroup cpaDcBp Data Compression Batch and Pack API * * @ingroup cpaDc * * @description * These functions specify the API for Data Compression operations related * to the 'Batch and Pack' mode of operation. * * @remarks * * *****************************************************************************/ #ifndef CPA_DC_BP_H #define CPA_DC_BP_H #ifdef __cplusplus extern"C" { #endif #include "cpa_dc.h" /** ***************************************************************************** * @ingroup cpaDcBp * Batch request input parameters. * @description * This structure contains the request information for use with batched * compression operations. * * ****************************************************************************/ typedef struct _CpaDcBatchOpData { CpaDcOpData opData; /**< Compression input parameters */ CpaBufferList *pSrcBuff; /**< Input buffer list containing the data to be compressed. */ CpaBoolean resetSessionState; /**< Reset the session state at the beginning of this request within * the batch. Only applies to stateful sessions. When this flag is * set, the history from previous requests in this session will not be * used when compressing the input data for this request in the batch. * */ } CpaDcBatchOpData ; /** ***************************************************************************** * @ingroup cpaDcBp * Submit a batch of requests to compress a batch of input buffers into * a common output buffer. The same output buffer is used for each request * in the batch. This is termed 'batch and pack'. * * @description * This API consumes data from the input buffer and generates compressed * data in the output buffer. * This API compresses a batch of input buffers and concatenates the * compressed data into the output buffer. A results structure is also * generated for each request in the batch. * * @context * When called as an asynchronous funnction 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] dcInstance Target service instance. * @param[in,out] pSessionHandle Session handle. * @param[in] numRequests Number of requests in the batch. * @param[in] pBatchOpData Pointer to an array of CpaDcBatchOpData * structures which contain the input buffers * and parameters for each request in the * batch. There should be numRequests entries * in the array. * @param[in] pDestBuff Pointer to buffer space for data after * compression. * @param[in,out] pResults Pointer to an array of results structures. * There should be numRequests entries in the * array. * @param[in] callbackTag User supplied value to help correlate * the callback with its associated * request. * * @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_DC_BAD_DATA The input data was not properly formed. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * * @pre * pSessionHandle has been setup using cpaDcInitSession() * Session must be setup as a stateless sesssion. * @note * This function passes control to the compression service for processing * * In synchronous mode the function returns the error status returned from the * service. In asynchronous mode the status is returned by the callback * function. * * This function may be called repetitively with input until all of the input * has been consumed by the compression service and all the output has been * produced. * * When this function returns, it may be that all of the available buffers in * the input list has not been compressed. This situation will occur when * there is insufficient space in the output buffer. The calling application * should note the amount of buffers processed, and then submit the request * again, with a new output buffer and with the input buffer list containing * the buffers that were not previously compressed. * * Relationship between input buffers and results buffers. * -# Implementations of this API must not modify the individual * flat buffers of the input buffer list. * -# The implementation communicates the number of buffers * consumed from the source buffer list via pResults->consumed arg. * -# The implementation communicates the amount of data in the * destination buffer list via pResults->produced arg. * * Source Buffer Setup Rules * -# The buffer list must have the correct number of flat buffers. This * is specified by the numBuffers element of the CpaBufferList. * -# Each flat buffer must have a pointer to contiguous memory that has * been allocated by the calling application. The number of octets to be * compressed or decompressed must be stored in the dataLenInBytes element * of the flat buffer. * -# It is permissible to have one or more flat buffers with a zero length * data store. This function will process all flat buffers until the * destination buffer is full or all source data has been processed. * If a buffer has zero length, then no data will be processed from * that buffer. * * Source Buffer Processing Rules. * -# The buffer list is processed in index order - SrcBuff->pBuffers[0] * will be completely processed before SrcBuff->pBuffers[1] begins to * be processed. * -# The application must drain the destination buffers. * If the source data was not completely consumed, the application * must resubmit the request. * -# On return, the pResults->consumed will indicate the number of buffers * consumed from the input buffer list. * * Destination Buffer Setup Rules * -# The destination buffer list must have storage for processed data and * for the packed header information. * This means that least two flat buffer must exist in the buffer list. * The first buffer entry will be used for the header information. * Subsequent entries will be used for the compressed data. * -# For each flat buffer in the buffer list, the dataLenInBytes element * must be set to the size of the buffer space. * -# It is permissible to have one or more flat buffers with a zero length * data store. * If a buffer has zero length, then no data will be added to * that buffer. * * Destination Buffer Processing Rules. * -# The buffer list is processed in index order. * -# On return, the pResults->produced will indicate the number of bytes * of compressed data written to the output buffers. Note that this * will not include the header information buffer. * -# If processing has not been completed, the application must drain the * destination buffers and resubmit the request. The application must reset * the dataLenInBytes for each flat buffer in the destination buffer list. * * Synchronous or Asynchronous operation of the API is determined by * the value of the callbackFn parameter passed to cpaDcInitSession() * when the sessionHandle was setup. If a non-NULL value was specified * then the supplied callback function will be invoked asynchronously * with the response of this request. * * Response ordering: * For each session, the implementation must maintain the order of * responses. That is, if in asynchronous mode, the order of the callback * functions must match the order of jobs submitted by this function. * In a simple synchronous mode implementation, the practice of submitting * a request and blocking on its completion ensure ordering is preserved. * * This limitation does not apply if the application employs multiple * threads to service a single session. * * If this API is invoked asynchronous, the return code represents * the success or not of asynchronously scheduling the request. * The results of the operation, along with the amount of data consumed * and produced become available when the callback function is invoked. * As such, pResults->consumed and pResults->produced are available * only when the operation is complete. * * The application must not use either the source or destination buffers * until the callback has completed. * * @see * None * *****************************************************************************/ CpaStatus cpaDcBPCompressData( CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, const Cpa32U numRequests, CpaDcBatchOpData *pBatchOpData, CpaBufferList *pDestBuff, CpaDcRqResults *pResults, void *callbackTag ); /** ***************************************************************************** * @ingroup cpaDcBp * Function to return the size of the memory which must be allocated for * the pPrivateMetaData member of CpaBufferList contained within * CpaDcBatchOpData. * * @description * This function is used to obtain the size (in bytes) required to allocate * a buffer descriptor for the pPrivateMetaData member in the * CpaBufferList structure when Batch and Pack API are used. * Should the function return zero then no meta data is required for the * buffer list. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[in] numJobs The number of jobs defined in the CpaDcBatchOpData * table. * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be * allocated when the client wishes to allocate * a cpaFlatBuffer and the Batch and Pack OP data. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * * @pre * None * @post * None * @note * None * @see * cpaDcBPCompressData() * *****************************************************************************/ CpaStatus cpaDcBnpBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, Cpa32U numJobs, Cpa32U *pSizeInBytes); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_DC_BP_H */ diff --git a/sys/dev/qat/qat_api/include/dc/cpa_dc_chain.h b/sys/dev/qat/qat_api/include/dc/cpa_dc_chain.h index 8679b64fa5b5..7c0102d8d838 100644 --- a/sys/dev/qat/qat_api/include/dc/cpa_dc_chain.h +++ b/sys/dev/qat/qat_api/include/dc/cpa_dc_chain.h @@ -1,655 +1,622 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_dc_chain.h * * @defgroup cpaDcChain Data Compression Chaining API * * @ingroup cpaDc * * @description * These functions specify the API for Data Compression Chaining operations. * * @remarks * * *****************************************************************************/ #ifndef CPA_DC_CHAIN_H #define CPA_DC_CHAIN_H #ifdef __cplusplus extern"C" { #endif #include "cpa_dc.h" #include "cpa_cy_sym.h" /** ***************************************************************************** * @ingroup cpaDcChain * Supported operations for compression chaining * * @description * This enumeration lists the supported operations for compression chaining * *****************************************************************************/ typedef enum _CpaDcChainOperations { CPA_DC_CHAIN_COMPRESS_THEN_HASH = 0, /**< 2 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform hash on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for hash setup data*/ CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT = 1, /**< 2 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform encryption on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for encryption setup data*/ CPA_DC_CHAIN_COMPRESS_THEN_HASH_ENCRYPT = 2, /**< 2 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform hash on compressed text and * encryption on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for hash and encryption setup data*/ CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT_HASH = 3, /**< 2 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform encryption on compressed text and * hash on compressed & encrypted text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for encryption and hash setup data*/ CPA_DC_CHAIN_COMPRESS_THEN_AEAD = 4, /**< 2 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform AEAD encryption on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for AEAD encryption setup data*/ CPA_DC_CHAIN_HASH_THEN_COMPRESS = 5, /**< 2 operations for chaining: * 1st operation is to perform hash on plain text * 2nd operation is to perform compression on plain text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for hash setup data * 2nd entry is for compression setup data*/ CPA_DC_CHAIN_HASH_VERIFY_THEN_DECOMPRESS = 6, /**< 2 operations for chaining: * 1st operation is to perform hash verify on compressed text * 2nd operation is to perform decompression on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for hash setup data * 2nd entry is for decompression setup data*/ CPA_DC_CHAIN_DECRYPT_THEN_DECOMPRESS = 7, /**< 2 operations for chaining: * 1st operation is to perform decryption on compressed & encrypted text * 2nd operation is to perform decompression on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for decryption setup data * 2nd entry is for decompression setup data*/ CPA_DC_CHAIN_HASH_VERIFY_DECRYPT_THEN_DECOMPRESS = 8, /**< 2 operations for chaining: * 1st operation is to perform hash verify on compressed & encrypted text * and decryption on compressed & encrypted text * 2nd operation is to perform decompression on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for hash and decryption setup data * 2nd entry is for decompression setup data*/ CPA_DC_CHAIN_DECRYPT_HASH_VERIFY_THEN_DECOMPRESS = 9, /**< 2 operations for chaining: * 1st operation is to perform decryption on compressed & encrypted text * and hash verify on compressed text * 2nd operation is to perform decompression on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for decryption and hash setup data * 2nd entry is for decompression setup data*/ CPA_DC_CHAIN_AEAD_THEN_DECOMPRESS = 10, /**< 2 operations for chaining: * 1st operation is to perform AEAD decryption on compressed & encrypted text * 2nd operation is to perform decompression on compressed text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for AEAD decryption setup data * 2nd entry is for decompression setup data*/ CPA_DC_CHAIN_DECOMPRESS_THEN_HASH_VERIFY = 11, /**< 2 operations for chaining: * 1st operation is to perform decompression on compressed text * 2nd operation is to perform hash verify on plain text **< 2 entries in CpaDcChainSessionSetupData array: * 1st entry is for decompression setup data * 2nd entry is for hash setup data*/ CPA_DC_CHAIN_COMPRESS_THEN_AEAD_THEN_HASH = 12, /**< 3 operations for chaining: * 1st operation is to perform compression on plain text * 2nd operation is to perform AEAD encryption on compressed text * 3rd operation is to perform hash on compressed & encrypted text **< 3 entries in CpaDcChainSessionSetupData array: * 1st entry is for compression setup data * 2nd entry is for AEAD encryption setup data * 3rd entry is for hash setup data*/ } CpaDcChainOperations; /** ***************************************************************************** * @ingroup cpaDcChain * Supported session types for data compression chaining. * * @description * This enumeration lists the supported session types * for data compression chaining. *****************************************************************************/ typedef enum _CpaDcChainSessionType { CPA_DC_CHAIN_COMPRESS_DECOMPRESS = 0, /**< Indicate the session is for compression or decompression */ CPA_DC_CHAIN_SYMMETRIC_CRYPTO /**< Indicate the session is for symmetric crypto */ } CpaDcChainSessionType; /** ***************************************************************************** * @ingroup cpaDcChain * Chaining Session Setup Data. * @description * This structure contains data relating to set up chaining sessions. The * client needs to complete the information in this structure in order to * setup chaining sessions. * ****************************************************************************/ typedef struct _CpaDcChainSessionSetupData { CpaDcChainSessionType sessType; /**Indicate the type for this session */ union { CpaDcSessionSetupData *pDcSetupData; /**< Pointer to compression session setup data */ CpaCySymSessionSetupData *pCySetupData; /**< Pointer to symmetric crypto session setup data */ }; } CpaDcChainSessionSetupData; /** ***************************************************************************** * @ingroup cpaDcChain * Compression chaining request input parameters. * @description * This structure contains the request information to use with * compression chaining operations. * ****************************************************************************/ typedef struct _CpaDcChainOpData { CpaDcChainSessionType opType; /**< Indicate the type for this operation */ union { CpaDcOpData *pDcOp; /**< Pointer to compression operation data */ CpaCySymOpData *pCySymOp; /**< Pointer to symmetric crypto operation data */ }; } CpaDcChainOpData; /** ***************************************************************************** * @ingroup cpaDcChain * Chaining request results data * @description * This structure contains the request results. * ****************************************************************************/ typedef struct _CpaDcChainRqResults { CpaDcReqStatus dcStatus; /**< Additional status details from compression accelerator */ CpaStatus cyStatus; /**< Additional status details from symmetric crypto accelerator */ CpaBoolean verifyResult; /**< This parameter is valid when the verifyDigest option is set in the * CpaCySymSessionSetupData structure. A value of CPA_TRUE indicates * that the compare succeeded. A value of CPA_FALSE indicates that the * compare failed */ Cpa32U produced; /**< Octets produced to the output buffer */ Cpa32U consumed; /**< Octets consumed from the input buffer */ Cpa32U crc32; /**< crc32 checksum produced by chaining operations */ Cpa32U adler32; /**< Adler32 checksum produced by chaining operations */ }CpaDcChainRqResults; /** ***************************************************************************** * @ingroup cpaDcChain * Get the size of the memory required to hold the chaining sessions * information. * * @description * The client of the Data Compression API is responsible for * allocating sufficient memory to hold chaining sessions information. * This function provides a way for determining the size of chaining * sessions. * * @context * No restrictions * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle. * @param[in] operation The operation for chaining * @param[in] numSessions Number of sessions for the chaining * @param[in] pSessionData Pointer to an array of * CpaDcChainSessionSetupData structures. * There should be numSessions entries in * the array. * @param[out] pSessionSize On return, this parameter will be the size * of the memory that will be required by * cpaDcChainInitSession() for session data. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * Only a synchronous version of this function is provided. * * @see * cpaDcChainInitSession() * *****************************************************************************/ CpaStatus cpaDcChainGetSessionSize(CpaInstanceHandle dcInstance, CpaDcChainOperations operation, Cpa8U numSessions, CpaDcChainSessionSetupData *pSessionData, Cpa32U* pSessionSize); /** ***************************************************************************** * @ingroup cpaDcChain * Initialize data compression chaining session * * @description * This function is used to initialize compression/decompression chaining * sessions. * This function returns a unique session handle each time this function * is invoked. * If the session has been configured with a callback function, then * the order of the callbacks are guaranteed to be in the same order the * compression or decompression requests were submitted for each session, * so long as a single thread of execution is used for job submission. * * @context * This is a synchronous function and it cannot sleep. It can be executed * in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle derived from discovery * functions. * @param[in,out] pSessionHandle Pointer to a session handle. * @param[in] operation The operations for chaining * @param[in] numSessions Number of sessions for chaining * @param[in,out] pSessionData Pointer to an array of * CpaDcChainSessionSetupData structures. * There should be numSessions entries in * the array. * @param[in] callbackFn For synchronous operation this callback * shall be a null pointer. * * @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_UNSUPPORTED Function is not supported. * * @pre * dcInstance has been started using cpaDcStartInstance. * @post * None * @note * Only a synchronous version of this function is provided. * * pSessionData Setup Rules * -# Each element in CpaDcChainSessionSetupData structure array provides * (de)compression or a symmetric crypto session setup data. * * -# The supported chaining operations are listed in CpaDcChainOperations. * This enum indicates the number of operations in a chain and the order * in which they are performed. * * -# The order of entries in pSessionData[] should be consistent with the * CpaDcChainOperations perform order. * As an example, for CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT, pSessionData[0] * holds the compression setup data and pSessionData[1] holds the * encryption setup data.. * * -# The numSessions for each chaining operation are provided in * the comments of enum CpaDcChainOperations. * * -# For a (de)compression session, the corresponding * pSessionData[]->sessType should be set to * CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pSessionData[]->pDcSetupData * should point to a CpaDcSessionSetupData structure. * * -# For a symmetric crypto session, the corresponding * pSessionData[]->sessType should be set to CPA_DC_CHAIN_SYMMETRIC_CRYPTO * and pSessionData[]->pCySetupData should point to a * CpaCySymSessionSetupData structure. * * -# Combined compression sessions are not supported for chaining. * * -# Stateful compression is not supported for chaining. * * -# Both CRC32 and Adler32 over the input data are supported for chaining. * * @see * None * *****************************************************************************/ CpaStatus cpaDcChainInitSession(CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaDcChainOperations operation, Cpa8U numSessions, CpaDcChainSessionSetupData *pSessionData, CpaDcCallbackFn callbackFn); /** ***************************************************************************** * @ingroup cpaDcChain * Reset a compression chaining session. * * @description * This function will reset a previously initialized session handle. * Reset will fail if outstanding calls still exist for the initialized * session handle. * The client needs to retry the reset function at a later time. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle. * @param[in,out] pSessionHandle Session handle. * * @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_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaDcStartInstance function. * The session has been initialized via cpaDcChainInitSession function. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * * @see * cpaDcChainInitSession() * *****************************************************************************/ CpaStatus cpaDcChainResetSession(const CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle); /** ***************************************************************************** * @ingroup cpaDcChain * Remove a compression chaining session. * * @description * This function will remove a previously initialized session handle * and the installed callback handler function. Removal will fail if * outstanding calls still exist for the initialized session handle. * The client needs to retry the remove function at a later time. * The memory for the session handle MUST not be freed until this call * has completed successfully. * * @context * This is a synchronous function that cannot sleep. It can be executed * in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] dcInstance Instance handle. * @param[in,out] pSessionHandle Session handle. * * @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 cpaDcStartInstance function. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * * @see * cpaDcChainInitSession() * *****************************************************************************/ CpaStatus cpaDcChainRemoveSession(const CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle); /** ***************************************************************************** * @ingroup cpaDcChain * Submit a request to perform chaining operations. * * @description * This function is used to perform chaining operations over data from * the source buffer. * * @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] dcInstance Target service instance. * @param[in,out] pSessionHandle Session handle. * @param[in] pSrcBuff Pointer to input data buffer. * @param[out] pDestBuff Pointer to output data buffer. * @param[in] operation Operation for the chaining request * @param[in] numOpDatas The entries size CpaDcChainOpData array * @param[in] pChainOpData Pointer to an array of CpaDcChainOpData * structures. There should be numOpDatas * entries in the array. * @param[in,out] pResults Pointer to CpaDcChainRqResults * @param[in] callbackTag User supplied value to help correlate * the callback with its associated request. * * @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_DC_BAD_DATA The input data was not properly formed. * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * pSessionHandle has been setup using cpaDcChainInitSession() * @post * pSessionHandle has session related state information * @note * This function passes control to the compression service for chaining * processing, the supported chaining operations are described in * CpaDcChainOperations. * * pChainOpData Setup Rules * -# Each element in CpaDcChainOpData structure array holds either a * (de)compression or a symmetric crypto operation data. * * -# The order of entries in pChainOpData[] must be consistent with the * order of operations described for the chaining operation in * CpaDcChainOperations. * As an example, for CPA_DC_CHAIN_HASH_THEN_COMPRESS, pChainOpData[0] * must contain the hash operation data and pChainOpData[1] must * contain the compress operation data. * * -# The numOpDatas for each chaining operation are specified in the * comments for the operation in CpaDcChainOperations. * * -# For a (de)compression operation, the corresponding * pChainOpData[]->opType should be set to * CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pChainOpData[]->pDcOp should * point to a CpaDcOpData structure. * * -# For a symmetric crypto operation, the corresponding * pChainOpData[]->opType should be set to * CPA_DC_CHAIN_SYMMETRIC_CRYPTO and pChainOpData[]->pCySymOp should * point to a CpaCySymOpData structure. * * -# Partial packet processing is not supported. * * This function has identical buffer processing rules as * cpaDcCompressData(). * * This function has identical checksum processing rules as * cpaDcCompressData(), except: * -# pResults->crc32 is available to application if * CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32 * * -# pResults->adler32 is available to application if * CpaDcSessionSetupData->checksum is set to CPA_DC_ADLER32 * * -# Both pResults->crc32 and pResults->adler32 are available if * CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32_ADLER32 * * Synchronous or asynchronous operation of the API is determined by * the value of the callbackFn parameter passed to cpaDcChainInitSession() * when the sessionHandle was setup. If a non-NULL value was specified * then the supplied callback function will be invoked asynchronously * with the response of this request. * * This function has identical response ordering rules as * cpaDcCompressData(). * * @see * cpaDcCompressData * *****************************************************************************/ CpaStatus cpaDcChainPerformOp(CpaInstanceHandle dcInstance, CpaDcSessionHandle pSessionHandle, CpaBufferList *pSrcBuff, CpaBufferList *pDestBuff, CpaDcChainOperations operation, Cpa8U numOpDatas, CpaDcChainOpData *pChainOpData, CpaDcChainRqResults *pResults, void *callbackTag ); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_DC_CHAIN_H */ diff --git a/sys/dev/qat/qat_api/include/dc/cpa_dc_dp.h b/sys/dev/qat/qat_api/include/dc/cpa_dc_dp.h index a0aac8037855..95c34e631b9e 100644 --- a/sys/dev/qat/qat_api/include/dc/cpa_dc_dp.h +++ b/sys/dev/qat/qat_api/include/dc/cpa_dc_dp.h @@ -1,1250 +1,1217 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_dc_dp.h * * @defgroup cpaDcDp Data Compression Data Plane API * * @ingroup cpaDc * * @description * These data structures and functions specify the Data Plane API * for compression and decompression operations. * * This API is recommended for data plane applications, in which the * cost of offload - that is, the cycles consumed by the driver in * sending requests to the hardware, and processing responses - needs * to be minimized. In particular, use of this API is recommended * if the following constraints are acceptable to your application: * * - Thread safety is not guaranteed. Each software thread should * have access to its own unique instance (CpaInstanceHandle) to * avoid contention. * - Polling is used, rather than interrupts (which are expensive). * Implementations of this API will provide a function (not * defined as part of this API) to read responses from the hardware * response queue and dispatch callback functions, as specified on * this API. * - Buffers and buffer lists are passed using physical addresses, * to avoid virtual to physical address translation costs. * - The ability to enqueue one or more requests without submitting * them to the hardware allows for certain costs to be amortized * across multiple requests. * - Only asynchronous invocation is supported. * - There is no support for partial packets. * - Implementations may provide certain features as optional at * build time, such as atomic counters. * - There is no support for stateful operations. * - The "default" instance (CPA_INSTANCE_HANDLE_SINGLE) is not * supported on this API. The specific handle should be obtained * using the instance discovery functions (@ref cpaDcGetNumInstances, * @ref cpaDcGetInstances). * *****************************************************************************/ #ifndef CPA_DC_DP_H #define CPA_DC_DP_H #ifdef __cplusplus extern "C" { #endif #include "cpa_dc.h" /** ***************************************************************************** * @ingroup cpaDcDp * Decompression partial read data. * @description * This structure contains configuration related to requesting * specific chunk of decompression data. * ****************************************************************************/ typedef struct _CpaDcDpPartialReadData { Cpa32U bufferOffset; /**< Number of bytes to skip in a destination buffer (or buffers list) * before writing. At this point only zero is supported. */ Cpa32U dataOffset; /**< The offset in the decompressed data of the first byte written to * the destination buffer. The data offset length should be an integer * multiple of 4KB in order to achieve the best performance. */ Cpa32U length; /**< Size of requested decompressed data chunk. The length should be * an integer multiple of 4KB in order to achieve the best performance. */ } CpaDcDpPartialReadData; /** ***************************************************************************** * @ingroup cpaDcDp * Operation Data for compression data plane API. * * @description * This structure contains data relating to a request to perform * compression processing on one or more data buffers. * * The physical memory to which this structure points should be * at least 8-byte aligned. * * All reserved fields SHOULD NOT be written or read by the * calling code. * * @see * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch ****************************************************************************/ typedef struct _CpaDcDpOpData { Cpa64U reserved0; /**< Reserved for internal use. Source code should not read or write * this field. */ Cpa32U bufferLenToCompress; /**< The number of bytes from the source buffer to compress. This must be * less than, or more typically equal to, the total size of the source * buffer (or buffer list). */ Cpa32U bufferLenForData; /**< The maximum number of bytes that should be written to the destination * buffer. This must be less than, or more typically equal to, the total * size of the destination buffer (or buffer list). */ Cpa64U reserved1; /**< Reserved for internal use. Source code should not read or write */ Cpa64U reserved2; /**< Reserved for internal use. Source code should not read or write */ Cpa64U reserved3; /**< Reserved for internal use. Source code should not read or write */ CpaDcRqResults results; /**< Results of the operation. Contents are valid upon completion. */ CpaInstanceHandle dcInstance; /**< Instance to which the request is to be enqueued */ CpaDcSessionHandle pSessionHandle; /**< DC Session associated with the stream of requests. * This field is only valid when using the session based API functions. * This field must be set to NULL if the application wishes to use * the No-Session (Ns) API. */ CpaPhysicalAddr srcBuffer; /**< Physical address of the source buffer on which to operate. * This is either the location of the data, of length srcBufferLen; or, * if srcBufferLen has the special value @ref CPA_DP_BUFLIST, then * srcBuffer contains the location where a @ref CpaPhysBufferList is * stored. */ Cpa32U srcBufferLen; /**< If the source buffer is a "flat buffer", then this field * specifies the size of the buffer, in bytes. If the source buffer * is a "buffer list" (of type @ref CpaPhysBufferList), then this field * should be set to the value @ref CPA_DP_BUFLIST. */ CpaPhysicalAddr destBuffer; /**< Physical address of the destination buffer on which to operate. * This is either the location of the data, of length destBufferLen; or, * if destBufferLen has the special value @ref CPA_DP_BUFLIST, then * destBuffer contains the location where a @ref CpaPhysBufferList is * stored. */ Cpa32U destBufferLen; /**< If the destination buffer is a "flat buffer", then this field * specifies the size of the buffer, in bytes. If the destination buffer * is a "buffer list" (of type @ref CpaPhysBufferList), then this field * should be set to the value @ref CPA_DP_BUFLIST. */ CpaDcSessionDir sessDirection; /**pSessionHandle was setup using * @ref cpaDcDpInitSession OR pOpData->pSetupData data structure was * initialized for No-Session (Ns) usage. * The instance identified by pOpData->dcInstance has had a * callback function registered via @ref cpaDcDpRegCbFunc. * * @post * None * * @note * A callback of type @ref CpaDcDpCallbackFn is generated in * response to this function call. Any errors generated during * processing are reported as part of the callback status code. * * @see * @ref cpaDcDpPerformOpNow *****************************************************************************/ CpaStatus cpaDcDpEnqueueOp(CpaDcDpOpData *pOpData, const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Enqueue a single decompression request with partial read configuration. * See @CpaDcDpPartialReadData for more details. * * @description * This function enqueues a single request to perform a decompression * operation and allows to specify particular region of decompressed * data to be placed in to the destination buffer (or buffer list). * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. * Callbacks within a session are guaranteed to be in the same order * in which they were submitted. * * The following restrictions apply to the pOpData parameter: * * - The memory MUST be aligned on an 8-byte boundary. * - The reserved fields of the structure MUST NOT be written to * or read from. * - The structure MUST reside in physically contiguous memory. * * @context * This function will not sleep, and hence can be executed in a context * that does not permit sleeping. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in,out] pOpData See @ref cpaDcDpEnqueueOp pOpData description. * * @param[in] pPartReadData Pointer to a structure containing the partial * read configuration parameters. * See @CpaDcDpPartialReadData for more details. * * @param[in] performOpNow See @ref cpaDcDpEnqueueOp performOpNow input * 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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The session identified by pOpData->pSessionHandle was setup using * @ref cpaDcDpInitSession. The instance identified by pOpData->dcInstance * has had a callback function registered via @ref cpaDcDpRegCbFunc. * * @post * None * * @note * A callback of type @ref CpaDcDpCallbackFn is generated in * response to this function call. Any errors generated during * processing are reported as part of the callback status code. * * @see * @ref cpaDcDpPerformOpNow *****************************************************************************/ CpaStatus cpaDcDpEnqueueOpWithPartRead(CpaDcDpOpData *pOpData, CpaDcDpPartialReadData *pPartReadData, const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Enqueue a single compression request with an option set to zero-fill * data after the compression output in the leftover bytes. * * @description * This function enqueues a single request to perform a compression * operation with zero-filling leftover bytes with 4KB alignment * in the destination buffer (or buffer list). * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. * Callbacks within a session are guaranteed to be in the same order * in which they were submitted. * * The following restrictions apply to the pOpData parameter: * * - The memory MUST be aligned on an 8-byte boundary. * - The reserved fields of the structure MUST NOT be written to * or read from. * - The structure MUST reside in physically contiguous memory. * * @context * This function will not sleep, and hence can be executed in a context * that does not permit sleeping. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in,out] pOpData See @ref cpaDcDpEnqueueOp pOpData description. * * @param[in] performOpNow See @ref cpaDcDpEnqueueOp performOpNow input * 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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The session identified by pOpData->pSessionHandle was setup using * @ref cpaDcDpInitSession. The instance identified by pOpData->dcInstance * has had a callback function registered via @ref cpaDcDpRegCbFunc. * * @post * None * * @note * A callback of type @ref CpaDcDpCallbackFn is generated in * response to this function call. Any errors generated during * processing are reported as part of the callback status code. * * @see * @ref cpaDcDpPerformOpNow *****************************************************************************/ CpaStatus cpaDcDpEnqueueOpWithZeroPad(CpaDcDpOpData *pOpData, const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Enqueue multiple requests to the compression data plane API. * * @description * This function enqueues multiple requests to perform compression or * decompression operations. * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. * Separate callbacks will be invoked for each request. * Callbacks within a session and at the same priority are guaranteed * to be in the same order in which they were submitted. * * The following restrictions apply to each element of the pOpData * array: * * - The memory MUST be aligned on an 8-byte boundary. * - The reserved fields of the structure MUST be set to zero. * - The structure MUST reside in physically contiguous memory. * * @context * This function will not sleep, and hence can be executed in a context * that does not permit sleeping. * * @assumptions * Client MUST allocate the request parameters to 8 byte alignment. * Reserved elements of the CpaDcDpOpData structure MUST not used * The CpaDcDpOpData structure MUST reside in physically * contiguous memory. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] numberRequests The number of requests in the array of * CpaDcDpOpData structures. * @param[in] pOpData An array of pointers to CpaDcDpOpData * structures. Each CpaDcDpOpData * structure contains the request parameters for * that request. The client code allocates the * memory for this structure. This component takes * ownership of the memory until it is returned in * the callback, which was registered on the * instance via @ref cpaDcDpRegCbFunc. * See the above Description for some restrictions * that apply to this parameter. * @param[in] performOpNow Flag to indicate whether the operation should be * performed immediately (CPA_TRUE), or simply * enqueued to be performed later (CPA_FALSE). * In the latter case, the request is submitted * to be performed either by calling this function * again with this flag set to CPA_TRUE, or by * invoking the function @ref * cpaDcDpPerformOpNow. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The session identified by pOpData[i]->pSessionHandle was setup using * @ref cpaDcDpInitSession OR pOpData[i]->pSetupData data structure was * initialized for No-Session (Ns) usage. * The instance identified by pOpData[i]->dcInstance has had a * callback function registered via @ref cpaDcDpRegCbFunc. * * @post * None * * @note * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in * response to this function call (one per request). Any errors * generated during processing are reported as part of the callback * status code. * * @see * cpaDcDpEnqueueOp *****************************************************************************/ CpaStatus cpaDcDpEnqueueOpBatch(const Cpa32U numberRequests, CpaDcDpOpData *pOpData[], const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Enqueue multiple decompression request with partial read configuration. * See @CpaDcDpPartialReadData for more details. * * @description * This function enqueues multiple requests to perform decompression * operations and allows to specify particular region of decompressed * data to be placed in to the destination buffer (or buffer list) for * each individual request. * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. * Separate callbacks will be invoked for each request. * Callbacks within a session and at the same priority are guaranteed * to be in the same order in which they were submitted. * * The following restrictions apply to each element of the pOpData * array: * * - The memory MUST be aligned on an 8-byte boundary. * - The reserved fields of the structure MUST be set to zero. * - The structure MUST reside in physically contiguous memory. * * @context * See @ref cpaDcDpEnqueueOpBatch context. * * @assumptions * See @ref cpaDcDpEnqueueOpBatch assumptions. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] numberRequests The number of requests in the array of * CpaDcDpOpData structures. * * @param[in,out] pOpData See @ref cpaDcDpEnqueueOpBatch pOpData for more * details. * * @param[in] pPartReadData An array of pointers to a structures containing * the partial read configuration parameters. * See @CpaDcDpPartialReadData for more details. * * @param[in] performOpNow See @ref cpaDcDpEnqueueOpBatch performOpNow * input 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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * * @pre * The session identified by pOpData[i]->pSessionHandle was setup using * @ref cpaDcDpInitSession. The instance identified by * pOpData[i]->dcInstance has had a callback function registered via * @ref cpaDcDpRegCbFunc. * * @post * None * * @note * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in * response to this function call (one per request). Any errors * generated during processing are reported as part of the callback * status code. * * @see * @ref cpaDcDpEnqueueOp *****************************************************************************/ CpaStatus cpaDcDpEnqueueOpWithPartReadBatch(const Cpa32U numberRequests, CpaDcDpOpData *pOpData[], CpaDcDpPartialReadData *pPartReadData[], const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Enqueue multiple compression requests with an option set to zero-fill * data after the compression output in the leftover bytes. * * @description * This function enqueues multiple requests to perform compression * operations with an option set to zero-fill leftover bytes in the * destination buffer (of buffer list) for each individual request. * Please note that optional zero-filling leftover output buffer bytes * is aligned to 4KB. * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. * Separate callbacks will be invoked for each request. * Callbacks within a session and at the same priority are guaranteed * to be in the same order in which they were submitted. * * The following restrictions apply to each element of the pOpData * array: * * - The memory MUST be aligned on an 8-byte boundary. * - The reserved fields of the structure MUST be set to zero. * - The structure MUST reside in physically contiguous memory. * * @context * See @ref cpaDcDpEnqueueOpBatch context. * * @assumptions * See @ref cpaDcDpEnqueueOpBatch assumptions. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] numberRequests The number of requests in the array of * CpaDcDpOpData structures. * * @param[in,out] pOpData See @ref cpaDcDpEnqueueOpBatch pOpData for more * details. * * @param[in] performOpNow See @ref cpaDcDpEnqueueOpBatch performOpNow * input 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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * * @pre * The session identified by pOpData[i]->pSessionHandle was setup using * @ref cpaDcDpInitSession. The instance identified by * pOpData[i]->dcInstance has had a callback function registered via * @ref cpaDcDpRegCbFunc. * * @post * None * * @note * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in * response to this function call (one per request). Any errors * generated during processing are reported as part of the callback * status code. * * @see * @ref cpaDcDpEnqueueOp *****************************************************************************/ CpaStatus cpaDcDpEnqueueOpWithZeroPadBatch(const Cpa32U numberRequests, CpaDcDpOpData *pOpData[], const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaDcDp * Submit any previously enqueued requests to be performed now on the * compression data plane API. * * @description * This function triggers processing of previously enqueued requests on the * referenced instance. * * * @context * Will not sleep. It can be executed in a context that does not * permit sleeping. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] dcInstance Instance to which the requests will be * submitted. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via @ref cpaDcStartInstance function. * A compression session has been previously setup using the * @ref cpaDcDpInitSession function call. * * @post * None * * @see * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch *****************************************************************************/ CpaStatus cpaDcDpPerformOpNow(CpaInstanceHandle dcInstance); /** ***************************************************************************** * @ingroup cpaDc * Function to return the "partial read" feature support. * * @description * This function is used to determine if given instance supports * "partial read" feature. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[out] pFlag Pointer to boolean flag which indicates * whether a feature is supported. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * None * @see * cpaDcQueryCapabilities() * *****************************************************************************/ CpaStatus cpaDcDpIsPartReadSupported(const CpaInstanceHandle instanceHandle, CpaBoolean *pFlag); /** ***************************************************************************** * @ingroup cpaDc * Function to return the "zero pad" feature support. * * @description * This function is used to determine if given instance supports * "zero pad" feature. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[out] pFlag Pointer to boolean flag which indicates * whether a feature is supported. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * None * @see * cpaDcQueryCapabilities() * *****************************************************************************/ CpaStatus cpaDcDpIsZeroPadSupported(const CpaInstanceHandle instanceHandle, CpaBoolean *pFlag); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_DC_DP_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_common.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_common.h index a7cdb711e60b..87c73fe7f05d 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_common.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_common.h @@ -1,682 +1,649 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_common.h * * @defgroup cpaCy Cryptographic API * * @ingroup cpa * * @description * These functions specify the Cryptographic API. * *****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_common.h * @defgroup cpaCyCommon Cryptographic Common API * * @ingroup cpaCy * * @description * This file specifies items which are common for both the asymmetric * (public key cryptography) and the symmetric operations for the * Cryptographic API. * *****************************************************************************/ #ifndef CPA_CY_COMMON_H #define CPA_CY_COMMON_H #ifdef __cplusplus extern "C" { #endif #include "cpa.h" /** ***************************************************************************** * @ingroup cpa_cyCommon * CPA CY Major Version Number * @description * The CPA_CY API major version number. This number will be incremented * when significant churn to the API has occurred. The combination of the * major and minor number definitions represent the complete version number * for this interface. * *****************************************************************************/ #define CPA_CY_API_VERSION_NUM_MAJOR (3) /** ***************************************************************************** * @ingroup cpa_cyCommon * CPA CY Minor Version Number * @description * The CPA_CY API minor version number. This number will be incremented * when minor changes to the API has occurred. The combination of the major * and minor number definitions represent the complete version number for * this interface. * *****************************************************************************/ #define CPA_CY_API_VERSION_NUM_MINOR (0) /** ***************************************************************************** * @file cpa_cy_common.h * @ingroup cpa_cyCommon * CPA CY API version at least * @description * The minimal supported CPA_CY API version. Allow to check if the API * version is equal or above some version to avoid compilation issues * with an older API version. * *****************************************************************************/ #define CPA_CY_API_VERSION_AT_LEAST(major, minor) \ (CPA_CY_API_VERSION_NUM_MAJOR > major || \ (CPA_CY_API_VERSION_NUM_MAJOR == major && \ CPA_CY_API_VERSION_NUM_MINOR >= minor)) /** ***************************************************************************** * @file cpa_cy_common.h * @ingroup cpa_cyCommon * CPA CY API version less than * @description * The maximum supported CPA_CY API version. Allow to check if the API * version is below some version to avoid compilation issues with a newer * API version. * *****************************************************************************/ #define CPA_CY_API_VERSION_LESS_THAN(major, minor) \ (CPA_CY_API_VERSION_NUM_MAJOR < major || \ (CPA_CY_API_VERSION_NUM_MAJOR == major && \ CPA_CY_API_VERSION_NUM_MINOR < minor)) /** ***************************************************************************** * @file cpa_cy_common.h * @ingroup cpaCyCommon * Request priority * @description * Enumeration of priority of the request to be given to the API. * Currently two levels - HIGH and NORMAL are supported. HIGH priority * requests will be prioritized on a "best-effort" basis over requests * that are marked with a NORMAL priority. * *****************************************************************************/ typedef enum _CpaCyPriority { CPA_CY_PRIORITY_NORMAL = 1, /**< Normal priority */ CPA_CY_PRIORITY_HIGH /**< High priority */ } CpaCyPriority; /*****************************************************************************/ /* Callback Definitions */ /*****************************************************************************/ /** ***************************************************************************** * @ingroup cpaCyCommon * Definition of the crypto generic callback function * * @description * This data structure specifies the prototype for a generic 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 Opaque value provided by user while making individual * function call. * @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 the operation data that was * submitted in the request * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyKeyGenSsl() * *****************************************************************************/ typedef void (*CpaCyGenericCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData); /** ***************************************************************************** * @ingroup cpaCyCommon * Definition of generic callback function with an additional output * CpaFlatBuffer parameter. * * @description * This data structure specifies the prototype for a generic callback * function which provides an output buffer (of type CpaFlatBuffer). * * @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 call. * @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 the operation data that was * submitted in the request * @param[in] pOut Pointer to the output buffer provided in the request * invoking this callback. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * None * *****************************************************************************/ typedef void (*CpaCyGenFlatBufCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpdata, CpaFlatBuffer *pOut); /** ***************************************************************************** * @ingroup cpaCyCommon * Function to return the size of the memory which must be allocated for * the pPrivateMetaData member of CpaBufferList. * * @description * This function is used obtain the size (in bytes) required to allocate * a buffer descriptor for the pPrivateMetaData member in the * CpaBufferList the structure. * Should the function return zero then no meta data is required for the * buffer list. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[in] numBuffers The number of pointers in the CpaBufferList. * this is the maximum number of CpaFlatBuffers * which may be contained in this CpaBufferList. * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be * allocated when the client wishes to allocate * a cpaFlatBuffer * * @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_UNSUPPORTED Function is not supported. * * @pre * None. * @post * None * @note * None * @see * cpaCyGetInstances() * *****************************************************************************/ CpaStatus cpaCyBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, Cpa32U numBuffers, Cpa32U *pSizeInBytes); /** ***************************************************************************** * @ingroup cpaCyCommon * Function to return a string indicating the specific error that occurred * for a particular instance. * * @description * When a function invocation on a particular instance returns an error, * the client can invoke this function to query the instance for a null * terminated string which describes the general error condition, and if * available additional text on the specific error. * The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for * the buffer string. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[in] errStatus The error condition that occurred * @param[out] pStatusText Pointer to the string buffer that will be * updated with a null terminated status text * string. * The invoking application MUST allocate this * buffer to be CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Note, In this scenario it * is INVALID to call this function a further * time. * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None. * @post * None * @note * None * @see * CpaStatus * *****************************************************************************/ CpaStatus cpaCyGetStatusText(const CpaInstanceHandle instanceHandle, CpaStatus errStatus, Cpa8S *pStatusText); /*****************************************************************************/ /* Instance Discovery Functions */ /*****************************************************************************/ /** ***************************************************************************** * @ingroup cpaCyCommon * Get the number of instances that are supported by the API * implementation. * * @description * This function will get the number of instances that are supported * by an implementation of the Cryptographic API. This number is then * used to determine the size of the array that must be passed to * @ref cpaCyGetInstances(). * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[out] pNumInstances Pointer to where the number of * instances 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaCyGetInstances * *****************************************************************************/ CpaStatus cpaCyGetNumInstances(Cpa16U *pNumInstances); /** ***************************************************************************** * @ingroup cpaCyCommon * Get the handles to the instances that are supported by the * API implementation. * * @description * This function will return handles to the instances that are * supported by an implementation of the Cryptographic API. These * instance handles can then be used as input parameters with other * Cryptographic API functions. * * This function will populate an array that has been allocated by the * caller. The size of this API will have been determined by the * cpaCyGetNumInstances() function. * * @context * This function MUST NOT be called from an interrupt context as it MAY * sleep. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] numInstances Size of the array. If the value is not * the same as the number of instances * supported, then an error (@ref * CPA_STATUS_INVALID_PARAM) is returned. * @param[in,out] cyInstances Pointer to where the instance * handles 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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated * * @see * cpaCyGetNumInstances * *****************************************************************************/ CpaStatus cpaCyGetInstances(Cpa16U numInstances, CpaInstanceHandle *cyInstances); /** ***************************************************************************** * @ingroup cpaCyCommon * Function to get information on a particular instance. * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyInstanceGetInfo2. * * @description * This function will provide instance specific information through a * @ref CpaInstanceInfo structure. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API to be * initialized. * @param[out] pInstanceInfo Pointer to the memory location allocated by * the client into which the CpaInstanceInfo * structure 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_UNSUPPORTED Function is not supported. * * @pre * The client has retrieved an instanceHandle from successive calls to * @ref cpaCyGetNumInstances and @ref cpaCyGetInstances. * @post * None * @note * None * @see * cpaCyGetNumInstances, * cpaCyGetInstances, * CpaInstanceInfo * *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyInstanceGetInfo(const CpaInstanceHandle instanceHandle, struct _CpaInstanceInfo * pInstanceInfo); /** ***************************************************************************** * @ingroup cpaCyCommon * Function to get information on a particular instance. * * @description * This function will provide instance specific information through a * @ref CpaInstanceInfo2 structure. * Supersedes @ref cpaCyInstanceGetInfo. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API to be * initialized. * @param[out] pInstanceInfo2 Pointer to the memory location allocated by * the client into which the CpaInstanceInfo2 * structure 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_UNSUPPORTED Function is not supported. * * @pre * The client has retrieved an instanceHandle from successive calls to * @ref cpaCyGetNumInstances and @ref cpaCyGetInstances. * @post * None * @note * None * @see * cpaCyGetNumInstances, * cpaCyGetInstances, * CpaInstanceInfo * *****************************************************************************/ CpaStatus cpaCyInstanceGetInfo2(const CpaInstanceHandle instanceHandle, CpaInstanceInfo2 * pInstanceInfo2); /*****************************************************************************/ /* Instance Notification Functions */ /*****************************************************************************/ /** ***************************************************************************** * @ingroup cpaCyCommon * Callback function for instance notification support. * * @description * This is the prototype for the instance notification callback function. * The callback function is passed in as a parameter to the * @ref cpaCyInstanceSetNotificationCb function. * * @context * This function will be executed in a context that requires that sleeping * MUST NOT be permitted. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pCallbackTag Opaque value provided by user while making * individual function calls. * @param[in] instanceEvent The event that will trigger this function to * get invoked. * * @retval * None * @pre * Component has been initialized and the notification function has been * set via the cpaCyInstanceSetNotificationCb function. * @post * None * @note * None * @see * cpaCyInstanceSetNotificationCb(), * *****************************************************************************/ typedef void (*CpaCyInstanceNotificationCbFunc)( const CpaInstanceHandle instanceHandle, void * pCallbackTag, const CpaInstanceEvent instanceEvent); /** ***************************************************************************** * @ingroup cpaCyCommon * Subscribe for instance notifications. * * @description * Clients of the CpaCy interface can subscribe for instance notifications * by registering a @ref CpaCyInstanceNotificationCbFunc function. * * @context * This function may be called from any context. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pInstanceNotificationCb Instance notification callback * function pointer. * @param[in] pCallbackTag Opaque value provided by user while * making individual function calls. * * @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_UNSUPPORTED Function is not supported. * * @pre * Instance has been initialized. * @post * None * @note * None * @see * CpaCyInstanceNotificationCbFunc * *****************************************************************************/ CpaStatus cpaCyInstanceSetNotificationCb( const CpaInstanceHandle instanceHandle, const CpaCyInstanceNotificationCbFunc pInstanceNotificationCb, void *pCallbackTag); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_COMMON_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_dh.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_dh.h index c99aa449ec06..b82bf63642a9 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_dh.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_dh.h @@ -1,514 +1,481 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_dh.h * * @defgroup cpaCyDh Diffie-Hellman (DH) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) operations for use with Diffie-Hellman algorithm. * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). *****************************************************************************/ #ifndef CPA_CY_DH_H #define CPA_CY_DH_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyDh * Diffie-Hellman Phase 1 Key Generation Data. * @description * This structure lists the different items that are required in the * cpaCyDhKeyGenPhase1 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 with the * CpaCyDhPhase1KeyGenOpData structure. * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyDhKeyGenPhase1 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. primeP.pData[0] = MSB. * *****************************************************************************/ typedef struct _CpaCyDhPhase1KeyGenOpData { CpaFlatBuffer primeP; /**< Flat buffer containing a pointer to the random odd prime number (p). * The bit-length of this number may be one of 768, 1024, 1536, 2048, * 3072, 4096 or 8192. */ CpaFlatBuffer baseG; /**< Flat buffer containing a pointer to base (g). This MUST comply with * the following: * 0 < g < p. */ CpaFlatBuffer privateValueX; /**< Flat buffer containing a pointer to the private value (x). This is a * random value which MUST satisfy the following condition: * 0 < PrivateValueX < (PrimeP - 1) * * Refer to PKCS #3: Diffie-Hellman Key-Agreement Standard for details. * The client creating this data MUST ensure the compliance of this value * with the standard. Note: This value is also needed to complete local * phase 2 Diffie-Hellman operation.*/ } CpaCyDhPhase1KeyGenOpData; /** ***************************************************************************** * @ingroup cpaCyDh * Diffie-Hellman Phase 2 Secret Key Generation Data. * @description * This structure lists the different items that required in the * cpaCyDhKeyGenPhase2Secret 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 with * the callback. * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyDhKeyGenPhase2Secret * 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. primeP.pData[0] = MSB. * *****************************************************************************/ typedef struct _CpaCyDhPhase2SecretKeyGenOpData { CpaFlatBuffer primeP; /**< Flat buffer containing a pointer to the random odd prime number (p). * The bit-length of this number may be one of 768, 1024, 1536, 2048, * 3072, 4096 or 8192. * This SHOULD be same prime number as was used in the phase 1 key * generation operation. */ CpaFlatBuffer remoteOctetStringPV; /**< Flat buffer containing a pointer to the remote entity * octet string Public Value (PV). */ CpaFlatBuffer privateValueX; /**< Flat buffer containing a pointer to the private value (x). This * value may have been used in a call to the cpaCyDhKeyGenPhase1 function. * This is a random value which MUST satisfy the following condition: * 0 < privateValueX < (primeP - 1). */ } CpaCyDhPhase2SecretKeyGenOpData; /** ***************************************************************************** * @ingroup cpaCyDh * Diffie-Hellman Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyDhStats64. * @description * This structure contains statistics on the Diffie-Hellman operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. ****************************************************************************/ typedef struct _CpaCyDhStats { Cpa32U numDhPhase1KeyGenRequests; /**< Total number of successful Diffie-Hellman phase 1 key * generation requests. */ Cpa32U numDhPhase1KeyGenRequestErrors; /**< Total number of Diffie-Hellman phase 1 key generation requests * that had an error and could not be processed. */ Cpa32U numDhPhase1KeyGenCompleted; /**< Total number of Diffie-Hellman phase 1 key generation operations * that completed successfully. */ Cpa32U numDhPhase1KeyGenCompletedErrors; /**< Total number of Diffie-Hellman phase 1 key generation operations * that could not be completed successfully due to errors. */ Cpa32U numDhPhase2KeyGenRequests; /**< Total number of successful Diffie-Hellman phase 2 key * generation requests. */ Cpa32U numDhPhase2KeyGenRequestErrors; /**< Total number of Diffie-Hellman phase 2 key generation requests * that had an error and could not be processed. */ Cpa32U numDhPhase2KeyGenCompleted; /**< Total number of Diffie-Hellman phase 2 key generation operations * that completed successfully. */ Cpa32U numDhPhase2KeyGenCompletedErrors; /**< Total number of Diffie-Hellman phase 2 key generation operations * that could not be completed successfully due to errors. */ } CpaCyDhStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyDh * Diffie-Hellman Statistics (64-bit version). * @description * This structure contains the 64-bit version of the statistics on the * Diffie-Hellman operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. ****************************************************************************/ typedef struct _CpaCyDhStats64 { Cpa64U numDhPhase1KeyGenRequests; /**< Total number of successful Diffie-Hellman phase 1 key * generation requests. */ Cpa64U numDhPhase1KeyGenRequestErrors; /**< Total number of Diffie-Hellman phase 1 key generation requests * that had an error and could not be processed. */ Cpa64U numDhPhase1KeyGenCompleted; /**< Total number of Diffie-Hellman phase 1 key generation operations * that completed successfully. */ Cpa64U numDhPhase1KeyGenCompletedErrors; /**< Total number of Diffie-Hellman phase 1 key generation operations * that could not be completed successfully due to errors. */ Cpa64U numDhPhase2KeyGenRequests; /**< Total number of successful Diffie-Hellman phase 2 key * generation requests. */ Cpa64U numDhPhase2KeyGenRequestErrors; /**< Total number of Diffie-Hellman phase 2 key generation requests * that had an error and could not be processed. */ Cpa64U numDhPhase2KeyGenCompleted; /**< Total number of Diffie-Hellman phase 2 key generation operations * that completed successfully. */ Cpa64U numDhPhase2KeyGenCompletedErrors; /**< Total number of Diffie-Hellman phase 2 key generation operations * that could not be completed successfully due to errors. */ } CpaCyDhStats64; /** ***************************************************************************** * @ingroup cpaCyDh * Function to implement Diffie-Hellman phase 1 operations. * * @description * This function may be used to implement the Diffie-Hellman phase 1 * operations as defined in the PKCS #3 standard. It may be used to * generate the (local) octet string public value (PV) key. * The prime number sizes specified in RFC 2409, 4306, and part of * RFC 3526 are supported (bit size 6144 from RFC 3536 is not * supported). * * @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] pDhPhase1Cb Pointer to a callback function to be invoked * when the operation is complete. If the * pointer 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] pPhase1KeyGenData Structure containing all the data needed * to perform the DH Phase 1 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] pLocalOctetStringPV Pointer to memory allocated by the client * into which the (local) octet string Public * Value (PV) will be written. This value * needs to be sent to the remote entity with * which Diffie-Hellman is negotiating. * The size of this buffer in bytes (as * represented by the dataLenInBytes field) * MUST be at least big enough to store * the public value, which may have a bit * length up to that of pPrimeP. * 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 pDhPhase1Cb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function * call. Any errors generated during processing are reported in the * structure returned in the callback. * * @see * CpaCyGenFlatBufCbFunc, * CpaCyDhPhase1KeyGenOpData * *****************************************************************************/ CpaStatus cpaCyDhKeyGenPhase1(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pDhPhase1Cb, void *pCallbackTag, const CpaCyDhPhase1KeyGenOpData *pPhase1KeyGenData, CpaFlatBuffer *pLocalOctetStringPV); /** ***************************************************************************** * @ingroup cpaCyDh * Function to implement Diffie-Hellman phase 2 operations. * * @description * This function may be used to implement the Diffie-Hellman phase 2 * operation as defined in the PKCS #3 standard. It may be used to * generate the Diffie-Hellman shared secret key. * * @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] pDhPhase2Cb Pointer to a callback function to be * invoked when the operation is complete. * If the pointer 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] pPhase2SecretKeyGenData Structure containing all the data * needed to perform the DH Phase 2 * secret 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] pOctetStringSecretKey Pointer to memory allocated by the * client into which the octet string * secret key will be written. * The size of this buffer in bytes (as * represented by the dataLenInBytes field) * MUST be at least big enough to store * the public value, which may have a bit * length up to that of pPrimeP. * 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 pDhPhase2Cb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function * call. Any errors generated during processing are reported in the * structure returned in the callback. * * @see * CpaCyGenFlatBufCbFunc, * CpaCyDhPhase2SecretKeyGenOpData * *****************************************************************************/ CpaStatus cpaCyDhKeyGenPhase2Secret(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pDhPhase2Cb, void *pCallbackTag, const CpaCyDhPhase2SecretKeyGenOpData *pPhase2SecretKeyGenData, CpaFlatBuffer *pOctetStringSecretKey); /** ***************************************************************************** * @ingroup cpaCyDh * Query statistics for Diffie-Hellman operations * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyDhQueryStats64(). * * @description * This function will query a specific Instance handle for Diffie- * Hellman statistics. The user MUST allocate the CpaCyDhStats * structure and pass the reference to that structure into this function * call. This function writes the statistic results into the passed in * CpaCyDhStats 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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pDhStats 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 * CpaCyDhStats *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyDhQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCyDhStats *pDhStats); /** ***************************************************************************** * @ingroup cpaCyDh * Query statistics (64-bit version) for Diffie-Hellman operations * * @description * This function will query a specific Instance handle for the 64-bit * version of the Diffie-Hellman statistics. The user MUST allocate the * CpaCyDhStats64 structure and pass the reference to that structure into * this function call. This function writes the statistic results into * the passed in CpaCyDhStats64 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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pDhStats 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 * CpaCyDhStats64 *****************************************************************************/ CpaStatus cpaCyDhQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyDhStats64 *pDhStats); /*****************************************************************************/ #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_DH_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_dsa.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_dsa.h index eea346ddadae..149a888f1744 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_dsa.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_dsa.h @@ -1,1443 +1,1410 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* 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 */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_ec.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_ec.h index e6466ab7476a..45f724a8d629 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_ec.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_ec.h @@ -1,1124 +1,1091 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_ec.h * * @defgroup cpaCyEc Elliptic Curve (EC) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) Elliptic Curve (EC) operations. * * All implementations will support at least the following: * * - "NIST RECOMMENDED ELLIPTIC CURVES FOR FEDERAL GOVERNMENT USE" * as defined by * http://csrc.nist.gov/groups/ST/toolkit/documents/dss/NISTReCur.pdf * * - Random curves where the max(log2(q), log2(n) + log2(h)) <= 512 * where q is the modulus, n is the order of the curve and h is the * cofactor * * For Montgomery and Edwards 25519 and 448 elliptic curves, * the following operations are supported: * 1. Montgomery 25519 Curve | scalar point Multiplication * Input: Montgomery affine coordinate X of point P * Scalar k * Output: Montgomery affine coordinate X of point [k]P * Decode: Scalar k always decoded by implementation * * 2. Montgomery 25519 Curve | generator point Multiplication * Input: Scalar k * Output: Montgomery affine coordinate X of point [k]G * Decode: Scalar k always decoded by implementation * * 3. Twisted Edwards 25519 Curve | scalar point Multiplication * Input: Twisted Edwards affine coordinate X of point P * Twisted Edwards affine coordinate Y of point P * Scalar k * Output: Twisted Edwards affine coordinate X of point [k]P * Twisted Edwards affine coordinate Y of point [k]P * Decode: Caller must supply parameters in MSB order, the * implementation will not explicitly decode according * to RFC#7748 Section 5 * * 4. Twisted Edwards 25519 Curve | generator point Multiplication * Input: Scalar k * Output: Twisted Edwards affine coordinate X of point [k]G * Twisted Edwards affine coordinate Y of point [k]G * Decode: Caller must supply parameters in MSB order, the * implementation will not explicitly decode according * to RFC#7748 Section 5 * * 5. Montgomery 448 Curve | scalar point Multiplication * Input: Montgomery affine coordinate X of point P * Scalar k * Output: Montgomery affine coordinate X of point [k]P * Decode: Scalar k always decoded by implementation * * 6. Montgomery 448 Curve | generator point Multiplication * Input: Scalar k * Output: Montgomery affine coordinate X of point [k]G * Decode: Scalar k always decoded by implementation * * 7. Edwards 448 Curve | scalar point Multiplication * Input: Edwards affine coordinate X of point P * Edwards affine coordinate Y of point P * Scalar k * Output: Edwards affine coordinate X of point [k]P * Edwards affine coordinate Y of point [k]P * Decode: Caller must supply parameters in MSB order, the * implementation will not explicitly decode according * to RFC#7748 Section 5 * * 8. Edwards 448 Curve | generator point Multiplication * Input: Scalar k * Output: Edwards affine coordinate X of point [k]G * Edwards affine coordinate Y of point [k]G * Decode: Caller must supply parameters in MSB order, the * implementation will not explicitly decode according * to RFC#7748 Section 5 * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). * * In addition, the bit length of large numbers passed to the API * MUST NOT exceed 576 bits for Elliptic Curve operations. *****************************************************************************/ #ifndef CPA_CY_EC_H_ #define CPA_CY_EC_H_ #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyEc * Field types for Elliptic Curve * @description * As defined by FIPS-186-3, for each cryptovariable length, there are * two kinds of fields. *
    *
  • A prime field is the field GF(p) which contains a prime number * p of elements. The elements of this field are the integers modulo * p, and the field arithmetic is implemented in terms of the * arithmetic of integers modulo p.
    • * *
  • A binary field is the field GF(2^m) which contains 2^m elements * for some m (called the degree of the field). The elements of * this field are the bit strings of length m, and the field * arithmetic is implemented in terms of operations on the bits.
    • *
*****************************************************************************/ typedef enum _CpaCyEcFieldType { CPA_CY_EC_FIELD_TYPE_PRIME = 1, /**< A prime field, GF(p) */ CPA_CY_EC_FIELD_TYPE_BINARY, /**< A binary field, GF(2^m) */ } CpaCyEcFieldType; /** ***************************************************************************** * @ingroup cpaCyEc * Enumeration listing curve types to use with generic multiplication * and verification routines. * * @description * This structure contains a list of different elliptic curve types. * EC Point multiplication and other operations depend on the type of * the curve. * * @see * cpaCyEcGenericPointMultiply() * cpaCyEcGenericPointVerify() * *****************************************************************************/ typedef enum _CpaCyEcCurveType { CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_PRIME = 1, /**< A Weierstrass curve with arithmetic in terms of the * arithmetic of integers modulo p over a prime field. */ CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_BINARY, /**< A Weierstrass curve with arithmetic in terms of operations on bits * over a binary field. */ CPA_CY_EC_CURVE_TYPE_WEIERSTRASS_KOBLITZ_BINARY, /**< A Weierstrass-koblitz curve with arithmetic in terms of operations on * the bits over a binary field. */ } CpaCyEcCurveType; /** ***************************************************************************** * @ingroup cpaCyEc * Curve types for Elliptic Curves defined in RFC#7748 * @description * As defined by RFC 7748, there are four elliptic curves in this * group. The Montgomery curves are denoted curve25519 and curve448, * and the birationally equivalent Twisted Edwards curves are denoted * edwards25519 and edwards448 * *****************************************************************************/ typedef enum _CpaCyEcMontEdwdsCurveType { CPA_CY_EC_MONTEDWDS_CURVE25519_TYPE = 1, /**< Montgomery 25519 curve */ CPA_CY_EC_MONTEDWDS_ED25519_TYPE, /**< Edwards 25519 curve */ CPA_CY_EC_MONTEDWDS_CURVE448_TYPE, /**< Montgomery 448 curve */ CPA_CY_EC_MONTEDWDS_ED448_TYPE, /**< Edwards 448 curve */ } CpaCyEcMontEdwdsCurveType; /** ***************************************************************************** * @ingroup cpaCyEc * Curve parameters for a Weierstrass type curve. * * @description * This structure contains curve parameters for Weierstrass type * curve: y^2 = x^3 + ax + b * 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 callback function. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * The legend used in this structure is borrowed from RFC7748 * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the function, and before it * has been returned in the callback, undefined behavior will result. * * @see * CpaCyEcCurveParameters * CpaCyEcFieldType * *****************************************************************************/ typedef struct _CpaCyEcCurveParametersWeierstrass { CpaCyEcFieldType fieldType; /**< Prime or Binary */ CpaFlatBuffer p; /**< Prime modulus or irreducible polynomial over GF(2^m) */ CpaFlatBuffer a; /**< a coefficient */ CpaFlatBuffer b; /**< b coefficient */ CpaFlatBuffer h; /**< Cofactor */ } CpaCyEcCurveParametersWeierstrass; /** ***************************************************************************** * @ingroup cpaCyEc * Union characterised by a specific curve. * * @description * This union allows for the characterisation of different curve types * encapsulated in one data type. The intention is that new curve types * will be added in the future. * * @note * * @see * CpaCyEcCurveParametersWeierstrass * *****************************************************************************/ typedef union _CpaCyEcCurveParameters { CpaCyEcCurveParametersWeierstrass weierstrassParameters; } CpaCyEcCurveParameters; /** ***************************************************************************** * @ingroup cpaCyEc * Unified curve parameters. * * @description * This structure provides a single data type that can describe a number * of different curve types. The intention is to add further * curve types in the future, thus the union field will allow for that * expansion. * * 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. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the function, and before it * has been returned in the callback, undefined behavior will result. * * @see * CpaCyEcCurveParameters * cpaCyEcGenericPointMultiply * cpaCyEcGenericPointVerify * *****************************************************************************/ typedef struct _CpaCyEcCurve { CpaCyEcCurveType curveType; CpaCyEcCurveParameters parameters; } CpaCyEcCurve; /** ***************************************************************************** * @ingroup cpaCyEc * EC Point Multiplication Operation Data. * * @description * This structure contains the operation data for the cpaCyEcPointMultiply * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcPointMultiply * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcPointMultiply() * *****************************************************************************/ typedef struct _CpaCyEcPointMultiplyOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaFlatBuffer xg; /**< x coordinate of curve point */ CpaFlatBuffer yg; /**< y coordinate of curve point */ CpaFlatBuffer a; /**< a elliptic curve coefficient */ CpaFlatBuffer b; /**< b elliptic curve coefficient */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^m)*/ CpaFlatBuffer h; /**< cofactor of the operation. * If the cofactor is NOT required then set the cofactor to 1 or the * data pointer of the Flat Buffer to NULL. */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcPointMultiplyOpData CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyEc * Generic EC Point Multiplication Operation Data. * * @description * This structure contains a generic EC point and a multiplier for use with * cpaCyEcGenericPointMultiply. This is common for representing all EC * points, irrespective of curve type: Weierstrass, Montgomery and Twisted * Edwards (at this time only Weierstrass are supported). The same * point + multiplier format can be used when performing generator * multiplication, in which case the xP, yP supplied in this structure will * be ignored by QAT API library & a generator point will be inserted in * their place. * * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcGenericPointMultiply * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcGenericPointMultiply() * *****************************************************************************/ typedef struct _CpaCyEcGenericPointMultiplyOpData { CpaFlatBuffer k; /** 0 and k < n) */ CpaFlatBuffer xP; /** pair specified in the structure * lies on the curve indicated in the cpaCyEcGenericPointVerify API. * * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcGenericPointVerify * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcGenericPointVerify() * *****************************************************************************/ typedef struct _CpaCyEcGenericPointVerifyOpData { CpaFlatBuffer xP; /** 0 and k < n) */ CpaFlatBuffer xg; /**< x coordinate of curve point */ CpaFlatBuffer yg; /**< y coordinate of curve point */ CpaFlatBuffer a; /**< a equation coefficient */ CpaFlatBuffer b; /**< b equation coefficient */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^r) */ CpaFlatBuffer h; /**< cofactor of the operation. * If the cofactor is NOT required then set the cofactor to 1 or the * data pointer of the Flat Buffer to NULL. * There are some restrictions on the value of the cofactor. * Implementations of this API will support at least the following: *
    *
  • NIST standard curves and their cofactors (1, 2 and 4)
    • * *
  • Random curves where max(log2(p), log2(n)+log2(h)) <= 512, where * p is the modulus, n is the order of the curve and h is the cofactor *
    • *
*/ CpaCyEcFieldType fieldType; /**< field type for the operation */ CpaBoolean pointVerify; /**< set to CPA_TRUE to do a verification before the multiplication */ } CpaCyEcdhPointMultiplyOpData; /** ***************************************************************************** * @ingroup cpaCyEcdh * Cryptographic ECDH Statistics. * @description * This structure contains statistics on the Cryptographic ECDH * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyEcdhStats64 { Cpa64U numEcdhPointMultiplyRequests; /**< Total number of ECDH Point Multiplication operation requests. */ Cpa64U numEcdhPointMultiplyRequestErrors; /**< Total number of ECDH Point Multiplication operation requests that had * an error and could not be processed. */ Cpa64U numEcdhPointMultiplyCompleted; /**< Total number of ECDH Point Multiplication operation requests that * completed successfully. */ Cpa64U numEcdhPointMultiplyCompletedError; /**< Total number of ECDH Point Multiplication operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdhRequestCompletedOutputInvalid; /**< Total number of ECDH Point Multiplication or Point Verify operation * requests that could not be completed successfully due to an invalid * output. * Note that this does not indicate an error. */ } CpaCyEcdhStats64; /** ***************************************************************************** * @ingroup cpaCyEcdh * Definition of callback function invoked for cpaCyEcdhPointMultiply * requests. * * @description * This is the prototype for the CpaCyEcdhPointMultiplyCbFunc 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] pXk Output x coordinate from the request. * @param[in] pYk Output y coordinate from the request. * @param[in] multiplyStatus Status of the point multiplication and the * verification when the pointVerify bit is set * in the CpaCyEcdhPointMultiplyOpData structure. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcdhPointMultiply() * *****************************************************************************/ typedef void (*CpaCyEcdhPointMultiplyCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean multiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @ingroup cpaCyEcdh * ECDH Point Multiplication. * * @description * This function performs ECDH Point Multiplication as defined in * ANSI X9.63 2001 section 5.4 * * @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] pMultiplyStatus In synchronous mode, the status of the point * multiplication and the verification when the * pointVerify bit is set in the * CpaCyEcdhPointMultiplyOpData structure. Set to * CPA_FALSE if the point is NOT on the curve or * at infinity. Set to CPA_TRUE if the point is * on the curve. * @param[out] pXk Pointer to x coordinate flat buffer. * @param[out] pYk Pointer to y coordinate 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcdhPointMultiplyCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcdhPointMultiplyOpData, * CpaCyEcdhPointMultiplyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcdhPointMultiply(const CpaInstanceHandle instanceHandle, const CpaCyEcdhPointMultiplyCbFunc pCb, void *pCallbackTag, const CpaCyEcdhPointMultiplyOpData *pOpData, CpaBoolean *pMultiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @ingroup cpaCyEcdh * Query statistics for a specific ECDH instance. * * @description * This function will query a specific instance of the ECDH implementation * for statistics. The user MUST allocate the CpaCyEcdhStats64 structure * and pass the reference to that structure into this function call. This * function writes the statistic results into the passed in * CpaCyEcdhStats64 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] pEcdhStats 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 * CpaCyEcdhStats64 *****************************************************************************/ CpaStatus cpaCyEcdhQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyEcdhStats64 *pEcdhStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /*CPA_CY_ECDH_H_*/ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_ecdsa.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_ecdsa.h index f1bb2b0240dc..af1eea223e89 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_ecdsa.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_ecdsa.h @@ -1,852 +1,819 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_ecdsa.h * * @defgroup cpaCyEcdsa Elliptic Curve Digital Signature Algorithm (ECDSA) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) Elliptic Curve Digital Signature Algorithm (ECDSA) * operations. * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). * * In addition, the bit length of large numbers passed to the API * MUST NOT exceed 576 bits for Elliptic Curve operations. *****************************************************************************/ #ifndef CPA_CY_ECDSA_H_ #define CPA_CY_ECDSA_H_ #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" #include "cpa_cy_ec.h" /** ***************************************************************************** * @ingroup cpaCyEcdsa * ECDSA Sign R Operation Data. * @description * This structure contains the operation data for the cpaCyEcdsaSignR * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcdsaSignR * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcdsaSignR() * *****************************************************************************/ typedef struct _CpaCyEcdsaSignROpData { CpaFlatBuffer xg; /**< x coordinate of base point G */ CpaFlatBuffer yg; /**< y coordinate of base point G */ CpaFlatBuffer n; /**< order of the base point G, which shall be prime */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^r) */ CpaFlatBuffer a; /**< a elliptic curve coefficient */ CpaFlatBuffer b; /**< b elliptic curve coefficient */ CpaFlatBuffer k; /**< random value (k > 0 and k < n) */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcdsaSignROpData; /** ***************************************************************************** * @ingroup cpaCyEcdsa * ECDSA Sign S Operation Data. * @description * This structure contains the operation data for the cpaCyEcdsaSignS * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcdsaSignS * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcdsaSignS() * *****************************************************************************/ typedef struct _CpaCyEcdsaSignSOpData { CpaFlatBuffer m; /**< digest of the message to be signed */ CpaFlatBuffer d; /**< private key */ CpaFlatBuffer r; /**< Ecdsa r signature value */ CpaFlatBuffer k; /**< random value (k > 0 and k < n) */ CpaFlatBuffer n; /**< order of the base point G, which shall be prime */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcdsaSignSOpData; /** ***************************************************************************** * @ingroup cpaCyEcdsa * ECDSA Sign R & S Operation Data. * @description * This structure contains the operation data for the cpaCyEcdsaSignRS * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcdsaSignRS * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcdsaSignRS() * *****************************************************************************/ typedef struct _CpaCyEcdsaSignRSOpData { CpaFlatBuffer xg; /**< x coordinate of base point G */ CpaFlatBuffer yg; /**< y coordinate of base point G */ CpaFlatBuffer n; /**< order of the base point G, which shall be prime */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^r) */ CpaFlatBuffer a; /**< a elliptic curve coefficient */ CpaFlatBuffer b; /**< b elliptic curve coefficient */ CpaFlatBuffer k; /**< random value (k > 0 and k < n) */ CpaFlatBuffer m; /**< digest of the message to be signed */ CpaFlatBuffer d; /**< private key */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcdsaSignRSOpData; /** ***************************************************************************** * @ingroup cpaCyEcdsa * ECDSA Verify Operation Data, for Public Key. * @description * This structure contains the operation data for the CpaCyEcdsaVerify * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcdsaVerify * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * CpaCyEcdsaVerify() * *****************************************************************************/ typedef struct _CpaCyEcdsaVerifyOpData { CpaFlatBuffer xg; /**< x coordinate of base point G */ CpaFlatBuffer yg; /**< y coordinate of base point G */ CpaFlatBuffer n; /**< order of the base point G, which shall be prime */ CpaFlatBuffer q; /**< prime modulus or irreducible polynomial over GF(2^r) */ CpaFlatBuffer a; /**< a elliptic curve coefficient */ CpaFlatBuffer b; /**< b elliptic curve coefficient */ CpaFlatBuffer m; /**< digest of the message to be signed */ CpaFlatBuffer r; /**< ECDSA r signature value (r > 0 and r < n) */ CpaFlatBuffer s; /**< ECDSA s signature value (s > 0 and s < n) */ CpaFlatBuffer xp; /**< x coordinate of point P (public key) */ CpaFlatBuffer yp; /**< y coordinate of point P (public key) */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcdsaVerifyOpData; /** ***************************************************************************** * @ingroup cpaCyEcdsa * Cryptographic ECDSA Statistics. * @description * This structure contains statistics on the Cryptographic ECDSA * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyEcdsaStats64 { Cpa64U numEcdsaSignRRequests; /**< Total number of ECDSA Sign R operation requests. */ Cpa64U numEcdsaSignRRequestErrors; /**< Total number of ECDSA Sign R operation requests that had an error and * could not be processed. */ Cpa64U numEcdsaSignRCompleted; /**< Total number of ECDSA Sign R operation requests that completed * successfully. */ Cpa64U numEcdsaSignRCompletedErrors; /**< Total number of ECDSA Sign R operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdsaSignRCompletedOutputInvalid; /**< Total number of ECDSA Sign R operation requests could not be completed * successfully due to an invalid output. * Note that this does not indicate an error. */ Cpa64U numEcdsaSignSRequests; /**< Total number of ECDSA Sign S operation requests. */ Cpa64U numEcdsaSignSRequestErrors; /**< Total number of ECDSA Sign S operation requests that had an error and * could not be processed. */ Cpa64U numEcdsaSignSCompleted; /**< Total number of ECDSA Sign S operation requests that completed * successfully. */ Cpa64U numEcdsaSignSCompletedErrors; /**< Total number of ECDSA Sign S operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdsaSignSCompletedOutputInvalid; /**< Total number of ECDSA Sign S operation requests could not be completed * successfully due to an invalid output. * Note that this does not indicate an error. */ Cpa64U numEcdsaSignRSRequests; /**< Total number of ECDSA Sign R & S operation requests. */ Cpa64U numEcdsaSignRSRequestErrors; /**< Total number of ECDSA Sign R & S operation requests that had an * error and could not be processed. */ Cpa64U numEcdsaSignRSCompleted; /**< Total number of ECDSA Sign R & S operation requests that completed * successfully. */ Cpa64U numEcdsaSignRSCompletedErrors; /**< Total number of ECDSA Sign R & S operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdsaSignRSCompletedOutputInvalid; /**< Total number of ECDSA Sign R & S operation requests could not be * completed successfully due to an invalid output. * Note that this does not indicate an error. */ Cpa64U numEcdsaVerifyRequests; /**< Total number of ECDSA Verification operation requests. */ Cpa64U numEcdsaVerifyRequestErrors; /**< Total number of ECDSA Verification operation requests that had an * error and could not be processed. */ Cpa64U numEcdsaVerifyCompleted; /**< Total number of ECDSA Verification operation requests that completed * successfully. */ Cpa64U numEcdsaVerifyCompletedErrors; /**< Total number of ECDSA Verification operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcdsaVerifyCompletedOutputInvalid; /**< Total number of ECDSA Verification operation requests that resulted * in an invalid output. * Note that this does not indicate an error. */ Cpa64U numKptEcdsaSignRSCompletedOutputInvalid; /**< Total number of KPT ECDSA Sign R & S operation requests could not be * completed successfully due to an invalid output. * Note that this does not indicate an error. */ Cpa64U numKptEcdsaSignRSCompleted; /**< Total number of KPT ECDSA Sign R & S operation requests that completed * successfully. */ Cpa64U numKptEcdsaSignRSRequests; /**< Total number of KPT ECDSA Sign R & S operation requests. */ Cpa64U numKptEcdsaSignRSRequestErrors; /**< Total number of KPT ECDSA Sign R & S operation requests that had an * error and could not be processed. */ Cpa64U numKptEcdsaSignRSCompletedErrors; /**< Total number of KPT ECDSA Sign R & S operation requests that could * not be completed successfully due to errors. */ } CpaCyEcdsaStats64; /** ***************************************************************************** * @ingroup cpaCyEcdsa * Definition of a generic callback function invoked for a number of the * ECDSA Sign API functions. * * @description * This is the prototype for the CpaCyEcdsaGenSignCbFunc 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] multiplyStatus Status of the point multiplication. * @param[in] pOut Output data from the request. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcdsaSignR() * cpaCyEcdsaSignS() * *****************************************************************************/ typedef void (*CpaCyEcdsaGenSignCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean multiplyStatus, CpaFlatBuffer *pOut); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Definition of callback function invoked for cpaCyEcdsaSignRS * requests. * * @description * This is the prototype for the CpaCyEcdsaSignRSCbFunc callback function, * which will provide the ECDSA 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] multiplyStatus Status of the point multiplication. * @param[in] pR Ecdsa message signature r. * @param[in] pS Ecdsa message signature s. * * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcdsaSignRS() * *****************************************************************************/ typedef void (*CpaCyEcdsaSignRSCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean multiplyStatus, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Definition of callback function invoked for cpaCyEcdsaVerify requests. * * @description * This is the prototype for the CpaCyEcdsaVerifyCbFunc 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 status. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcdsaVerify() * *****************************************************************************/ typedef void (*CpaCyEcdsaVerifyCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean verifyStatus); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Generate ECDSA Signature R. * * @description * This function generates ECDSA Signature R 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. * * * @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 is generated in response * to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * None *****************************************************************************/ CpaStatus cpaCyEcdsaSignR(const CpaInstanceHandle instanceHandle, const CpaCyEcdsaGenSignCbFunc pCb, void *pCallbackTag, const CpaCyEcdsaSignROpData *pOpData, CpaBoolean *pSignStatus, CpaFlatBuffer *pR); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Generate ECDSA Signature S. * * @description * This function generates ECDSA Signature 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] pS ECDSA 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 is generated in response * to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * None *****************************************************************************/ CpaStatus cpaCyEcdsaSignS(const CpaInstanceHandle instanceHandle, const CpaCyEcdsaGenSignCbFunc pCb, void *pCallbackTag, const CpaCyEcdsaSignSOpData *pOpData, CpaBoolean *pSignStatus, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Generate ECDSA Signature R & S. * * @description * This function 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. * * @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 is generated in response * to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * None *****************************************************************************/ CpaStatus cpaCyEcdsaSignRS(const CpaInstanceHandle instanceHandle, const CpaCyEcdsaSignRSCbFunc pCb, void *pCallbackTag, const CpaCyEcdsaSignRSOpData *pOpData, CpaBoolean *pSignStatus, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Verify ECDSA Public Key. * * @description * This function performs ECDSA Verify as per ANSI X9.62 2005 section 7.4. * * A response status of ok (verifyStatus == CPA_TRUE) means that the * signature was verified * * @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 In synchronous mode, set to CPA_FALSE if the * point is NOT on the curve or at infinity. Set * to CPA_TRUE if the point is on the curve. * * @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 * CpaCyEcdsaVerifyCbFunc is generated in response to this function * call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcdsaVerifyOpData, * CpaCyEcdsaVerifyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcdsaVerify(const CpaInstanceHandle instanceHandle, const CpaCyEcdsaVerifyCbFunc pCb, void *pCallbackTag, const CpaCyEcdsaVerifyOpData *pOpData, CpaBoolean *pVerifyStatus); /** ***************************************************************************** * @ingroup cpaCyEcdsa * Query statistics for a specific ECDSA instance. * * @description * This function will query a specific instance of the ECDSA implementation * for statistics. The user MUST allocate the CpaCyEcdsaStats64 structure * and pass the reference to that structure into this function call. This * function writes the statistic results into the passed in * CpaCyEcdsaStats64 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] pEcdsaStats 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 * CpaCyEcdsaStats64 *****************************************************************************/ CpaStatus cpaCyEcdsaQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyEcdsaStats64 *pEcdsaStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /*CPA_CY_ECDSA_H_*/ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_ecsm2.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_ecsm2.h index c7c89e3c6e8a..5d5e2b209aa1 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_ecsm2.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_ecsm2.h @@ -1,1464 +1,1431 @@ -/*************************************************************************** - * - * 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_ecsm2.h * * @defgroup cpaCyEcsm2 Elliptic Curve SM2 (ECSM2) API * * @ingroup cpaCy * * @description * These functions specify the API for Public Key Encryption * (Cryptography) SM2 operations. * * Chinese Public Key Algorithm based on Elliptic Curve Theory * * @note * The naming, terms, and reference on SM2 elliptic curve, and their * flow of algorithms inside this API header file are from the link * below, please kindly refer to it for details. * https://tools.ietf.org/html/draft-shen-sm2-ecdsa-02 * *****************************************************************************/ #ifndef CPA_CY_ECSM2_H_ #define CPA_CY_ECSM2_H_ #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" #include "cpa_cy_ec.h" /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Encryption Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2Encrypt * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2Encrypt * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2Encrypt() * *****************************************************************************/ typedef struct _CpaCyEcsm2EncryptOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaFlatBuffer xP; /**< x coordinate of public key */ CpaFlatBuffer yP; /**< y coordinate of public key */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2EncryptOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Decryption Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2Decrypt * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2Decrypt * function, and before it has been returned in the callback, undefined * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2Decrypt * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2Decrypt() * *****************************************************************************/ typedef struct _CpaCyEcsm2DecryptOpData { CpaFlatBuffer d; /**< private key (d > 0 and d < n) */ CpaFlatBuffer x1; /**< x coordinate of [k]G */ CpaFlatBuffer y1; /**< y coordinate of [k]G */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2DecryptOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Point Multiplication Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2PointMultiply * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2PointMultiply * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2PointMultiply() * *****************************************************************************/ typedef struct _CpaCyEcsm2PointMultiplyOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaFlatBuffer x; /**< x coordinate of a point on the curve */ CpaFlatBuffer y; /**< y coordinate of a point on the curve */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2PointMultiplyOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Generator Multiplication Operation Data. * * @description * This structure contains the operation data for the * cpaCyEcsm2GeneratorMultiply 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2GeneratorMultiply * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2GeneratorMultiply() * *****************************************************************************/ typedef struct _CpaCyEcsm2GeneratorMultiplyOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2GeneratorMultiplyOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Point Verify Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2PointVerify * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2PointVerify * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2PointVerify() * *****************************************************************************/ typedef struct _CpaCyEcsm2PointVerifyOpData { CpaFlatBuffer x; /**< x coordinate of a point on the curve */ CpaFlatBuffer y; /**< y coordinate of a point on the curve */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2PointVerifyOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Signature Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2Sign * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2Sign * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2Sign() * *****************************************************************************/ typedef struct _CpaCyEcsm2SignOpData { CpaFlatBuffer k; /**< scalar multiplier (k > 0 and k < n) */ CpaFlatBuffer e; /**< digest of the message */ CpaFlatBuffer d; /**< private key (d > 0 and d < n) */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2SignOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Signature Verify Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2Verify * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2Verify * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2Verify() * *****************************************************************************/ typedef struct _CpaCyEcsm2VerifyOpData { CpaFlatBuffer e; /**< digest of the message */ CpaFlatBuffer r; /**< signature r */ CpaFlatBuffer s; /**< signature s */ CpaFlatBuffer xP; /**< x coordinate of public key */ CpaFlatBuffer yP; /**< y coordinate of public key */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2VerifyOpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Key Exchange Phase 1 Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2KeyExPhase1 * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2KeyExPhase1 * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2KeyExPhase1() * *****************************************************************************/ typedef struct _CpaCyEcsm2KeyExPhase1OpData { CpaFlatBuffer r; /**< scalar multiplier (r > 0 and r < n) */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2KeyExPhase1OpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Key Exchange Phase 2 Operation Data. * * @description * This structure contains the operation data for the cpaCyEcsm2KeyExPhase2 * 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. a.pData[0] = MSB. * * @note * If the client modifies or frees the memory referenced in this * structure after it has been submitted to the cpaCyEcsm2KeyExPhase2 * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyEcsm2KeyExPhase2() * *****************************************************************************/ typedef struct _CpaCyEcsm2KeyExPhase2OpData { CpaFlatBuffer r; /**< scalar multiplier (r > 0 and r < n) */ CpaFlatBuffer d; /**< private key (d > 0 and d < n) */ CpaFlatBuffer x1; /**< x coordinate of a point on the curve from other side */ CpaFlatBuffer x2; /**< x coordinate of a point on the curve from phase 1 */ CpaFlatBuffer y2; /**< y coordinate of a point on the curve from phase 1 */ CpaFlatBuffer xP; /**< x coordinate of public key from other side */ CpaFlatBuffer yP; /**< y coordinate of public key from other side */ CpaCyEcFieldType fieldType; /**< field type for the operation */ } CpaCyEcsm2KeyExPhase2OpData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Encryption Output Data. * * @description * This structure contains the output data of the cpaCyEcsm2Encrypt * function. The client MUST allocate the memory for this structure and the * items pointed to by this structure. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * * @see * cpaCyEcsm2Encrypt() * *****************************************************************************/ typedef struct _CpaCyEcsm2EncryptOutputData { CpaFlatBuffer x1; /**< x coordinate of [k]G */ CpaFlatBuffer y1; /**< y coordinate of [k]G */ CpaFlatBuffer x2; /**< x coordinate of [k]Pb */ CpaFlatBuffer y2; /**< y coordinate of [k]Pb */ } CpaCyEcsm2EncryptOutputData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Decryption Output Data. * * @description * This structure contains the output data of the cpaCyEcsm2Decrypt * function. The client MUST allocate the memory for this structure and the * items pointed to by this structure. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * * @see * cpaCyEcsm2Decrypt() * *****************************************************************************/ typedef struct _CpaCyEcsm2DecryptOutputData { CpaFlatBuffer x2; /**< x coordinate of [k]Pb */ CpaFlatBuffer y2; /**< y coordinate of [k]Pb */ } CpaCyEcsm2DecryptOutputData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * SM2 Key Exchange (Phase 1 & Phase 2) Output Data. * * @description * This structure contains the output data of the key exchange(phase 1 & 2) * function. The client MUST allocate the memory for this structure and the * items pointed to by this structure. * * For optimal performance all data buffers SHOULD be 8-byte aligned. * * @see * cpaCyEcsm2KeyExPhase1(),cpaCyEcsm2KeyExPhase2() * *****************************************************************************/ typedef struct _CpaCyEcsm2KeyExOutputData { CpaFlatBuffer x; /**< x coordinate of a point on the curve */ CpaFlatBuffer y; /**< y coordinate of a point on the curve */ } CpaCyEcsm2KeyExOutputData; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Cryptographic ECSM2 Statistics. * @description * This structure contains statistics on the Cryptographic ECSM2 * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyEcsm2Stats64 { Cpa64U numEcsm2PointMultiplyRequests; /**< Total number of ECSM2 Point Multiplication operation requests. */ Cpa64U numEcsm2PointMultiplyRequestErrors; /**< Total number of ECSM2 Point Multiplication operation requests that * had an error and could not be processed. */ Cpa64U numEcsm2PointMultiplyCompleted; /**< Total number of ECSM2 Point Multiplication operation requests that * completed successfully. */ Cpa64U numEcsm2PointMultiplyCompletedError; /**< Total number of ECSM2 Point Multiplication operation requests that * could not be completed successfully due to errors. */ Cpa64U numEcsm2PointMultiplyCompletedOutputInvalid; /**< Total number of ECSM2 Point Multiplication or Point Verify operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2GeneratorMultiplyRequests; /**< Total number of ECSM2 Generator Multiplication operation requests. */ Cpa64U numEcsm2GeneratorMultiplyRequestErrors; /**< Total number of ECSM2 Generator Multiplication operation requests that * had an error and could not be processed. */ Cpa64U numEcsm2GeneratorMultiplyCompleted; /**< Total number of ECSM2 Generator Multiplication operation requests that * completed successfully. */ Cpa64U numEcsm2GeneratorMultiplyCompletedError; /**< Total number of ECSM2 Generator Multiplication operation requests that * could not be completed successfully due to errors. */ Cpa64U numEcsm2GeneratorMultiplyCompletedOutputInvalid; /**< Total number of ECSM2 Generator Multiplication or Point Verify * operation requests that could not be completed successfully due to an * invalid output. Note that this does not indicate an error. */ Cpa64U numEcsm2PointVerifyRequests; /**< Total number of ECSM2 Point Verify operation requests. */ Cpa64U numEcsm2PointVerifyRequestErrors; /**< Total number of ECSM2 Point Verify operation requests that had * an error and could not be processed. */ Cpa64U numEcsm2PointVerifyCompleted; /**< Total number of ECSM2 Point Verify operation requests that * completed successfully. */ Cpa64U numEcsm2PointVerifyCompletedError; /**< Total number of ECSM2 Point Verify operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcsm2PointVerifyCompletedOutputInvalid; /**< Total number of ECSM2 Point Verify operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2SignRequests; /**< Total number of ECSM2 Sign operation requests. */ Cpa64U numEcsm2SignRequestErrors; /**< Total number of ECSM2 Sign operation requests that had an error * and could not be processed. */ Cpa64U numEcsm2SignCompleted; /**< Total number of ECSM2 Sign operation requests that completed * successfully. */ Cpa64U numEcsm2SignCompletedError; /**< Total number of ECSM2 Sign operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcsm2SignCompletedOutputInvalid; /**< Total number of ECSM2 Sign operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2VerifyRequests; /**< Total number of ECSM2 Verify operation requests. */ Cpa64U numEcsm2VerifyRequestErrors; /**< Total number of ECSM2 Verify operation requests that had an error * and could not be processed. */ Cpa64U numEcsm2VerifyCompleted; /**< Total number of ECSM2 Verify operation requests that completed * successfully. */ Cpa64U numEcsm2VerifyCompletedError; /**< Total number of ECSM2 Verify operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcsm2VerifyCompletedOutputInvalid; /**< Total number of ECSM2 Verify operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2EncryptRequests; /**< Total number of ECSM2 Encryption requests. */ Cpa64U numEcsm2EncryptRequestErrors; /**< Total number of ECSM2 Point Encryption requests that had * an error and could not be processed. */ Cpa64U numEcsm2EncryptCompleted; /**< Total number of ECSM2 Encryption operation requests that * completed successfully. */ Cpa64U numEcsm2EncryptCompletedError; /**< Total number of ECSM2 Encryption operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcsm2EncryptCompletedOutputInvalid; /**< Total number of ECSM2 Encryption operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2DecryptRequests; /**< Total number of ECSM2 Decryption operation requests. */ Cpa64U numEcsm2DecryptRequestErrors; /**< Total number of ECSM2 Point Decryption requests that had * an error and could not be processed. */ Cpa64U numEcsm2DecryptCompleted; /**< Total number of ECSM2 Decryption operation requests that * completed successfully. */ Cpa64U numEcsm2DecryptCompletedError; /**< Total number of ECSM2 Decryption operation requests that could * not be completed successfully due to errors. */ Cpa64U numEcsm2DecryptCompletedOutputInvalid; /**< Total number of ECSM2 Decryption operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2KeyExPhase1Requests; /**< Total number of ECSM2 Key Exchange Phase1 operation requests. */ Cpa64U numEcsm2KeyExPhase1RequestErrors; /**< Total number of ECSM2 Key Exchange Phase1 operation requests that * had an error and could not be processed. */ Cpa64U numEcsm2KeyExPhase1Completed; /**< Total number of ECSM2 Key Exchange Phase1 operation requests that * completed successfully. */ Cpa64U numEcsm2KeyExPhase1CompletedError; /**< Total number of ECSM2 Key Exchange Phase1 operation requests that * could not be completed successfully due to errors. */ Cpa64U numEcsm2KeyExPhase1CompletedOutputInvalid; /**< Total number of ECSM2 Key Exchange Phase1 operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ Cpa64U numEcsm2KeyExPhase2Requests; /**< Total number of ECSM2 Key Exchange Phase2 operation requests. */ Cpa64U numEcsm2KeyExPhase2RequestErrors; /**< Total number of ECSM2 Key Exchange Phase2 operation requests that * had an error and could not be processed. */ Cpa64U numEcsm2KeyExPhase2Completed; /**< Total number of ECSM2 Key Exchange Phase2 operation requests that * completed successfully. */ Cpa64U numEcsm2KeyExPhase2CompletedError; /**< Total number of ECSM2 Key Exchange Phase2 operation requests that * could not be completed successfully due to errors. */ Cpa64U numEcsm2KeyExPhase2CompletedOutputInvalid; /**< Total number of ECSM2 Key Exchange Phase2 operation * requests that could not be completed successfully due to an invalid * output. Note that this does not indicate an error. */ } CpaCyEcsm2Stats64; /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Definition of callback function invoked for cpaCyEcsm2Sign * requests. * * @description * This is the callback function for: * cpaCyEcsm2Sign * * @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 and CPA_STATUS_FAIL. * @param[in] pOpData A pointer to Operation data supplied in * request. * @param[in] pass Indicate whether pOut is valid or not. * CPA_TRUE == pass, pOut is valid * CPA_FALSE == pass, pOut is invalid * @param[in] pR Ecsm2 message signature r. * @param[in] pS Ecsm2 message signature s. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcsm2GeneratorMultiply() * *****************************************************************************/ typedef void (*CpaCyEcsm2SignCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean pass, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Definition of callback function invoked for cpaCyEcsm2Verify requests. * * @description * This is the prototype for the CpaCyEcsm2VerifyCbFunc 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 and CPA_STATUS_FAIL. * @param[in] pOpData Operation data pointer supplied in request. * @param[in] verifyStatus The verification status. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyEcsm2Verify() * *****************************************************************************/ typedef void (*CpaCyEcsm2VerifyCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean verifyStatus); /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Perform SM2 Point Multiplication. * * @description * This function performs SM2 Point Multiplication, multiply * a point (P) by k (scalar) ([k]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] pMultiplyStatus Multiply status * CPA_TRUE == pOutputData is valid * CPA_FALSE == pOutputData is invalid * @param[out] pXk x coordinate of the resulting point * multiplication * @param[out] pYk y coordinate of the resulting point * multiplication * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcsm2PointMultiplyCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2PointMultiplyOpData, * CpaCyEcPointMultiplyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2PointMultiply(const CpaInstanceHandle instanceHandle, const CpaCyEcPointMultiplyCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2PointMultiplyOpData *pOpData, CpaBoolean *pMultiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Perform SM2 Generator Multiplication. * * @description * This function performs SM2 Generator Multiplication, multiply the * generator point (G) by k (scalar) ([k]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] pMultiplyStatus Multiply status * CPA_TRUE == pOutputData is valid * CPA_FALSE == pOutputData is invalid * @param[out] pXk x coordinate of the resulting point * multiplication * @param[out] pYk y coordinate of the resulting point * multiplication * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcPointMultiplyCbFunc is generated in response to this function * call. For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2GeneratorMultiplyOpData, * CpaCyEcPointMultiplyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2GeneratorMultiply(const CpaInstanceHandle instanceHandle, const CpaCyEcPointMultiplyCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2GeneratorMultiplyOpData *pOpData, CpaBoolean *pMultiplyStatus, CpaFlatBuffer *pXk, CpaFlatBuffer *pYk); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Point Verify. * * @description * This function performs SM2 Point Verify, to check if the input point * on the curve or not. * * @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 Verification status * CPA_TRUE == verify pass * CPA_FALSE == verify fail * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcsm2VerifyCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2PointVerifyOpData, * CpaCyEcPointVerifyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2PointVerify(const CpaInstanceHandle instanceHandle, const CpaCyEcPointVerifyCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2PointVerifyOpData *pOpData, CpaBoolean *pVerifyStatus); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Signature (Step A4 to A7). * * @description * This function implements step A4 to A7 (in Section 5.2 in "Generation * of Signature" Part 1). * * @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 Signature status * CPA_TRUE = pOutputData is valid * CPA_FALSE = pOutputData is invalid * @param[out] pR R output of the resulting signature operation * @param[out] pS S output of the resulting signature operation * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcsm2SignCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2SignOpData, * CpaCyEcsm2SignCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2Sign(const CpaInstanceHandle instanceHandle, const CpaCyEcsm2SignCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2SignOpData *pOpData, CpaBoolean *pSignStatus, CpaFlatBuffer *pR, CpaFlatBuffer *pS); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Signature Verify (Step B5 to B7). * * @description * This function implements step B5 to B7 (in Section 5.3 in "Verification * of Signature" Part 1). * * @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 Status of the signature verification * CPA_TRUE == verify pass * CPA_FALSE == verify fail * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyEcsm2VerifyCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2VerifyOpData, * CpaCyEcsm2VerifyCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2Verify(const CpaInstanceHandle instanceHandle, const CpaCyEcsm2VerifyCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2VerifyOpData *pOpData, CpaBoolean *pVerifyStatus); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Encryption (Step A2 to A4). * * @description * This function implements step A2 to A4 (in Section 7.2 in * "Algorithm for Encryption and the Flow Chart" Part 1). * * @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] pOutputData Ecrypted message * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2EncryptOpData, * CpaCyEcsm2EncryptOutputData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2Encrypt(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2EncryptOpData *pOpData, CpaCyEcsm2EncryptOutputData *pOutputData); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Decryption (Step B1 to B3). * * @description * This function implements step B1 to B3 (in Section 7.3 in "Algorithm * for Decryption and the Flow Chart" Part 1). * * @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] pOutputData Decrypted message * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2DecryptOpData, * CpaCyEcsm2DecryptOutputData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2Decrypt(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2DecryptOpData *pOpData, CpaCyEcsm2DecryptOutputData *pOutputData); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Key Exchange Phase 1 (Step A2/B2). * * @description * This function implements step A2 (User A) or B2 (User B) * (in Section 6.2 in "Key Exchange Protocol and the Flow Chart" Part 1). * * @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] pOutputData Output of key exchange phase 1 ([r]G) * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2KeyExPhase1OpData, * CpaCyEcsm2KeyExOutputData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2KeyExPhase1(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2KeyExPhase1OpData *pOpData, CpaCyEcsm2KeyExOutputData *pOutputData); /** ***************************************************************************** * @file cpa_cy_ec.h * @ingroup cpaCyEcsm2 * Perform SM2 Key Exchange Phase 2 (Step A4 to A7, B3 to B6). * * @description * This function implements steps A4 to A7(User A) or B3 to B6(User B) * (in Section 6.2 in "Key Exchange Protocol and the Flow Chart" Part 1). * * @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] pOutputData Output of key exchange phase2. * * @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 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 * When pCb is non-NULL an asynchronous callback of type * CpaCyGenFlatBufCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyEcsm2KeyExPhase2OpData, * CpaCyEcsm2KeyExOutputData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyEcsm2KeyExPhase2(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pCb, void *pCallbackTag, const CpaCyEcsm2KeyExPhase2OpData *pOpData, CpaCyEcsm2KeyExOutputData *pOutputData); /** ***************************************************************************** * @file cpa_cy_ecsm2.h * @ingroup cpaCyEcsm2 * Query statistics for a specific ECSM2 instance. * * @description * This function will query a specific instance of the ECSM2 implementation * for statistics. The user MUST allocate the CpaCyEcsm2Stats64 structure * and pass the reference to that structure into this function call. This * function writes the statistic results into the passed in * CpaCyEcsm2Stats64 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] pEcsm2Stats 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 * CpaCyEcsm2Stats64 *****************************************************************************/ CpaStatus cpaCyEcsm2QueryStats64(const CpaInstanceHandle instanceHandle_in, CpaCyEcsm2Stats64 *pEcsm2Stats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /*CPA_CY_ECSM2_H_*/ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_im.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_im.h index f70e43fcf047..a9410523367f 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_im.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_im.h @@ -1,342 +1,309 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_im.h * * @defgroup cpaCyInstMaint Cryptographic Instance Management API * * @ingroup cpaCy * * @description * These functions specify the Instance Management API for available * Cryptographic Instances. It is expected that these functions will only be * called via a single system maintenance entity, rather than individual * clients. * *****************************************************************************/ #ifndef CPA_CY_IM_H_ #define CPA_CY_IM_H_ #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyInstMaint * Cryptographic Component Initialization and Start function. * * @description * This function will initialize and start the Cryptographic component. * It MUST be called before any other crypto function is called. This * function SHOULD be called only once (either for the very first time, * or after an cpaCyStopInstance call which succeeded) per instance. * Subsequent calls will have no effect. * * @context * This function may sleep, and MUST NOT be called in interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * @param[out] instanceHandle Handle to an instance of this API to be * initialized. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Suggested course of action * is to shutdown and restart. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * None. * @post * None * @note * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * cpaCyStopInstance() * *****************************************************************************/ CpaStatus cpaCyStartInstance(CpaInstanceHandle instanceHandle); /** ***************************************************************************** * @ingroup cpaCyInstMaint * Cryptographic Component Stop function. * * @description * This function will stop the Cryptographic component and free * all system resources associated with it. The client MUST ensure that * all outstanding operations have completed before calling this function. * The recommended approach to ensure this is to deregister all session or * callback handles before calling this function. If outstanding * operations still exist when this function is invoked, the callback * function for each of those operations will NOT be invoked and the * shutdown will continue. If the component is to be restarted, then a * call to cpaCyStartInstance is required. * * @context * This function may sleep, and so MUST NOT be called in interrupt * context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * @param[in] instanceHandle Handle to an instance of this API to be * shutdown. * * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. Suggested course of action * is to ensure requests are not still being * submitted and that all sessions are * deregistered. If this does not help, then * forcefully remove the component from the * system. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaCyStartInstance. * @post * None * @note * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * cpaCyStartInstance() * *****************************************************************************/ CpaStatus cpaCyStopInstance(CpaInstanceHandle instanceHandle); /** ***************************************************************************** * @ingroup cpaCyInstMaint * Cryptographic Capabilities Info * * @description * This structure contains the capabilities that vary across API * implementations. This structure is used in conjunction with * @ref cpaCyQueryCapabilities() to determine the capabilities supported * by a particular API implementation. * * The client MUST allocate memory for this structure and any members * that require memory. 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 the function returns. *****************************************************************************/ typedef struct _CpaCyCapabilitiesInfo { CpaBoolean symSupported; /**< CPA_TRUE if instance supports the symmetric cryptography API. * See @ref cpaCySym. */ CpaBoolean symDpSupported; /**< CPA_TRUE if instance supports the symmetric cryptography * data plane API. * See @ref cpaCySymDp. */ CpaBoolean dhSupported; /**< CPA_TRUE if instance supports the Diffie Hellman API. * See @ref cpaCyDh. */ CpaBoolean dsaSupported; /**< CPA_TRUE if instance supports the DSA API. * See @ref cpaCyDsa. */ CpaBoolean rsaSupported; /**< CPA_TRUE if instance supports the RSA API. * See @ref cpaCyRsa. */ CpaBoolean ecSupported; /**< CPA_TRUE if instance supports the Elliptic Curve API. * See @ref cpaCyEc. */ CpaBoolean ecdhSupported; /**< CPA_TRUE if instance supports the Elliptic Curve Diffie Hellman API. * See @ref cpaCyEcdh. */ CpaBoolean ecdsaSupported; /**< CPA_TRUE if instance supports the Elliptic Curve DSA API. * See @ref cpaCyEcdsa. */ CpaBoolean keySupported; /**< CPA_TRUE if instance supports the Key Generation API. * See @ref cpaCyKeyGen. */ CpaBoolean lnSupported; /**< CPA_TRUE if instance supports the Large Number API. * See @ref cpaCyLn. */ CpaBoolean primeSupported; /**< CPA_TRUE if instance supports the prime number testing API. * See @ref cpaCyPrime. */ CpaBoolean drbgSupported; /**< CPA_TRUE if instance supports the DRBG API. * See @ref cpaCyDrbg. */ CpaBoolean nrbgSupported; /**< CPA_TRUE if instance supports the NRBG API. * See @ref cpaCyNrbg. */ CpaBoolean randSupported; /**< CPA_TRUE if instance supports the random bit/number generation API. * See @ref cpaCyRand. */ CpaBoolean kptSupported; /**< CPA_TRUE if instance supports the Intel(R) KPT Cryptographic API. * See @ref cpaCyKpt. */ CpaBoolean hkdfSupported; /**< CPA_TRUE if instance supports the HKDF components of the KeyGen API. * See @ref cpaCyKeyGen. */ CpaBoolean extAlgchainSupported; /**< CPA_TRUE if instance supports algorithm chaining for certain * wireless algorithms. Please refer to implementation for details. * See @ref cpaCySym. */ CpaBoolean ecEdMontSupported; /**< CPA_TRUE if instance supports the Edwards and Montgomery elliptic * curves of the EC API. * See @ref cpaCyEc */ CpaBoolean ecSm2Supported; /**< CPA_TRUE if instance supports the EcSM2 API. * See @ref cpaCyEcsm2. */ } CpaCyCapabilitiesInfo; /** ***************************************************************************** * @ingroup cpaCyInstMaint * Returns capabilities of a Cryptographic API instance * * @description * This function is used to query the instance capabilities. * * @context * The function shall not be called in an interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[out] pCapInfo Pointer to capabilities info structure. * All fields in the structure * are populated by the API instance. * * @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_UNSUPPORTED Function is not supported. * * @pre * The instance has been initialized via the @ref cpaCyStartInstance * function. * @post * None *****************************************************************************/ CpaStatus cpaCyQueryCapabilities(const CpaInstanceHandle instanceHandle, CpaCyCapabilitiesInfo * pCapInfo); /** ***************************************************************************** * @ingroup cpaCyInstMaint * Sets the address translation function * * @description * This function is used to set the virtual to physical address * translation routine for the instance. The specified routine * is used by the instance to perform any required translation of * a virtual address to a physical address. If the application * does not invoke this function, then the instance will use its * default method, such as virt2phys, for address translation. * @context * The function shall not be called in an interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[in] virtual2Physical Routine that performs virtual to * physical address translation. * * @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_UNSUPPORTED Function is not supported. * * @pre * None * @post * None * @see * None * *****************************************************************************/ CpaStatus cpaCySetAddressTranslation(const CpaInstanceHandle instanceHandle, CpaVirtualToPhysical virtual2Physical); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /*CPA_CY_IM_H_*/ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_key.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_key.h index a0eaf35ec760..c51d57fd8ca6 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_key.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_key.h @@ -1,1204 +1,1171 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_key.h * * @defgroup cpaCyKeyGen Cryptographic Key and Mask Generation API * * @ingroup cpaCy * * @description * These functions specify the API for key and mask generation * operations. * *****************************************************************************/ #ifndef CPA_CY_KEY_H #define CPA_CY_KEY_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" #include "cpa_cy_sym.h" /* needed for hash algorithm, for MGF */ /** ***************************************************************************** * @ingroup cpaCyKeyGen * SSL or TLS key generation random number length. * * @description * Defines the permitted SSL or TLS random number length in bytes that * may be used with the functions @ref cpaCyKeyGenSsl and @ref * cpaCyKeyGenTls. This is the length of the client or server random * number values. *****************************************************************************/ #define CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES (32) /** ***************************************************************************** * @ingroup cpaCyKeyGen * SSL Operation Types * @description * Enumeration of the different SSL operations that can be specified in * the struct @ref CpaCyKeyGenSslOpData. It identifies the label. *****************************************************************************/ typedef enum _CpaCyKeySslOp { CPA_CY_KEY_SSL_OP_MASTER_SECRET_DERIVE = 1, /**< Derive the master secret */ CPA_CY_KEY_SSL_OP_KEY_MATERIAL_DERIVE, /**< Derive the key material */ CPA_CY_KEY_SSL_OP_USER_DEFINED /**< User Defined Operation for custom labels*/ } CpaCyKeySslOp; /** ***************************************************************************** * @ingroup cpaCyKeyGen * SSL data for key generation functions * @description * This structure contains data for use in key generation operations for * SSL. For specific SSL key generation operations, the structure fields * MUST be set as follows: * * @par SSL Master-Secret Derivation: *
sslOp = CPA_CY_KEY_SSL_OP_MASTER_SECRET_DERIVE *
secret = pre-master secret key *
seed = client_random + server_random *
userLabel = NULL * * @par SSL Key-Material Derivation: *
sslOp = CPA_CY_KEY_SSL_OP_KEY_MATERIAL_DERIVE *
secret = master secret key *
seed = server_random + client_random *
userLabel = NULL * *
Note that the client/server random order is reversed from that * used for master-secret derivation. * * @note Each of the client and server random numbers need to be of * length CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES. * * @note In each of the above descriptions, + indicates concatenation. * * @note The label used is predetermined by the SSL operation in line * with the SSL 3.0 specification, and can be overridden by using * a user defined operation CPA_CY_KEY_SSL_OP_USER_DEFINED and * associated userLabel. * ****************************************************************************/ typedef struct _CpaCyKeyGenSslOpData { CpaCyKeySslOp sslOp; /**< Indicate the SSL operation to be performed */ CpaFlatBuffer secret; /**< Flat buffer containing a pointer to either the master or pre-master * secret key. The length field indicates the length of the secret key in * bytes. Implementation-specific limits may apply to this length. */ CpaFlatBuffer seed; /**< Flat buffer containing a pointer to the seed data. * Implementation-specific limits may apply to this length. */ CpaFlatBuffer info; /**< Flat buffer containing a pointer to the info data. * Implementation-specific limits may apply to this length. */ Cpa32U generatedKeyLenInBytes; /**< The requested length of the generated key in bytes. * Implementation-specific limits may apply to this length. */ CpaFlatBuffer userLabel; /**< Optional flat buffer containing a pointer to a user defined label. * The length field indicates the length of the label in bytes. To use this * field, the sslOp must be CPA_CY_KEY_SSL_OP_USER_DEFINED, * or otherwise it is ignored and can be set to NULL. * Implementation-specific limits may apply to this length. */ } CpaCyKeyGenSslOpData; /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS Operation Types * @description * Enumeration of the different TLS operations that can be specified in * the CpaCyKeyGenTlsOpData. It identifies the label. * * The functions @ref cpaCyKeyGenTls and @ref cpaCyKeyGenTls2 * accelerate the TLS PRF, which is defined as part of RFC2246 (TLS * v1.0), RFC4346 (TLS v1.1), and RFC5246 (TLS v1.2). * One of the inputs to each of these functions is a label. * This enumerated type defines values that correspond to some of * the required labels. * However, for some of the operations/labels required by these RFCs, * no values are specified. * * In such cases, a user-defined value must be provided. The client * should use the enum value @ref CPA_CY_KEY_TLS_OP_USER_DEFINED, and * pass the label using the userLabel field of the @ref * CpaCyKeyGenTlsOpData data structure. * *****************************************************************************/ typedef enum _CpaCyKeyTlsOp { CPA_CY_KEY_TLS_OP_MASTER_SECRET_DERIVE = 1, /**< Derive the master secret using the TLS PRF. * Corresponds to RFC2246/5246 section 8.1, operation "Computing the * master secret", label "master secret". */ CPA_CY_KEY_TLS_OP_KEY_MATERIAL_DERIVE, /**< Derive the key material using the TLS PRF. * Corresponds to RFC2246/5246 section 6.3, operation "Derive the key * material", label "key expansion". */ CPA_CY_KEY_TLS_OP_CLIENT_FINISHED_DERIVE, /**< Derive the client finished tag using the TLS PRF. * Corresponds to RFC2246/5246 section 7.4.9, operation "Client finished", * label "client finished". */ CPA_CY_KEY_TLS_OP_SERVER_FINISHED_DERIVE, /**< Derive the server finished tag using the TLS PRF. * Corresponds to RFC2246/5246 section 7.4.9, operation "Server finished", * label "server finished". */ CPA_CY_KEY_TLS_OP_USER_DEFINED /**< User Defined Operation for custom labels. */ } CpaCyKeyTlsOp; /** ***************************************************************************** * @file cpa_cy_key.h * @ingroup cpaCyKeyGen * TLS Operation Types * @description * Enumeration of the different TLS operations that can be specified in * the CpaCyKeyGenHKDFOpData. * * The function @ref cpaCyKeyGenTls3 * accelerates the TLS HKDF, which is defined as part of RFC5869 (HKDF) * and RFC8446 (TLS v1.3). * * This enumerated type defines the support HKDF operations for * extraction and expansion of keying material. * *****************************************************************************/ typedef enum _CpaCyKeyHKDFOp { CPA_CY_HKDF_KEY_EXTRACT = 12, /**< HKDF Extract operation * Corresponds to RFC5869 section 2.2, step 1 "Extract" */ CPA_CY_HKDF_KEY_EXPAND, /**< HKDF Expand operation * Corresponds to RFC5869 section 2.3, step 2 "Expand" */ CPA_CY_HKDF_KEY_EXTRACT_EXPAND, /**< HKDF operation * This performs HKDF_EXTRACT and HKDF_EXPAND in a single * API invocation. */ CPA_CY_HKDF_KEY_EXPAND_LABEL , /**< HKDF Expand label operation for TLS 1.3 * Corresponds to RFC8446 section 7.1 Key Schedule definition for * HKDF-Expand-Label, which refers to HKDF-Expand defined in RFC5869. */ CPA_CY_HKDF_KEY_EXTRACT_EXPAND_LABEL /**< HKDF Extract plus Expand label operation for TLS 1.3 * Corresponds to RFC5869 section 2.2, step 1 "Extract" followed by * RFC8446 section 7.1 Key Schedule definition for * HKDF-Expand-Label, which refers to HKDF-Expand defined in RFC5869. */ } CpaCyKeyHKDFOp; /** ***************************************************************************** * @file cpa_cy_key.h * @ingroup cpaCyKeyGen * TLS Operation Types * @description * Enumeration of the different cipher suites that may be used in a TLS * v1.3 operation. This value is used to infer the sizes of the key * and iv sublabel. * * The function @ref cpaCyKeyGenTls3 * accelerates the TLS HKDF, which is defined as part of RFC5869 (HKDF) * and RFC8446 (TLS v1.3). * * This enumerated type defines the supported cipher suites in the * TLS operation that require HKDF key operations. * *****************************************************************************/ typedef enum _CpaCyKeyHKDFCipherSuite { CPA_CY_HKDF_TLS_AES_128_GCM_SHA256 = 1, CPA_CY_HKDF_TLS_AES_256_GCM_SHA384, CPA_CY_HKDF_TLS_CHACHA20_POLY1305_SHA256 , CPA_CY_HKDF_TLS_AES_128_CCM_SHA256, CPA_CY_HKDF_TLS_AES_128_CCM_8_SHA256 } CpaCyKeyHKDFCipherSuite; /** ***************************************************************************** * @file cpa_cy_key.h * @ingroup cpaCyKeyGen * TLS Operation Types * @description * Bitwise constants for HKDF sublabels * * These definitions provide bit settings for sublabels for * HKDF-ExpandLabel operations. * *
key sublabel to generate "key" keying material *
iv sublabel to generate "iv" keying material *
resumption sublabel to generate "resumption" keying material *
finished sublabel to generate "finished" keying material * *****************************************************************************/ #define CPA_CY_HKDF_SUBLABEL_KEY ((Cpa16U)0x0001) /**< Bit for creation of key material for 'key' sublabel */ #define CPA_CY_HKDF_SUBLABEL_IV ((Cpa16U)0x0002) /**< Bit for creation of key material for 'iv' sublabel */ #define CPA_CY_HKDF_SUBLABEL_RESUMPTION ((Cpa16U)0x0004) /**< Bit for creation of key material for 'resumption' sublabel */ #define CPA_CY_HKDF_SUBLABEL_FINISHED ((Cpa16U)0x0008) /**< Bit for creation of key material for 'finished' sublabel */ #define CPA_CY_HKDF_KEY_MAX_SECRET_SZ ((Cpa8U)80) /** space in bytes PSK or (EC)DH */ #define CPA_CY_HKDF_KEY_MAX_HMAC_SZ ((Cpa8U)48) /** space in bytes of CPA_CY_SYM_HASH_SHA384 result */ #define CPA_CY_HKDF_KEY_MAX_INFO_SZ ((Cpa8U)80) /** space in bytes of largest info needed for TLS 1.3, * rounded up to multiple of 8 */ #define CPA_CY_HKDF_KEY_MAX_LABEL_SZ ((Cpa8U)78) /** space in bytes of largest label for TLS 1.3 */ #define CPA_CY_HKDF_KEY_MAX_LABEL_COUNT ((Cpa8U)4) /** Maximum number of labels in op structure */ /** ***************************************************************************** * @file cpa_cy_key.h * @ingroup cpaCyKeyGen * TLS data for key generation functions * @description * This structure contains data for describing label for the * HKDF Extract Label function * * @par Extract Label Function *
labelLen = length of the label field *
contextLen = length of the context field *
sublabelFlag = Mask of sub labels required for this label. *
label = label as defined in RFC8446 *
context = context as defined in RFC8446 * ****************************************************************************/ typedef struct _CpaCyKeyGenHKDFExpandLabel { Cpa8U label[CPA_CY_HKDF_KEY_MAX_LABEL_SZ]; /**< HKDFLabel field as defined in RFC8446 sec 7.1. */ Cpa8U labelLen; /**< The length, in bytes of the label */ Cpa8U sublabelFlag; /**< mask of sublabels to be generated. * This flag is composed of zero or more of: * CPA_CY_HKDF_SUBLABEL_KEY * CPA_CY_HKDF_SUBLABEL_IV * CPA_CY_HKDF_SUBLABEL_RESUMPTION * CPA_CY_HKDF_SUBLABEL_FINISHED */ } CpaCyKeyGenHKDFExpandLabel; /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS data for key generation functions * @description * This structure contains data for all HKDF operations: *
HKDF Extract *
HKDF Expand *
HKDF Expand Label *
HKDF Extract and Expand *
HKDF Extract and Expand Label * * @par HKDF Map Structure Elements *
secret - IKM value for extract operations or PRK for expand * or expand operations. *
seed - contains the salt for extract * operations *
info - contains the info data for extract operations *
labels - See notes above * ****************************************************************************/ typedef struct _CpaCyKeyGenHKDFOpData { CpaCyKeyHKDFOp hkdfKeyOp; /**< Keying operation to be performed. */ Cpa8U secretLen; /**< Length of secret field */ Cpa16U seedLen; /**< Length of seed field */ Cpa16U infoLen; /**< Length of info field */ Cpa16U numLabels; /**< Number of filled CpaCyKeyGenHKDFExpandLabel elements */ Cpa8U secret[CPA_CY_HKDF_KEY_MAX_SECRET_SZ]; /**< Input Key Material or PRK */ Cpa8U seed[CPA_CY_HKDF_KEY_MAX_HMAC_SZ]; /**< Input salt */ Cpa8U info[CPA_CY_HKDF_KEY_MAX_INFO_SZ]; /**< info field */ CpaCyKeyGenHKDFExpandLabel label[CPA_CY_HKDF_KEY_MAX_LABEL_COUNT]; /**< array of Expand Label structures */ } CpaCyKeyGenHKDFOpData; /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS data for key generation functions * @description * This structure contains data for use in key generation operations for * TLS. For specific TLS key generation operations, the structure fields * MUST be set as follows: * * @par TLS Master-Secret Derivation: *
tlsOp = CPA_CY_KEY_TLS_OP_MASTER_SECRET_DERIVE *
secret = pre-master secret key *
seed = client_random + server_random *
userLabel = NULL * * @par TLS Key-Material Derivation: *
tlsOp = CPA_CY_KEY_TLS_OP_KEY_MATERIAL_DERIVE *
secret = master secret key *
seed = server_random + client_random *
userLabel = NULL * *
Note that the client/server random order is reversed from * that used for Master-Secret Derivation. * * @par TLS Client finished/Server finished tag Derivation: *
tlsOp = CPA_CY_KEY_TLS_OP_CLIENT_FINISHED_DERIVE (client) *
or CPA_CY_KEY_TLS_OP_SERVER_FINISHED_DERIVE (server) *
secret = master secret key *
seed = MD5(handshake_messages) + SHA-1(handshake_messages) *
userLabel = NULL * * @note Each of the client and server random seeds need to be of * length CPA_CY_KEY_GEN_SSL_TLS_RANDOM_LEN_IN_BYTES. * @note In each of the above descriptions, + indicates concatenation. * @note The label used is predetermined by the TLS operation in line * with the TLS specifications, and can be overridden by using * a user defined operation CPA_CY_KEY_TLS_OP_USER_DEFINED * and associated userLabel. * ****************************************************************************/ typedef struct _CpaCyKeyGenTlsOpData { CpaCyKeyTlsOp tlsOp; /**< TLS operation to be performed */ CpaFlatBuffer secret; /**< Flat buffer containing a pointer to either the master or pre-master * secret key. The length field indicates the length of the secret in * bytes. */ CpaFlatBuffer seed; /**< Flat buffer containing a pointer to the seed data. * Implementation-specific limits may apply to this length. */ Cpa32U generatedKeyLenInBytes; /**< The requested length of the generated key in bytes. * Implementation-specific limits may apply to this length. */ CpaFlatBuffer userLabel; /**< Optional flat buffer containing a pointer to a user defined label. * The length field indicates the length of the label in bytes. To use this * field, the tlsOp must be CPA_CY_KEY_TLS_OP_USER_DEFINED. * Implementation-specific limits may apply to this length. */ } CpaCyKeyGenTlsOpData; /** ***************************************************************************** * @ingroup cpaCyKeyGen * Key Generation Mask Generation Function (MGF) Data * @description * This structure contains data relating to Mask Generation Function * key generation operations. * * @note The default hash algorithm used by the MGF is SHA-1. If a * different hash algorithm is preferred, then see the extended * version of this structure, @ref CpaCyKeyGenMgfOpDataExt. * @see * cpaCyKeyGenMgf ****************************************************************************/ typedef struct _CpaCyKeyGenMgfOpData { CpaFlatBuffer seedBuffer; /**< Caller MUST allocate a buffer and populate with the input seed * data. For optimal performance the start of the seed SHOULD be allocated * on an 8-byte boundary. The length field represents the seed length in * bytes. Implementation-specific limits may apply to this length. */ Cpa32U maskLenInBytes; /**< The requested length of the generated mask in bytes. * Implementation-specific limits may apply to this length. */ } CpaCyKeyGenMgfOpData; /** ***************************************************************************** * @ingroup cpaCyKeyGen * Extension to the original Key Generation Mask Generation Function * (MGF) Data * @description * This structure is an extension to the original MGF data structure. * The extension allows the hash function to be specified. * @note * This structure is separate from the base @ref CpaCyKeyGenMgfOpData * structure in order to retain backwards compatibility with the * original version of the API. * @see * cpaCyKeyGenMgfExt ****************************************************************************/ typedef struct _CpaCyKeyGenMgfOpDataExt { CpaCyKeyGenMgfOpData baseOpData; /**< "Base" operational data for MGF generation */ CpaCySymHashAlgorithm hashAlgorithm; /**< Specifies the hash algorithm to be used by the Mask Generation * Function */ } CpaCyKeyGenMgfOpDataExt; /** ***************************************************************************** * @ingroup cpaCyKeyGen * Key Generation Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyKeyGenStats64. * @description * This structure contains statistics on the key and mask generation * operations. Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyKeyGenStats { Cpa32U numSslKeyGenRequests; /**< Total number of successful SSL key generation requests. */ Cpa32U numSslKeyGenRequestErrors; /**< Total number of SSL key generation requests that had an error and * could not be processed. */ Cpa32U numSslKeyGenCompleted; /**< Total number of SSL key generation operations that completed * successfully. */ Cpa32U numSslKeyGenCompletedErrors; /**< Total number of SSL key generation operations that could not be * completed successfully due to errors. */ Cpa32U numTlsKeyGenRequests; /**< Total number of successful TLS key generation requests. */ Cpa32U numTlsKeyGenRequestErrors; /**< Total number of TLS key generation requests that had an error and * could not be processed. */ Cpa32U numTlsKeyGenCompleted; /**< Total number of TLS key generation operations that completed * successfully. */ Cpa32U numTlsKeyGenCompletedErrors; /**< Total number of TLS key generation operations that could not be * completed successfully due to errors. */ Cpa32U numMgfKeyGenRequests; /**< Total number of successful MGF key generation requests (including * "extended" MGF requests). */ Cpa32U numMgfKeyGenRequestErrors; /**< Total number of MGF key generation requests that had an error and * could not be processed. */ Cpa32U numMgfKeyGenCompleted; /**< Total number of MGF key generation operations that completed * successfully. */ Cpa32U numMgfKeyGenCompletedErrors; /**< Total number of MGF key generation operations that could not be * completed successfully due to errors. */ } CpaCyKeyGenStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyKeyGen * Key Generation Statistics (64-bit version). * @description * This structure contains the 64-bit version of the statistics * on the key and mask generation operations. * Statistics are set to zero when the component is * initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyKeyGenStats64 { Cpa64U numSslKeyGenRequests; /**< Total number of successful SSL key generation requests. */ Cpa64U numSslKeyGenRequestErrors; /**< Total number of SSL key generation requests that had an error and * could not be processed. */ Cpa64U numSslKeyGenCompleted; /**< Total number of SSL key generation operations that completed * successfully. */ Cpa64U numSslKeyGenCompletedErrors; /**< Total number of SSL key generation operations that could not be * completed successfully due to errors. */ Cpa64U numTlsKeyGenRequests; /**< Total number of successful TLS key generation requests. */ Cpa64U numTlsKeyGenRequestErrors; /**< Total number of TLS key generation requests that had an error and * could not be processed. */ Cpa64U numTlsKeyGenCompleted; /**< Total number of TLS key generation operations that completed * successfully. */ Cpa64U numTlsKeyGenCompletedErrors; /**< Total number of TLS key generation operations that could not be * completed successfully due to errors. */ Cpa64U numMgfKeyGenRequests; /**< Total number of successful MGF key generation requests (including * "extended" MGF requests). */ Cpa64U numMgfKeyGenRequestErrors; /**< Total number of MGF key generation requests that had an error and * could not be processed. */ Cpa64U numMgfKeyGenCompleted; /**< Total number of MGF key generation operations that completed * successfully. */ Cpa64U numMgfKeyGenCompletedErrors; /**< Total number of MGF key generation operations that could not be * completed successfully due to errors. */ } CpaCyKeyGenStats64; /** ***************************************************************************** * @ingroup cpaCyKeyGen * SSL Key Generation Function. * @description * This function is used for SSL key generation. It implements the key * generation function defined in section 6.2.2 of the SSL 3.0 * specification as described in * http://www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt. * * The input seed is taken as a flat buffer and the generated key is * returned to caller in a flat destination data buffer. * @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] pKeyGenCb 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] pKeyGenSslOpData Structure containing all the data * needed to perform the SSL 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] pGeneratedKeyBuffer Caller MUST allocate a sufficient * buffer to hold the key generation * output. The data pointer SHOULD be * aligned on an 8-byte boundary. The * length field passed in represents the * size of the buffer in bytes. The value * that is returned is the size of the * result key in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @see * CpaCyKeyGenSslOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyKeyGenSsl(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenSslOpData *pKeyGenSslOpData, CpaFlatBuffer *pGeneratedKeyBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS Key Generation Function. * @description * This function is used for TLS key generation. It implements the * TLS PRF (Pseudo Random Function) as defined by RFC2246 (TLS v1.0) * and RFC4346 (TLS v1.1). * * The input seed is taken as a flat buffer and the generated key is * returned to caller in a flat destination data buffer. * * @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] pKeyGenCb 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] pKeyGenTlsOpData Structure containing all the data * needed to perform the TLS 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] pGeneratedKeyBuffer Caller MUST allocate a sufficient * buffer to hold the key generation * output. The data pointer SHOULD be * aligned on an 8-byte boundary. The * length field passed in represents the * size of the buffer in bytes. The value * that is returned is the size of the * result key in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @see * CpaCyKeyGenTlsOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyKeyGenTls(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenTlsOpData *pKeyGenTlsOpData, CpaFlatBuffer *pGeneratedKeyBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS Key Generation Function version 2. * @description * This function is used for TLS key generation. It implements the * TLS PRF (Pseudo Random Function) as defined by RFC5246 (TLS v1.2). * * The input seed is taken as a flat buffer and the generated key is * returned to caller in a flat destination data buffer. * * @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] pKeyGenCb 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] pKeyGenTlsOpData Structure containing all the data * needed to perform the TLS 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[in] hashAlgorithm Specifies the hash algorithm to use. * According to RFC5246, this should be * "SHA-256 or a stronger standard hash * function." * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient * buffer to hold the key generation * output. The data pointer SHOULD be * aligned on an 8-byte boundary. The * length field passed in represents the * size of the buffer in bytes. The value * that is returned is the size of the * result key in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @see * CpaCyKeyGenTlsOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyKeyGenTls2(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenTlsOpData *pKeyGenTlsOpData, CpaCySymHashAlgorithm hashAlgorithm, CpaFlatBuffer *pGeneratedKeyBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * TLS Key Generation Function version 3. * @description * This function is used for TLS key generation. It implements the * TLS HKDF (HMAC Key Derivation Function) as defined by * RFC5689 (HKDF) and RFC8446 (TLS 1.3). * * The input seed is taken as a flat buffer and the generated key is * returned to caller in a flat destination data buffer. * * @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] pKeyGenCb 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] pKeyGenTlsOpData Structure containing all the data * needed to perform the TLS 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. The memory * must be pinned and contiguous, suitable * for DMA operations. * @param[in] hashAlgorithm Specifies the hash algorithm to use. * According to RFC5246, this should be * "SHA-256 or a stronger standard hash * function." * @param[out] pGeneratedKeyBuffer Caller MUST allocate a sufficient * buffer to hold the key generation * output. The data pointer SHOULD be * aligned on an 8-byte boundary. The * length field passed in represents the * size of the buffer in bytes. The value * that is returned is the size of the * result key in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @see * CpaCyGenFlatBufCbFunc * CpaCyKeyGenHKDFOpData * *****************************************************************************/ CpaStatus cpaCyKeyGenTls3(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenHKDFOpData *pKeyGenTlsOpData, CpaCyKeyHKDFCipherSuite cipherSuite, CpaFlatBuffer *pGeneratedKeyBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * Mask Generation Function. * @description * This function implements the mask generation function MGF1 as * defined by PKCS#1 v2.1, and RFC3447. The input seed is taken * as a flat buffer and the generated mask is returned to caller in a * flat destination data buffer. * * @note The default hash algorithm used by the MGF is SHA-1. If a * different hash algorithm is preferred, then see the "extended" * version of this function, @ref cpaCyKeyGenMgfExt. * * @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] pKeyGenCb 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] pKeyGenMgfOpData Structure containing all the data needed * to perform the MGF 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] pGeneratedMaskBuffer Caller MUST allocate a sufficient buffer * to hold the generated mask. The data * pointer SHOULD be aligned on an 8-byte * boundary. The length field passed in * represents the size of the buffer in * bytes. The value that is returned is the * size of the generated mask in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @see * CpaCyKeyGenMgfOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyKeyGenMgf(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenMgfOpData *pKeyGenMgfOpData, CpaFlatBuffer *pGeneratedMaskBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * Extended Mask Generation Function. * @description * This function is used for mask generation. It differs from the "base" * version of the function (@ref cpaCyKeyGenMgf) in that it allows * the hash function used by the Mask Generation Function to be * specified. * * @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] pKeyGenCb 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] pKeyGenMgfOpDataExt Structure containing all the data needed * to perform the extended MGF 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] pGeneratedMaskBuffer Caller MUST allocate a sufficient buffer * to hold the generated mask. The data * pointer SHOULD be aligned on an 8-byte * boundary. The length field passed in * represents the size of the buffer in * bytes. The value that is returned is the * size of the generated mask in bytes. * 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. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @note * This function is only used to generate a mask keys from seed * material. * @see * CpaCyKeyGenMgfOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyKeyGenMgfExt(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pKeyGenCb, void *pCallbackTag, const CpaCyKeyGenMgfOpDataExt *pKeyGenMgfOpDataExt, CpaFlatBuffer *pGeneratedMaskBuffer); /** ***************************************************************************** * @ingroup cpaCyKeyGen * Queries the Key and Mask generation statistics specific to * an instance. * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyKeyGenQueryStats64(). * * @description * This function will query a specific instance for key and mask * generation statistics. The user MUST allocate the CpaCyKeyGenStats * structure and pass the reference to that into this function call. This * function will write the statistic results into the passed in * CpaCyKeyGenStats 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] pKeyGenStats 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. * * @pre * Component has been initialized. * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * * @see * CpaCyKeyGenStats * *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyKeyGenQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCyKeyGenStats *pKeyGenStats); /** ***************************************************************************** * @ingroup cpaCyKeyGen * Queries the Key and Mask generation statistics (64-bit version) * specific to an instance. * * @description * This function will query a specific instance for key and mask * generation statistics. The user MUST allocate the CpaCyKeyGenStats64 * structure and pass the reference to that into this function call. This * function will write the statistic results into the passed in * CpaCyKeyGenStats64 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] pKeyGenStats 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. * * @pre * Component has been initialized. * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * * @see * CpaCyKeyGenStats64 *****************************************************************************/ CpaStatus cpaCyKeyGenQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyKeyGenStats64 *pKeyGenStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_KEY_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_kpt.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_kpt.h index dbf510cacb82..e3efc2163848 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_kpt.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_kpt.h @@ -1,853 +1,820 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * 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 CpaCyKptKeyManagementStatus_t { 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 CpaCyKptValidationKey_t { 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 CpaCyKptWrappingKeyType_t { 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 CpaCyKptLoadKey_t { 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 CpaCyKptUnwrapContext_t { CpaCyKptHandle kptHandle; /**< This is application's unique handle that identifies its * (symmetric) wrapping key*/ Cpa8U iv[CPA_CY_KPT_MAX_IV_LENGTH]; /**< Initialization Vector */ 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) * Input = (D || N) * Encrypt (SWK, AAD, (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. * *****************************************************************************/ typedef struct CpaCyKptRsaPrivateKeyRep1_t { 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 * AAD = DER(OID) * Input = (P || Q || dP || dQ || Qinv || publicExponentE) * Expanded Description: * Encrypt (SWK, AAD, * (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). * *****************************************************************************/ typedef struct CpaCyKptRsaPrivateKeyRep2_t { 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 CpaCyKptRsaPrivateKey_t { 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 CpaCyKptRsaDecryptOpData_t { 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) * Input = (d) * Encrypt (SWK, AAD, (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 CpaCyKptEcdsaSignRSOpData_t { 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 diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_ln.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_ln.h index 6039720d3368..1049bb114948 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_ln.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_ln.h @@ -1,519 +1,486 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_ln.h * * @defgroup cpaCyLn Cryptographic Large Number API * * @ingroup cpaCy * * @description * These functions specify the Cryptographic API for Large Number * Operations. * * @note * Large numbers are represented on the QuickAssist API using octet * strings, stored in structures of type @ref CpaFlatBuffer. These * octet strings are encoded as described by PKCS#1 v2.1, section 4, * which is consistent with ASN.1 syntax. The following text * summarizes this. Any exceptions to this encoding are specified * on the specific data structure or function to which the exception * applies. * * An n-bit number, N, has a value in the range 2^(n-1) through 2^(n)-1. * In other words, its most significant bit, bit n-1 (where bit-counting * starts from zero) MUST be set to 1. We can also state that the * bit-length n of a number N is defined by n = floor(log2(N))+1. * * The buffer, b, in which an n-bit number N is stored, must be "large * enough". In other words, b.dataLenInBytes must be at least * minLenInBytes = ceiling(n/8). * * The number is stored in a "big endian" format. This means that the * least significant byte (LSB) is b[b.dataLenInBytes-1], while the * most significant byte (MSB) is b[b.dataLenInBytes-minLenInBytes]. * In the case where the buffer is "exactly" the right size, then the * MSB is b[0]. Otherwise, all bytes from b[0] up to the MSB MUST be * set to 0x00. * * The largest bit-length we support today is 8192 bits. In other * words, we can deal with numbers up to a value of (2^8192)-1. * *****************************************************************************/ #ifndef CPA_CY_LN_H #define CPA_CY_LN_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyLn * Modular Exponentiation Function Operation Data. * @description * This structure lists the different items that are required in the * cpaCyLnModExp 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 callback. * The operation size in bits is equal to the size of whichever of the * following is largest: the modulus, the base or the exponent. * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyLnModExp function, and * before it has been returned in the callback, undefined behavior will * result. * The values of the base, the exponent and the modulus MUST all be less * than 2^8192, and the modulus must not be equal to zero. *****************************************************************************/ typedef struct _CpaCyLnModExpOpData { CpaFlatBuffer modulus; /**< Flat buffer containing a pointer to the modulus. * This number may be up to 8192 bits in length, and MUST be greater * than zero. */ CpaFlatBuffer base; /**< Flat buffer containing a pointer to the base. * This number may be up to 8192 bits in length. */ CpaFlatBuffer exponent; /**< Flat buffer containing a pointer to the exponent. * This number may be up to 8192 bits in length. */ } CpaCyLnModExpOpData; /** ***************************************************************************** * @ingroup cpaCyLn * Modular Inversion Function Operation Data. * @description * This structure lists the different items that are required in the * function @ref cpaCyLnModInv. 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 * callback. * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCyLnModInv function, and * before it has been returned in the callback, undefined behavior will * result. * * Note that the values of A and B MUST NOT both be even numbers, and * both MUST be less than 2^8192. *****************************************************************************/ typedef struct _CpaCyLnModInvOpData { CpaFlatBuffer A; /**< Flat buffer containing a pointer to the value that will be * inverted. * This number may be up to 8192 bits in length, it MUST NOT be zero, * and it MUST be co-prime with B. */ CpaFlatBuffer B; /**< Flat buffer containing a pointer to the value that will be used as * the modulus. * This number may be up to 8192 bits in length, it MUST NOT be zero, * and it MUST be co-prime with A. */ } CpaCyLnModInvOpData; /** ***************************************************************************** * @ingroup cpaCyLn * Look Aside Cryptographic large number Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyLnStats64. * @description * This structure contains statistics on the Look Aside Cryptographic * large number operations. Statistics are set to zero when the component * is initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyLnStats { Cpa32U numLnModExpRequests; /**< Total number of successful large number modular exponentiation * requests.*/ Cpa32U numLnModExpRequestErrors; /**< Total number of large number modular exponentiation requests that * had an error and could not be processed. */ Cpa32U numLnModExpCompleted; /**< Total number of large number modular exponentiation operations * that completed successfully. */ Cpa32U numLnModExpCompletedErrors; /**< Total number of large number modular exponentiation operations * that could not be completed successfully due to errors. */ Cpa32U numLnModInvRequests; /**< Total number of successful large number modular inversion * requests.*/ Cpa32U numLnModInvRequestErrors; /**< Total number of large number modular inversion requests that * had an error and could not be processed. */ Cpa32U numLnModInvCompleted; /**< Total number of large number modular inversion operations * that completed successfully. */ Cpa32U numLnModInvCompletedErrors; /**< Total number of large number modular inversion operations * that could not be completed successfully due to errors. */ } CpaCyLnStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyLn * Look Aside Cryptographic large number Statistics. * @description * This structure contains statistics on the Look Aside Cryptographic * large number operations. Statistics are set to zero when the component * is initialized, and are collected per instance. * ****************************************************************************/ typedef struct _CpaCyLnStats64 { Cpa64U numLnModExpRequests; /**< Total number of successful large number modular exponentiation * requests.*/ Cpa64U numLnModExpRequestErrors; /**< Total number of large number modular exponentiation requests that * had an error and could not be processed. */ Cpa64U numLnModExpCompleted; /**< Total number of large number modular exponentiation operations * that completed successfully. */ Cpa64U numLnModExpCompletedErrors; /**< Total number of large number modular exponentiation operations * that could not be completed successfully due to errors. */ Cpa64U numLnModInvRequests; /**< Total number of successful large number modular inversion * requests.*/ Cpa64U numLnModInvRequestErrors; /**< Total number of large number modular inversion requests that * had an error and could not be processed. */ Cpa64U numLnModInvCompleted; /**< Total number of large number modular inversion operations * that completed successfully. */ Cpa64U numLnModInvCompletedErrors; /**< Total number of large number modular inversion operations * that could not be completed successfully due to errors. */ } CpaCyLnStats64; /** ***************************************************************************** * @ingroup cpaCyLn * Perform modular exponentiation operation. * * @description * This function performs modular exponentiation. It computes the * following result based on the inputs: * * result = (base ^ exponent) mod modulus * * @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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pLnModExpCb Pointer to callback function to be * invoked when the operation is complete. * @param[in] pCallbackTag Opaque User Data for this specific call. * Will be returned unchanged in the callback. * @param[in] pLnModExpOpData Structure containing all the data needed * to perform the LN modular exponentiation * 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] pResult Pointer to a flat buffer containing a * pointer to memory allocated by the client * into which the result will be written. * The size of the memory required MUST be * larger than or equal to the size * required to store the modulus. * 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 pLnModExpCb is non null, an asynchronous callback of type * CpaCyLnModExpCbFunc is generated in response to this function call. * Any errors generated during processing are reported in the structure * returned in the callback. * * @see * CpaCyLnModExpOpData, CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyLnModExp(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pLnModExpCb, void *pCallbackTag, const CpaCyLnModExpOpData *pLnModExpOpData, CpaFlatBuffer *pResult); /** ***************************************************************************** * @ingroup cpaCyLn * Perform modular inversion operation. * * @description * This function performs modular inversion. It computes the following * result based on the inputs: * * result = (1/A) mod B. * * @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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pLnModInvCb Pointer to callback function to be * invoked when the operation is complete. * @param[in] pCallbackTag Opaque User Data for this specific call. * Will be returned unchanged in the * callback. * @param[in] pLnModInvOpData Structure containing all the data * needed to perform the LN modular * inversion 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] pResult Pointer to a flat buffer containing a * pointer to memory allocated by the client * into which the result will be written. * The size of the memory required MUST be * larger than or equal to the size * required to store the modulus. * 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 pLnModInvCb is non null, an asynchronous callback of type * CpaCyLnModInvCbFunc is generated in response to this function call. * Any errors generated during processing are reported in the structure * returned in the callback. * * @see * CpaCyLnModInvOpData, * CpaCyGenFlatBufCbFunc * *****************************************************************************/ CpaStatus cpaCyLnModInv(const CpaInstanceHandle instanceHandle, const CpaCyGenFlatBufCbFunc pLnModInvCb, void *pCallbackTag, const CpaCyLnModInvOpData *pLnModInvOpData, CpaFlatBuffer *pResult); /** ***************************************************************************** * @ingroup cpaCyLn * Query statistics for large number operations * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyLnStatsQuery64(). * * @description * This function will query a specific instance handle for large number * statistics. The user MUST allocate the CpaCyLnStats structure and pass * the reference to that structure into this function call. This function * writes the statistic results into the passed in CpaCyLnStats 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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pLnStats 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 * Acceleration Services unit has been initialized. * * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * * @see * CpaCyLnStats * *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyLnStatsQuery(const CpaInstanceHandle instanceHandle, struct _CpaCyLnStats *pLnStats); /** ***************************************************************************** * @ingroup cpaCyLn * Query statistics (64-bit version) for large number operations * * @description * This function will query a specific instance handle for the 64-bit * version of the large number statistics. * The user MUST allocate the CpaCyLnStats64 structure and pass * the reference to that structure into this function call. This function * writes the statistic results into the passed in CpaCyLnStats64 * 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 * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pLnStats 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 * Acceleration Services unit has been initialized. * * @post * None * @note * This function operates in a synchronous manner and no asynchronous * callback will be generated. * * @see * CpaCyLnStats *****************************************************************************/ CpaStatus cpaCyLnStatsQuery64(const CpaInstanceHandle instanceHandle, CpaCyLnStats64 *pLnStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_LN_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_prime.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_prime.h index 11e4773a05d1..313a2aca7649 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_prime.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_prime.h @@ -1,450 +1,417 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_prime.h * * @defgroup cpaCyPrime Prime Number Test API * * @ingroup cpaCy * * @description * These functions specify the API for the prime number test operations. * * For prime number generation, this API SHOULD be used in conjunction * with the Deterministic Random Bit Generation API (@ref cpaCyDrbg). * * @note * Large numbers are represented on the QuickAssist API as described * in the Large Number API (@ref cpaCyLn). * * In addition, the bit length of large numbers passed to the API * MUST NOT exceed 576 bits for Elliptic Curve operations. *****************************************************************************/ #ifndef CPA_CY_PRIME_H #define CPA_CY_PRIME_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCyPrime * Prime Test Operation Data. * @description * This structure contains the operation data for the cpaCyPrimeTest * 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. primeCandidate.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 cpaCyPrimeTest * function, and before it has been returned in the callback, undefined * behavior will result. * * @see * cpaCyPrimeTest() * *****************************************************************************/ typedef struct _CpaCyPrimeTestOpData { CpaFlatBuffer primeCandidate; /**< The prime number candidate to test */ CpaBoolean performGcdTest; /**< A value of CPA_TRUE means perform a GCD Primality Test */ CpaBoolean performFermatTest; /**< A value of CPA_TRUE means perform a Fermat Primality Test */ Cpa32U numMillerRabinRounds; /**< Number of Miller Rabin Primality Test rounds. Set to 0 to perform * zero Miller Rabin tests. The maximum number of rounds supported is 50. */ CpaFlatBuffer millerRabinRandomInput; /**< Flat buffer containing a pointer to an array of n random numbers * for Miller Rabin Primality Tests. The size of the buffer MUST be * * n * (MAX(64,x)) * * where: * * - n is the requested number of rounds. * - x is the minimum number of bytes required to represent the prime * candidate, i.e. x = ceiling((ceiling(log2(p)))/8). * * Each random number MUST be greater than 1 and less than the prime * candidate - 1, with leading zeroes as necessary. */ CpaBoolean performLucasTest; /**< An CPA_TRUE value means perform a Lucas Primality Test */ } CpaCyPrimeTestOpData; /** ***************************************************************************** * @ingroup cpaCyPrime * Prime Number Test Statistics. * @deprecated * As of v1.3 of the Crypto API, this structure has been deprecated, * replaced by @ref CpaCyPrimeStats64. * @description * This structure contains statistics on the prime number test operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. * ****************************************************************************/ typedef struct _CpaCyPrimeStats { Cpa32U numPrimeTestRequests; /**< Total number of successful prime number test requests.*/ Cpa32U numPrimeTestRequestErrors; /**< Total number of prime number test requests that had an * error and could not be processed. */ Cpa32U numPrimeTestCompleted; /**< Total number of prime number test operations that completed * successfully. */ Cpa32U numPrimeTestCompletedErrors; /**< Total number of prime number test operations that could not be * completed successfully due to errors. */ Cpa32U numPrimeTestFailures; /**< Total number of prime number test operations that executed * successfully but the outcome of the test was that the number was not * prime. */ } CpaCyPrimeStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCyPrime * Prime Number Test Statistics (64-bit version). * @description * This structure contains a 64-bit version of the statistics on the * prime number test operations. * Statistics are set to zero when the component is initialized, and are * collected per instance. ****************************************************************************/ typedef struct _CpaCyPrimeStats64 { Cpa64U numPrimeTestRequests; /**< Total number of successful prime number test requests.*/ Cpa64U numPrimeTestRequestErrors; /**< Total number of prime number test requests that had an * error and could not be processed. */ Cpa64U numPrimeTestCompleted; /**< Total number of prime number test operations that completed * successfully. */ Cpa64U numPrimeTestCompletedErrors; /**< Total number of prime number test operations that could not be * completed successfully due to errors. */ Cpa64U numPrimeTestFailures; /**< Total number of prime number test operations that executed * successfully but the outcome of the test was that the number was not * prime. */ } CpaCyPrimeStats64; /** ***************************************************************************** * @ingroup cpaCyPrime * Definition of callback function invoked for cpaCyPrimeTest * requests. * * @description * This is the prototype for the cpaCyPrimeTest 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 the Operation data pointer * supplied in request. * @param[in] testPassed A value of CPA_TRUE means the prime candidate * is probably prime. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCyPrimeTest() * *****************************************************************************/ typedef void (*CpaCyPrimeTestCbFunc)(void *pCallbackTag, CpaStatus status, void *pOpData, CpaBoolean testPassed); /** ***************************************************************************** * @ingroup cpaCyPrime * Prime Number Test Function. * * @description * This function will test probabilistically if a number is prime. Refer * to ANSI X9.80 2005 for details. The primality result will be returned * in the asynchronous callback. * * The following combination of GCD, Fermat, Miller-Rabin, and Lucas * testing is supported: * (up to 1x GCD) + (up to 1x Fermat) + (up to 50x Miller-Rabin rounds) + * (up to 1x Lucas) * For example: * (1x GCD) + (25x Miller-Rabin) + (1x Lucas); * (1x GCD) + (1x Fermat); * (50x Miller-rabin); * * Tests are always performed in order of increasing complexity, for * example GCD first, then Fermat, then Miller-Rabin, and finally Lucas. * * For all of the primality tests, the following prime number "sizes" * (length in bits) are supported: all sizes up to and including 512 * bits, as well as sizes 768, 1024, 1536, 2048, 3072 and 4096. * * Candidate prime numbers MUST match these sizes accordingly, with * leading zeroes present where necessary. * * When this prime number test is used in conjunction with combined * Miller-Rabin and Lucas tests, it may be used as a means of performing * a self test operation on the random data generator. * * A response status of ok (pass == CPA_TRUE) means all requested * primality tests passed, and the prime candidate is probably prime * (the exact probability depends on the primality tests requested). * A response status of not ok (pass == CPA_FALSE) means one of the * requested primality tests failed (the prime candidate has been found * to be composite). * @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] pTestPassed A value of CPA_TRUE means the prime candidate * is probably prime. * * @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 * CpaCyPrimeTestCbFunc is generated in response to this function call. * For optimal performance, data pointers SHOULD be 8-byte aligned. * * @see * CpaCyPrimeTestOpData, CpaCyPrimeTestCbFunc * *****************************************************************************/ CpaStatus cpaCyPrimeTest(const CpaInstanceHandle instanceHandle, const CpaCyPrimeTestCbFunc pCb, void *pCallbackTag, const CpaCyPrimeTestOpData *pOpData, CpaBoolean *pTestPassed); /****************************************************************************** * @ingroup cpaCyPrime * Query prime number statistics specific to an instance. * * @deprecated * As of v1.3 of the Crypto API, this function has been deprecated, * replaced by @ref cpaCyPrimeQueryStats64(). * * @description * This function will query a specific instance for prime number * statistics. The user MUST allocate the CpaCyPrimeStats structure * and pass the reference to that into this function call. This function * will write the statistic results into the passed in * CpaCyPrimeStats 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] pPrimeStats 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. * *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCyPrimeQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCyPrimeStats *pPrimeStats); /****************************************************************************** * @ingroup cpaCyPrime * Query prime number statistics specific to an instance. * * @description * This function will query a specific instance for the 64-bit * version of the prime number statistics. * The user MUST allocate the CpaCyPrimeStats64 structure * and pass the reference to that into this function call. This function * will write the statistic results into the passed in * CpaCyPrimeStats64 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] pPrimeStats 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. *****************************************************************************/ CpaStatus cpaCyPrimeQueryStats64(const CpaInstanceHandle instanceHandle, CpaCyPrimeStats64 *pPrimeStats); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_PRIME_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_rsa.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_rsa.h index fb6c83725745..bd85b7ee178d 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_rsa.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_rsa.h @@ -1,919 +1,886 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * 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 */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_sym.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_sym.h index adc1671c7f57..45f456d4a31d 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_sym.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_sym.h @@ -1,1851 +1,1818 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_sym.h * * @defgroup cpaCySym Symmetric Cipher and Hash Cryptographic API * * @ingroup cpaCy * * @description * These functions specify the Cryptographic API for symmetric cipher, * hash, and combined cipher and hash operations. * *****************************************************************************/ #ifndef CPA_CY_SYM_H #define CPA_CY_SYM_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" /** ***************************************************************************** * @ingroup cpaCySym * Cryptographic component symmetric session context handle. * @description * Handle to a cryptographic session context. The memory for this handle * is allocated by the client. The size of the memory that the client needs * to allocate is determined by a call to the @ref * cpaCySymSessionCtxGetSize or @ref cpaCySymSessionCtxGetDynamicSize * functions. The session context memory is initialized with a call to * the @ref cpaCySymInitSession function. * This memory MUST not be freed until a call to @ref * cpaCySymRemoveSession has completed successfully. * *****************************************************************************/ typedef void * CpaCySymSessionCtx; /** ***************************************************************************** * @ingroup cpaCySym * Packet type for the cpaCySymPerformOp function * * @description * Enumeration which is used to indicate to the symmetric cryptographic * perform function on which type of packet the operation is required to * be invoked. Multi-part cipher and hash operations are useful when * processing needs to be performed on a message which is available to * the client in multiple parts (for example due to network fragmentation * of the packet). * * @note * There are some restrictions regarding the operations on which * partial packet processing is supported. For details, see the * function @ref cpaCySymPerformOp. * * @see * cpaCySymPerformOp() * *****************************************************************************/ typedef enum _CpaCySymPacketType { CPA_CY_SYM_PACKET_TYPE_FULL = 1, /**< Perform an operation on a full packet*/ CPA_CY_SYM_PACKET_TYPE_PARTIAL, /**< Perform a partial operation and maintain the state of the partial * operation within the session. This is used for either the first or * subsequent packets within a partial packet flow. */ CPA_CY_SYM_PACKET_TYPE_LAST_PARTIAL /**< Complete the last part of a multi-part operation */ } CpaCySymPacketType; /** ***************************************************************************** * @ingroup cpaCySym * Types of operations supported by the cpaCySymPerformOp function. * @description * This enumeration lists different types of operations supported by the * cpaCySymPerformOp function. The operation type is defined during * session registration and cannot be changed for a session once it has * been setup. * @see * cpaCySymPerformOp *****************************************************************************/ typedef enum _CpaCySymOp { CPA_CY_SYM_OP_NONE=0, /**< No operation */ CPA_CY_SYM_OP_CIPHER, /**< Cipher only operation on the data */ CPA_CY_SYM_OP_HASH, /**< Hash only operation on the data */ CPA_CY_SYM_OP_ALGORITHM_CHAINING /**< Chain any cipher with any hash operation. The order depends on * the value in the CpaCySymAlgChainOrder enum. * * This value is also used for authenticated ciphers (GCM and CCM), in * which case the cipherAlgorithm should take one of the values @ref * CPA_CY_SYM_CIPHER_AES_CCM or @ref CPA_CY_SYM_CIPHER_AES_GCM, while the * hashAlgorithm should take the corresponding value @ref * CPA_CY_SYM_HASH_AES_CCM or @ref CPA_CY_SYM_HASH_AES_GCM. */ } CpaCySymOp; /** ***************************************************************************** * @ingroup cpaCySym * Cipher algorithms. * @description * This enumeration lists supported cipher algorithms and modes. * *****************************************************************************/ typedef enum _CpaCySymCipherAlgorithm { CPA_CY_SYM_CIPHER_NULL = 1, /**< NULL cipher algorithm. No mode applies to the NULL algorithm. */ CPA_CY_SYM_CIPHER_ARC4, /**< (A)RC4 cipher algorithm */ CPA_CY_SYM_CIPHER_AES_ECB, /**< AES algorithm in ECB mode */ CPA_CY_SYM_CIPHER_AES_CBC, /**< AES algorithm in CBC mode */ CPA_CY_SYM_CIPHER_AES_CTR, /**< AES algorithm in Counter mode */ CPA_CY_SYM_CIPHER_AES_CCM, /**< AES algorithm in CCM mode. This authenticated cipher is only supported * when the hash mode is also set to CPA_CY_SYM_HASH_MODE_AUTH. When this * cipher algorithm is used the CPA_CY_SYM_HASH_AES_CCM element of the * CpaCySymHashAlgorithm enum MUST be used to set up the related * CpaCySymHashSetupData structure in the session context. */ CPA_CY_SYM_CIPHER_AES_GCM, /**< AES algorithm in GCM mode. This authenticated cipher is only supported * when the hash mode is also set to CPA_CY_SYM_HASH_MODE_AUTH. When this * cipher algorithm is used the CPA_CY_SYM_HASH_AES_GCM element of the * CpaCySymHashAlgorithm enum MUST be used to set up the related * CpaCySymHashSetupData structure in the session context. */ CPA_CY_SYM_CIPHER_DES_ECB, /**< DES algorithm in ECB mode */ CPA_CY_SYM_CIPHER_DES_CBC, /**< DES algorithm in CBC mode */ CPA_CY_SYM_CIPHER_3DES_ECB, /**< Triple DES algorithm in ECB mode */ CPA_CY_SYM_CIPHER_3DES_CBC, /**< Triple DES algorithm in CBC mode */ CPA_CY_SYM_CIPHER_3DES_CTR, /**< Triple DES algorithm in CTR mode */ CPA_CY_SYM_CIPHER_KASUMI_F8, /**< Kasumi algorithm in F8 mode */ CPA_CY_SYM_CIPHER_SNOW3G_UEA2, /**< SNOW3G algorithm in UEA2 mode */ CPA_CY_SYM_CIPHER_AES_F8, /**< AES algorithm in F8 mode */ CPA_CY_SYM_CIPHER_AES_XTS, /**< AES algorithm in XTS mode */ CPA_CY_SYM_CIPHER_ZUC_EEA3, /**< ZUC algorithm in EEA3 mode */ CPA_CY_SYM_CIPHER_CHACHA, /**< ChaCha20 Cipher Algorithm. This cipher is only supported for * algorithm chaining. When selected, the hash algorithm must be set to * CPA_CY_SYM_HASH_POLY and the hash mode must be set to * CPA_CY_SYM_HASH_MODE_AUTH. */ CPA_CY_SYM_CIPHER_SM4_ECB, /**< SM4 algorithm in ECB mode This cipher supports 128 bit keys only and * does not support partial processing. */ CPA_CY_SYM_CIPHER_SM4_CBC, /**< SM4 algorithm in CBC mode This cipher supports 128 bit keys only and * does not support partial processing. */ CPA_CY_SYM_CIPHER_SM4_CTR /**< SM4 algorithm in CTR mode This cipher supports 128 bit keys only and * does not support partial processing. */ } CpaCySymCipherAlgorithm; /** * @ingroup cpaCySym * Size of bitmap needed for cipher "capabilities" type. * * @description * Defines the number of bits in the bitmap to represent supported * ciphers in the type @ref CpaCySymCapabilitiesInfo. Should be set to * at least one greater than the largest value in the enumerated type * @ref CpaCySymHashAlgorithm, so that the value of the enum constant * can also be used as the bit position in the bitmap. * * A larger value was chosen to allow for extensibility without the need * to change the size of the bitmap (to ease backwards compatibility in * future versions of the API). */ #define CPA_CY_SYM_CIPHER_CAP_BITMAP_SIZE (32) /** ***************************************************************************** * @ingroup cpaCySym * Symmetric Cipher Direction * @description * This enum indicates the cipher direction (encryption or decryption). * *****************************************************************************/ typedef enum _CpaCySymCipherDirection { CPA_CY_SYM_CIPHER_DIRECTION_ENCRYPT = 1, /**< Encrypt Data */ CPA_CY_SYM_CIPHER_DIRECTION_DECRYPT /**< Decrypt Data */ } CpaCySymCipherDirection; /** ***************************************************************************** * @ingroup cpaCySym * Symmetric Cipher Setup Data. * @description * This structure contains data relating to Cipher (Encryption and * Decryption) to setup a session. * *****************************************************************************/ typedef struct _CpaCySymCipherSetupData { CpaCySymCipherAlgorithm cipherAlgorithm; /**< Cipher algorithm and mode */ Cpa32U cipherKeyLenInBytes; /**< Cipher key length in bytes. For AES it can be 128 bits (16 bytes), * 192 bits (24 bytes) or 256 bits (32 bytes). * For the CCM mode of operation, the only supported key length is 128 bits * (16 bytes). * For the CPA_CY_SYM_CIPHER_AES_F8 mode of operation, cipherKeyLenInBytes * should be set to the combined length of the encryption key and the * keymask. Since the keymask and the encryption key are the same size, * cipherKeyLenInBytes should be set to 2 x the AES encryption key length. * For the AES-XTS mode of operation: * - Two keys must be provided and cipherKeyLenInBytes refers to total * length of the two keys. * - Each key can be either 128 bits (16 bytes) or 256 bits (32 bytes). * - Both keys must have the same size. */ Cpa8U *pCipherKey; /**< Cipher key * For the CPA_CY_SYM_CIPHER_AES_F8 mode of operation, pCipherKey will * point to a concatenation of the AES encryption key followed by a * keymask. As per RFC3711, the keymask should be padded with trailing * bytes to match the length of the encryption key used. * For AES-XTS mode of operation, two keys must be provided and pCipherKey * must point to the two keys concatenated together (Key1 || Key2). * cipherKeyLenInBytes will contain the total size of both keys. * These fields are set to NULL if key derivation will be used. */ CpaCySymCipherDirection cipherDirection; /**< This parameter determines if the cipher operation is an encrypt or * a decrypt operation. * For the RC4 algorithm and the F8/CTR modes, only encrypt operations * are valid. */ } CpaCySymCipherSetupData; /** ***************************************************************************** * @ingroup cpaCySym * Symmetric Hash mode * @description * This enum indicates the Hash Mode. * *****************************************************************************/ typedef enum _CpaCySymHashMode { CPA_CY_SYM_HASH_MODE_PLAIN = 1, /**< Plain hash. Can be specified for MD5 and the SHA family of * hash algorithms. */ CPA_CY_SYM_HASH_MODE_AUTH, /**< Authenticated hash. This mode may be used in conjunction with the * MD5 and SHA family of algorithms to specify HMAC. It MUST also be * specified with all of the remaining algorithms, all of which are in * fact authentication algorithms. */ CPA_CY_SYM_HASH_MODE_NESTED /**< Nested hash. Can be specified for MD5 and the SHA family of * hash algorithms. */ } CpaCySymHashMode; /** ***************************************************************************** * @ingroup cpaCySym * Hash algorithms. * @description * This enumeration lists supported hash algorithms. * *****************************************************************************/ typedef enum _CpaCySymHashAlgorithm { CPA_CY_SYM_HASH_NONE = 0, /**< No hash algorithm. */ CPA_CY_SYM_HASH_MD5, /**< MD5 algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_SHA1, /**< 128 bit SHA algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_SHA224, /**< 224 bit SHA algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_SHA256, /**< 256 bit SHA algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_SHA384, /**< 384 bit SHA algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_SHA512, /**< 512 bit SHA algorithm. Supported in all 3 hash modes */ CPA_CY_SYM_HASH_AES_XCBC, /**< AES XCBC algorithm. This is only supported in the hash mode * CPA_CY_SYM_HASH_MODE_AUTH. */ CPA_CY_SYM_HASH_AES_CCM, /**< AES algorithm in CCM mode. This authenticated cipher requires that the * hash mode is set to CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm * is used, the CPA_CY_SYM_CIPHER_AES_CCM element of the * CpaCySymCipherAlgorithm enum MUST be used to set up the related * CpaCySymCipherSetupData structure in the session context. */ CPA_CY_SYM_HASH_AES_GCM, /**< AES algorithm in GCM mode. This authenticated cipher requires that the * hash mode is set to CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm * is used, the CPA_CY_SYM_CIPHER_AES_GCM element of the * CpaCySymCipherAlgorithm enum MUST be used to set up the related * CpaCySymCipherSetupData structure in the session context. */ CPA_CY_SYM_HASH_KASUMI_F9, /**< Kasumi algorithm in F9 mode. This is only supported in the hash * mode CPA_CY_SYM_HASH_MODE_AUTH. */ CPA_CY_SYM_HASH_SNOW3G_UIA2, /**< SNOW3G algorithm in UIA2 mode. This is only supported in the hash * mode CPA_CY_SYM_HASH_MODE_AUTH. */ CPA_CY_SYM_HASH_AES_CMAC, /**< AES CMAC algorithm. This is only supported in the hash mode * CPA_CY_SYM_HASH_MODE_AUTH. */ CPA_CY_SYM_HASH_AES_GMAC, /**< AES GMAC algorithm. This is only supported in the hash mode * CPA_CY_SYM_HASH_MODE_AUTH. When this hash algorithm * is used, the CPA_CY_SYM_CIPHER_AES_GCM element of the * CpaCySymCipherAlgorithm enum MUST be used to set up the related * CpaCySymCipherSetupData structure in the session context. */ CPA_CY_SYM_HASH_AES_CBC_MAC, /**< AES-CBC-MAC algorithm. This is only supported in the hash mode * CPA_CY_SYM_HASH_MODE_AUTH. Only 128-bit keys are supported. */ CPA_CY_SYM_HASH_ZUC_EIA3, /**< ZUC algorithm in EIA3 mode */ CPA_CY_SYM_HASH_SHA3_256, /**< 256 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. * Partial requests are not supported, that is, only requests * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ CPA_CY_SYM_HASH_SHA3_224, /**< 224 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. */ CPA_CY_SYM_HASH_SHA3_384, /**< 384 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. * Partial requests are not supported, that is, only requests * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ CPA_CY_SYM_HASH_SHA3_512, /**< 512 bit SHA-3 algorithm. Only CPA_CY_SYM_HASH_MODE_PLAIN and * CPA_CY_SYM_HASH_MODE_AUTH are supported, that is, the hash * mode CPA_CY_SYM_HASH_MODE_NESTED is not supported for this algorithm. * Partial requests are not supported, that is, only requests * of CPA_CY_SYM_PACKET_TYPE_FULL are supported. */ CPA_CY_SYM_HASH_SHAKE_128, /**< 128 bit SHAKE algorithm. This is only supported in the hash * mode CPA_CY_SYM_HASH_MODE_PLAIN. Partial requests are not * supported, that is, only requests of CPA_CY_SYM_PACKET_TYPE_FULL * are supported. */ CPA_CY_SYM_HASH_SHAKE_256, /**< 256 bit SHAKE algorithm. This is only supported in the hash * mode CPA_CY_SYM_HASH_MODE_PLAIN. Partial requests are not * supported, that is, only requests of CPA_CY_SYM_PACKET_TYPE_FULL * are supported. */ CPA_CY_SYM_HASH_POLY, /**< Poly1305 hash algorithm. This is only supported in the hash mode * CPA_CY_SYM_HASH_MODE_AUTH. This hash algorithm is only supported * as part of an algorithm chain with AES_CY_SYM_CIPHER_CHACHA to * implement the ChaCha20-Poly1305 AEAD algorithm. */ CPA_CY_SYM_HASH_SM3 /**< SM3 hash algorithm. Supported in all 3 hash modes. */ } CpaCySymHashAlgorithm; /** * @ingroup cpaCySym * Size of bitmap needed for hash "capabilities" type. * * @description * Defines the number of bits in the bitmap to represent supported * hashes in the type @ref CpaCySymCapabilitiesInfo. Should be set to * at least one greater than the largest value in the enumerated type * @ref CpaCySymHashAlgorithm, so that the value of the enum constant * can also be used as the bit position in the bitmap. * * A larger value was chosen to allow for extensibility without the need * to change the size of the bitmap (to ease backwards compatibility in * future versions of the API). */ #define CPA_CY_SYM_HASH_CAP_BITMAP_SIZE (32) /** ***************************************************************************** * @ingroup cpaCySym * Hash Mode Nested Setup Data. * @description * This structure contains data relating to a hash session in * CPA_CY_SYM_HASH_MODE_NESTED mode. * *****************************************************************************/ typedef struct _CpaCySymHashNestedModeSetupData { Cpa8U *pInnerPrefixData; /**< A pointer to a buffer holding the Inner Prefix data. For optimal * performance the prefix data SHOULD be 8-byte aligned. This data is * prepended to the data being hashed before the inner hash operation is * performed. */ Cpa32U innerPrefixLenInBytes; /**< The inner prefix length in bytes. The maximum size the prefix data * can be is 255 bytes. */ CpaCySymHashAlgorithm outerHashAlgorithm; /**< The hash algorithm used for the outer hash. Note: The inner hash * algorithm is provided in the hash context. */ Cpa8U *pOuterPrefixData; /**< A pointer to a buffer holding the Outer Prefix data. For optimal * performance the prefix data SHOULD be 8-byte aligned. This data is * prepended to the output from the inner hash operation before the outer * hash operation is performed.*/ Cpa32U outerPrefixLenInBytes; /**< The outer prefix length in bytes. The maximum size the prefix data * can be is 255 bytes. */ } CpaCySymHashNestedModeSetupData; /** ***************************************************************************** * @ingroup cpaCySym * Hash Auth Mode Setup Data. * @description * This structure contains data relating to a hash session in * CPA_CY_SYM_HASH_MODE_AUTH mode. * *****************************************************************************/ typedef struct _CpaCySymHashAuthModeSetupData { Cpa8U *authKey; /**< Authentication key pointer. * For the GCM (@ref CPA_CY_SYM_HASH_AES_GCM) and CCM (@ref * CPA_CY_SYM_HASH_AES_CCM) modes of operation, this field is ignored; * the authentication key is the same as the cipher key (see * the field pCipherKey in struct @ref CpaCySymCipherSetupData). */ Cpa32U authKeyLenInBytes; /**< Length of the authentication key in bytes. The key length MUST be * less than or equal to the block size of the algorithm. It is the client's * responsibility to ensure that the key length is compliant with the * standard being used (for example RFC 2104, FIPS 198a). * * For the GCM (@ref CPA_CY_SYM_HASH_AES_GCM) and CCM (@ref * CPA_CY_SYM_HASH_AES_CCM) modes of operation, this field is ignored; * the authentication key is the same as the cipher key, and so is its * length (see the field cipherKeyLenInBytes in struct @ref * CpaCySymCipherSetupData). */ Cpa32U aadLenInBytes; /**< The length of the additional authenticated data (AAD) in bytes. * The maximum permitted value is 240 bytes, unless otherwise * specified below. * * This field must be specified when the hash algorithm is one of the * following: * - For SNOW3G (@ref CPA_CY_SYM_HASH_SNOW3G_UIA2), this is the * length of the IV (which should be 16). * - For GCM (@ref CPA_CY_SYM_HASH_AES_GCM). In this case, this is the * length of the Additional Authenticated Data (called A, in NIST * SP800-38D). * - For CCM (@ref CPA_CY_SYM_HASH_AES_CCM). In this case, this is the * length of the associated data (called A, in NIST SP800-38C). * Note that this does NOT include the length of any padding, or the * 18 bytes reserved at the start of the above field to store the * block B0 and the encoded length. The maximum permitted value in * this case is 222 bytes. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of operation * this field is not used and should be set to 0. Instead the length * of the AAD data is specified in the messageLenToHashInBytes field of * the CpaCySymOpData structure. */ } CpaCySymHashAuthModeSetupData; /** ***************************************************************************** * @ingroup cpaCySym * Hash Setup Data. * @description * This structure contains data relating to a hash session. The fields * hashAlgorithm, hashMode and digestResultLenInBytes are common to all * three hash modes and MUST be set for each mode. * *****************************************************************************/ typedef struct _CpaCySymHashSetupData { CpaCySymHashAlgorithm hashAlgorithm; /**< Hash algorithm. For mode CPA_CY_SYM_MODE_HASH_NESTED, this is the * inner hash algorithm. */ CpaCySymHashMode hashMode; /**< Mode of the hash operation. Valid options include plain, auth or * nested hash mode. */ Cpa32U digestResultLenInBytes; /**< Length of the digest to be returned. If the verify option is set, * this specifies the length of the digest to be compared for the * session. * * For CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this is the octet length * of the MAC, which can be one of 4, 6, 8, 10, 12, 14 or 16. * * For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), this is the length in bytes * of the authentication tag. * * If the value is less than the maximum length allowed by the hash, * the result shall be truncated. If the value is greater than the * maximum length allowed by the hash, an error (@ref * CPA_STATUS_INVALID_PARAM) is returned from the function @ref * cpaCySymInitSession. * * In the case of nested hash, it is the outer hash which determines * the maximum length allowed. */ CpaCySymHashAuthModeSetupData authModeSetupData; /**< Authentication Mode Setup Data. * Only valid for mode CPA_CY_SYM_MODE_HASH_AUTH */ CpaCySymHashNestedModeSetupData nestedModeSetupData; /**< Nested Hash Mode Setup Data * Only valid for mode CPA_CY_SYM_MODE_HASH_NESTED */ } CpaCySymHashSetupData; /** ***************************************************************************** * @ingroup cpaCySym * Algorithm Chaining Operation Ordering * @description * This enum defines the ordering of operations for algorithm chaining. * ****************************************************************************/ typedef enum _CpaCySymAlgChainOrder { CPA_CY_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER = 1, /**< Perform the hash operation followed by the cipher operation. If it is * required that the result of the hash (i.e. the digest) is going to be * included in the data to be ciphered, then: * *
    *
  • The digest MUST be placed in the destination buffer at the * location corresponding to the end of the data region to be hashed * (hashStartSrcOffsetInBytes + messageLenToHashInBytes), * i.e. there must be no gaps between the start of the digest and the * end of the data region to be hashed.
    • *
  • The messageLenToCipherInBytes member of the CpaCySymOpData * structure must be equal to the overall length of the plain text, * the digest length and any (optional) trailing data that is to be * included.
    • *
  • The messageLenToCipherInBytes must be a multiple to the block * size if a block cipher is being used.
    • *
* * The following is an example of the layout of the buffer before the * operation, after the hash, and after the cipher: @verbatim +-------------------------+---------------+ | Plaintext | Tail | +-------------------------+---------------+ <-messageLenToHashInBytes-> +-------------------------+--------+------+ | Plaintext | Digest | Tail | +-------------------------+--------+------+ <--------messageLenToCipherInBytes--------> +-----------------------------------------+ | Cipher Text | +-----------------------------------------+ @endverbatim */ CPA_CY_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH /**< Perform the cipher operation followed by the hash operation. * The hash operation will be performed on the ciphertext resulting from * the cipher operation. * * The following is an example of the layout of the buffer before the * operation, after the cipher, and after the hash: @verbatim +--------+---------------------------+---------------+ | Head | Plaintext | Tail | +--------+---------------------------+---------------+ <-messageLenToCipherInBytes-> +--------+---------------------------+---------------+ | Head | Ciphertext | Tail | +--------+---------------------------+---------------+ <------messageLenToHashInBytes-------> +--------+---------------------------+--------+------+ | Head | Ciphertext | Digest | Tail | +--------+---------------------------+--------+------+ @endverbatim * */ } CpaCySymAlgChainOrder; /** ***************************************************************************** * @ingroup cpaCySym * Session Setup Data. * @description * This structure contains data relating to setting up a session. The * client needs to complete the information in this structure in order to * setup a session. * ****************************************************************************/ typedef struct _CpaCySymSessionSetupData { CpaCyPriority sessionPriority; /**< Priority of this session */ CpaCySymOp symOperation; /**< Operation to perform */ CpaCySymCipherSetupData cipherSetupData; /**< Cipher Setup Data for the session. This member is ignored for the * CPA_CY_SYM_OP_HASH operation. */ CpaCySymHashSetupData hashSetupData; /**< Hash Setup Data for a session. This member is ignored for the * CPA_CY_SYM_OP_CIPHER operation. */ CpaCySymAlgChainOrder algChainOrder; /**< If this operation data structure relates to an algorithm chaining * session then this parameter determines the order in which the chained * operations are performed. If this structure does not relate to an * algorithm chaining session then this parameter will be ignored. * * @note In the case of authenticated ciphers (GCM and CCM), which are * also presented as "algorithm chaining", this value is also ignored. * The chaining order is defined by the authenticated cipher, in those * cases. */ CpaBoolean digestIsAppended; /**< Flag indicating whether the digest is appended immediately following * the region over which the digest is computed. This is true for both * IPsec packets and SSL/TLS records. * * If this flag is set, then the value of the pDigestResult field of * the structure @ref CpaCySymOpData is ignored. * * @note The value of this field is ignored for the authenticated cipher * AES_CCM as the digest must be appended in this case. * * @note Setting digestIsAppended for hash only operations when * verifyDigest is also set is not supported. For hash only operations * when verifyDigest is set, digestIsAppended should be set to CPA_FALSE. */ CpaBoolean verifyDigest; /**< This flag is relevant only for operations which generate a message * digest. If set to true, the computed digest will not be written back * to the buffer location specified by other parameters, but instead will * be verified (i.e. compared to the value passed in at that location). * The number of bytes to be written or compared is indicated by the * digest output length for the session. * @note This option is only valid for full packets and for final * partial packets when using partials without algorithm chaining. * @note The value of this field is ignored for the authenticated ciphers * (AES_CCM and AES_GCM). Digest verification is always done for these * (when the direction is decrypt) and unless the DP API is used, * the message buffer will be zeroed if verification fails. When using the * DP API, it is the API clients responsibility to clear the message * buffer when digest verification fails. */ CpaBoolean partialsNotRequired; /**< This flag indicates if partial packet processing is required for this * session. If set to true, partial packet processing will not be enabled * for this session and any calls to cpaCySymPerformOp() with the * packetType parameter set to a value other than * CPA_CY_SYM_PACKET_TYPE_FULL will fail. */ } CpaCySymSessionSetupData ; /** ***************************************************************************** * @ingroup cpaCySym * Session Update Data. * @description * This structure contains data relating to resetting a session. ****************************************************************************/ typedef struct _CpaCySymSessionUpdateData { Cpa32U flags; /**< Flags indicating which fields to update. * All bits should be set to 0 except those fields to be updated. */ #define CPA_CY_SYM_SESUPD_CIPHER_KEY 1 << 0 #define CPA_CY_SYM_SESUPD_CIPHER_DIR 1 << 1 #define CPA_CY_SYM_SESUPD_AUTH_KEY 1 << 2 Cpa8U *pCipherKey; /**< Cipher key. * The same restrictions apply as described in the corresponding field * of the data structure @ref CpaCySymCipherSetupData. */ CpaCySymCipherDirection cipherDirection; /**< This parameter determines if the cipher operation is an encrypt or * a decrypt operation. * The same restrictions apply as described in the corresponding field * of the data structure @ref CpaCySymCipherSetupData. */ Cpa8U *authKey; /**< Authentication key pointer. * The same restrictions apply as described in the corresponding field * of the data structure @ref CpaCySymHashAuthModeSetupData. */ } CpaCySymSessionUpdateData; /** ***************************************************************************** * @ingroup cpaCySym * Cryptographic Component Operation Data. * @description * This structure contains data relating to performing cryptographic * processing on a data buffer. This request is used with * cpaCySymPerformOp() call for performing cipher, hash, auth cipher * or a combined hash and cipher operation. * * @see * CpaCySymPacketType * * @note * If the client modifies or frees the memory referenced in this structure * after it has been submitted to the cpaCySymPerformOp function, and * before it has been returned in the callback, undefined behavior will * result. ****************************************************************************/ typedef struct _CpaCySymOpData { CpaCySymSessionCtx sessionCtx; /**< Handle for the initialized session context */ CpaCySymPacketType packetType; /**< Selects the packet type */ Cpa8U *pIv; /**< Initialization Vector or Counter. * * - For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for * SNOW3G in UEA2 mode, this is the Initialization Vector (IV) * value. * - For block ciphers in CTR mode, this is the counter. * - For GCM mode, this is either the IV (if the length is 96 bits) or J0 * (for other sizes), where J0 is as defined by NIST SP800-38D. * Regardless of the IV length, a full 16 bytes needs to be allocated. * - For CCM mode, the first byte is reserved, and the nonce should be * written starting at &pIv[1] (to allow space for the implementation * to write in the flags in the first byte). Note that a full 16 bytes * should be allocated, even though the ivLenInBytes field will have * a value less than this. * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. * - For AES-XTS, this is the 128bit tweak, i, from IEEE Std 1619-2007. * * For optimum performance, the data pointed to SHOULD be 8-byte * aligned. * * The IV/Counter will be updated after every partial cryptographic * operation. */ Cpa32U ivLenInBytes; /**< Length of valid IV data pointed to by the pIv parameter. * * - For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for * SNOW3G in UEA2 mode, this is the length of the IV (which * must be the same as the block length of the cipher). * - For block ciphers in CTR mode, this is the length of the counter * (which must be the same as the block length of the cipher). * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which * case pIv points to J0. * - For CCM mode, this is the length of the nonce, which can be in the * range 7 to 13 inclusive. */ Cpa32U cryptoStartSrcOffsetInBytes; /**< Starting point for cipher processing, specified as number of bytes * from start of data in the source buffer. The result of the cipher * operation will be written back into the output buffer starting * at this location. */ Cpa32U messageLenToCipherInBytes; /**< The message length, in bytes, of the source buffer on which the * cryptographic operation will be computed. This must be a multiple of * the block size if a block cipher is being used. This is also the same * as the result length. * * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value * should not include the length of the padding or the length of the * MAC; the driver will compute the actual number of bytes over which * the encryption will occur, which will include these values. * * @note There are limitations on this length for partial * operations. Refer to the cpaCySymPerformOp function description for * details. * * @note On some implementations, this length may be limited to a 16-bit * value (65535 bytes). * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field * should be set to 0. */ Cpa32U hashStartSrcOffsetInBytes; /**< Starting point for hash processing, specified as number of bytes * from start of packet in source buffer. * * @note For CCM and GCM modes of operation, this field is ignored. * The field @ref pAdditionalAuthData field should be set instead. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field specifies the start of the AAD data in * the source buffer. */ Cpa32U messageLenToHashInBytes; /**< The message length, in bytes, of the source buffer that the hash * will be computed on. * * @note There are limitations on this length for partial operations. * Refer to the @ref cpaCySymPerformOp function description for details. * * @note For CCM and GCM modes of operation, this field is ignored. * The field @ref pAdditionalAuthData field should be set instead. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field specifies the length of the AAD data in the * source buffer. The maximum length supported for AAD data for AES-GMAC * is 16383 bytes. * * @note On some implementations, this length may be limited to a 16-bit * value (65535 bytes). */ Cpa8U *pDigestResult; /**< If the digestIsAppended member of the @ref CpaCySymSessionSetupData * structure is NOT set then this is a pointer to the location where the * digest result should be inserted (in the case of digest generation) * or where the purported digest exists (in the case of digest verification). * * At session registration time, the client specified the digest result * length with the digestResultLenInBytes member of the @ref * CpaCySymHashSetupData structure. The client must allocate at least * digestResultLenInBytes of physically contiguous memory at this location. * * For partial packet processing without algorithm chaining, this pointer * will be ignored for all but the final partial operation. * * For digest generation, the digest result will overwrite any data * at this location. * * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result" * read "authentication tag T". * * If the digestIsAppended member of the @ref CpaCySymSessionSetupData * structure is set then this value is ignored and the digest result * is understood to be in the destination buffer for digest generation, * and in the source buffer for digest verification. The location of the * digest result in this case is immediately following the region over * which the digest is computed. * */ Cpa8U *pAdditionalAuthData; /**< Pointer to Additional Authenticated Data (AAD) needed for * authenticated cipher mechanisms (CCM and GCM), and to the IV for * SNOW3G authentication (@ref CPA_CY_SYM_HASH_SNOW3G_UIA2). * For other authentication mechanisms this pointer is ignored. * * The length of the data pointed to by this field is set up for * the session in the @ref CpaCySymHashAuthModeSetupData structure * as part of the @ref cpaCySymInitSession function call. This length * must not exceed 240 bytes. * * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM), the caller * should setup this field as follows: * * - the nonce should be written starting at an offset of one byte * into the array, leaving room for the implementation to write in * the flags to the first byte. For example, *
* memcpy(&pOpData->pAdditionalAuthData[1], pNonce, nonceLen); *
* The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. * * - the additional authentication data itself should be written * starting at an offset of 18 bytes into the array, leaving room for * the length encoding in the first two bytes of the second block. * For example, *
* memcpy(&pOpData->pAdditionalAuthData[18], pAad, aadLen); *
* The macro @ref CPA_CY_SYM_CCM_SET_AAD may be used here. * * - the array should be big enough to hold the above fields, plus * any padding to round this up to the nearest multiple of the * block size (16 bytes). Padding will be added by the * implementation. * * Finally, for GCM (@ref CPA_CY_SYM_HASH_AES_GCM), the caller * should setup this field as follows: * * - the AAD is written in starting at byte 0 * - the array must be big enough to hold the AAD, plus any padding * to round this up to the nearest multiple of the block size (16 * bytes). Padding will be added by the implementation. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field is not used and should be set to 0. Instead * the AAD data should be placed in the source buffer. */ } CpaCySymOpData; /** ***************************************************************************** * @ingroup cpaCySym * Setup the nonce for CCM. * @description * This macro sets the nonce in the appropriate locations of the * @ref CpaCySymOpData struct for the authenticated encryption * algorithm @ref CPA_CY_SYM_HASH_AES_CCM. ****************************************************************************/ #define CPA_CY_SYM_CCM_SET_NONCE(pOpData, pNonce, nonceLen) do { \ memcpy(&pOpData->pIv[1], pNonce, nonceLen); \ memcpy(&pOpData->pAdditionalAuthData[1], pNonce, nonceLen); \ } while (0) /** ***************************************************************************** * @ingroup cpaCySym * Setup the additional authentication data for CCM. * @description * This macro sets the additional authentication data in the * appropriate location of the@ref CpaCySymOpData struct for the * authenticated encryption algorithm @ref CPA_CY_SYM_HASH_AES_CCM. ****************************************************************************/ #define CPA_CY_SYM_CCM_SET_AAD(pOpData, pAad, aadLen) do { \ memcpy(&pOpData->pAdditionalAuthData[18], pAad, aadLen); \ } while (0) /** ***************************************************************************** * @ingroup cpaCySym * Cryptographic Component Statistics. * @deprecated * As of v1.3 of the cryptographic API, this structure has been * deprecated, replaced by @ref CpaCySymStats64. * @description * This structure contains statistics on the Symmetric Cryptographic * operations. Statistics are set to zero when the component is * initialized. ****************************************************************************/ typedef struct _CpaCySymStats { Cpa32U numSessionsInitialized; /**< Number of session initialized */ Cpa32U numSessionsRemoved; /**< Number of sessions removed */ Cpa32U numSessionErrors; /**< Number of session initialized and removed errors. */ Cpa32U numSymOpRequests; /**< Number of successful symmetric operation requests. */ Cpa32U numSymOpRequestErrors; /**< Number of operation requests that had an error and could * not be processed. */ Cpa32U numSymOpCompleted; /**< Number of operations that completed successfully. */ Cpa32U numSymOpCompletedErrors; /**< Number of operations that could not be completed * successfully due to errors. */ Cpa32U numSymOpVerifyFailures; /**< Number of operations that completed successfully, but the * result of the digest verification test was that it failed. * Note that this does not indicate an error condition. */ } CpaCySymStats CPA_DEPRECATED; /** ***************************************************************************** * @ingroup cpaCySym * Cryptographic Component Statistics (64-bit version). * @description * This structure contains a 64-bit version of the statistics on * the Symmetric Cryptographic operations. * Statistics are set to zero when the component is initialized. ****************************************************************************/ typedef struct _CpaCySymStats64 { Cpa64U numSessionsInitialized; /**< Number of session initialized */ Cpa64U numSessionsRemoved; /**< Number of sessions removed */ Cpa64U numSessionErrors; /**< Number of session initialized and removed errors. */ Cpa64U numSymOpRequests; /**< Number of successful symmetric operation requests. */ Cpa64U numSymOpRequestErrors; /**< Number of operation requests that had an error and could * not be processed. */ Cpa64U numSymOpCompleted; /**< Number of operations that completed successfully. */ Cpa64U numSymOpCompletedErrors; /**< Number of operations that could not be completed * successfully due to errors. */ Cpa64U numSymOpVerifyFailures; /**< Number of operations that completed successfully, but the * result of the digest verification test was that it failed. * Note that this does not indicate an error condition. */ } CpaCySymStats64; /** ***************************************************************************** * @ingroup cpaCySym * Definition of callback function * * @description * This is the callback function prototype. The callback function is * registered by the application using the cpaCySymInitSession() * function call. * * @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 call. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] operationType Identifies the operation type that was * requested in the cpaCySymPerformOp function. * @param[in] pOpData Pointer to structure with input parameters. * @param[in] pDstBuffer Caller MUST allocate a sufficiently sized * destination buffer to hold the data output. For * out-of-place processing the data outside the * cryptographic regions in the source buffer are * copied into the destination buffer. To perform * "in-place" processing set the pDstBuffer * parameter in cpaCySymPerformOp function to point * at the same location as pSrcBuffer. For optimum * performance, the data pointed to SHOULD be * 8-byte aligned. * @param[in] verifyResult This parameter is valid when the verifyDigest * option is set in the CpaCySymSessionSetupData * structure. A value of CPA_TRUE indicates that * the compare succeeded. A value of CPA_FALSE * indicates that the compare failed for an * unspecified reason. * * @retval * None * @pre * Component has been initialized. * @post * None * @note * None * @see * cpaCySymInitSession(), * cpaCySymRemoveSession() * *****************************************************************************/ typedef void (*CpaCySymCbFunc)(void *pCallbackTag, CpaStatus status, const CpaCySymOp operationType, void *pOpData, CpaBufferList *pDstBuffer, CpaBoolean verifyResult); /** ***************************************************************************** * @ingroup cpaCySym * Gets the size required to store a session context. * * @description * This function is used by the client to determine the size of the memory * it must allocate in order to store the session context. This MUST be * called before the client allocates the memory for the session context * and before the client calls the @ref cpaCySymInitSession function. * * For a given implementation of this API, it is safe to assume that * cpaCySymSessionCtxGetSize() will always return the same size and that * the size will not be different for different setup data parameters. * However, it should be noted that the size may change: * (1) between different implementations of the API (e.g. between software * and hardware implementations or between different hardware * implementations) * (2) between different releases of the same API implementation. * * The size returned by this function is the smallest size needed to * support all possible combinations of setup data parameters. Some * setup data parameter combinations may fit within a smaller session * context size. The alternate cpaCySymSessionCtxGetDynamicSize() * function will return the smallest size needed to fit the * provided setup data parameters. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pSessionSetupData Pointer to session setup data which * contains parameters which are static * for a given cryptographic session such * as operation type, mechanisms, and keys * for cipher and/or hash operations. * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required * to hold the Session Context. * * @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_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * @see * CpaCySymSessionSetupData * cpaCySymInitSession() * cpaCySymSessionCtxGetDynamicSize() * cpaCySymPerformOp() * *****************************************************************************/ CpaStatus cpaCySymSessionCtxGetSize(const CpaInstanceHandle instanceHandle, const CpaCySymSessionSetupData *pSessionSetupData, Cpa32U *pSessionCtxSizeInBytes); /** ***************************************************************************** * @ingroup cpaCySym * Gets the minimum size required to store a session context. * * @description * This function is used by the client to determine the smallest size of * the memory it must allocate in order to store the session context. * This MUST be called before the client allocates the memory for the * session context and before the client calls the @ref cpaCySymInitSession * function. * * This function is an alternate to cpaCySymSessionGetSize(). * cpaCySymSessionCtxGetSize() will return a fixed size which is the * minimum memory size needed to support all possible setup data parameter * combinations. cpaCySymSessionCtxGetDynamicSize() will return the * minimum memory size needed to support the specific session setup * data parameters provided. This size may be different for different setup * data parameters. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pSessionSetupData Pointer to session setup data which * contains parameters which are static * for a given cryptographic session such * as operation type, mechanisms, and keys * for cipher and/or hash operations. * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required * to hold the Session Context. * * @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_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized via cpaCyStartInstance function. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * @see * CpaCySymSessionSetupData * cpaCySymInitSession() * cpaCySymSessionCtxGetSize() * cpaCySymPerformOp() * *****************************************************************************/ CpaStatus cpaCySymSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle, const CpaCySymSessionSetupData *pSessionSetupData, Cpa32U *pSessionCtxSizeInBytes); /** ***************************************************************************** * @ingroup cpaCySym * Initialize a session for symmetric cryptographic API. * * @description * This function is used by the client to initialize an asynchronous * completion callback function for the symmetric cryptographic * operations. Clients MAY register multiple callback functions using * this function. * The callback function is identified by the combination of userContext, * pSymCb and session context (sessionCtx). The session context is the * handle to the session and needs to be passed when processing calls. * Callbacks on completion of operations within a session are guaranteed * to be in the same order they were submitted in. * * @context * This is a synchronous function and it cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pSymCb Pointer to callback function to be * registered. Set to NULL if the * cpaCySymPerformOp function is required to * work in a synchronous manner. * @param[in] pSessionSetupData Pointer to session setup data which contains * parameters which are static for a given * cryptographic session such as operation * type, mechanisms, and keys for cipher and/or * hash operations. * @param[out] sessionCtx Pointer to the memory allocated by the * client to store the session context. This * will be initialized with this function. This * value needs to be passed to subsequent * processing calls. * * @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 * This is a synchronous function and has no completion callback * associated with it. * @see * CpaCySymSessionCtx, * CpaCySymCbFunc, * CpaCySymSessionSetupData, * cpaCySymRemoveSession(), * cpaCySymPerformOp() * *****************************************************************************/ CpaStatus cpaCySymInitSession(const CpaInstanceHandle instanceHandle, const CpaCySymCbFunc pSymCb, const CpaCySymSessionSetupData *pSessionSetupData, CpaCySymSessionCtx sessionCtx); /** ***************************************************************************** * @ingroup cpaCySym * Remove (delete) a symmetric cryptographic session. * * @description * This function will remove a previously initialized session context * and the installed callback handler function. Removal will fail if * outstanding calls still exist for the initialized session handle. * The client needs to retry the remove function at a later time. * The memory for the session context MUST not be freed until this call * has completed successfully. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in,out] pSessionCtx Session context to be removed. * * @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 * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * CpaCySymSessionCtx, * cpaCySymInitSession() * *****************************************************************************/ CpaStatus cpaCySymRemoveSession(const CpaInstanceHandle instanceHandle, CpaCySymSessionCtx pSessionCtx); /** ***************************************************************************** * @ingroup cpaCySym * Update a session. * * @description * This function is used to update certain parameters of a session, as * specified by the CpaCySymSessionUpdateData data structure. * * It can be used on sessions created with either the so-called * Traditional API (@ref cpaCySymInitSession) or the Data Plane API * (@ref cpaCySymDpInitSession). * * In order for this function to operate correctly, two criteria must * be met: * * - In the case of sessions created with the Traditional API, the * session must be stateless, i.e. the field partialsNotRequired of * the CpaCySymSessionSetupData data structure must be FALSE. * (Sessions created using the Data Plane API are always stateless.) * * - There must be no outstanding requests in flight for the session. * The application can call the function @ref cpaCySymSessionInUse * to test for this. * * Note that in the case of multi-threaded applications (which are * supported using the Traditional API only), this function may fail * even if a previous invocation of the function @ref * cpaCySymSessionInUse indicated that there were no outstanding * requests. * * @param[in] sessionCtx Identifies the session to be reset. * @param[in] pSessionUpdateData Pointer to session data which contains * the parameters to be updated. * * @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 * This is a synchronous function and has no completion callback * associated with it. *****************************************************************************/ CpaStatus cpaCySymUpdateSession(CpaCySymSessionCtx sessionCtx, const CpaCySymSessionUpdateData *pSessionUpdateData); /** ***************************************************************************** * @ingroup cpaCySym * Indicates whether there are outstanding requests on a given * session. * * @description * This function is used to test whether there are outstanding * requests in flight for a specified session. This may be used * before resetting session parameters using the function @ref * cpaCySymResetSession. See some additional notes on * multi-threaded applications described on that function. * * @param[in] sessionCtx Identifies the session to be reset. * @param[out] pSessionInUse Returns CPA_TRUE if there are * outstanding requests on the session, * or CPA_FALSE otherwise. *****************************************************************************/ CpaStatus cpaCySymSessionInUse(CpaCySymSessionCtx sessionCtx, CpaBoolean* pSessionInUse); /** ***************************************************************************** * @ingroup cpaCySym * Perform a symmetric cryptographic operation on an existing session. * * @description * Performs a cipher, hash or combined (cipher and hash) operation on * the source data buffer using supported symmetric key algorithms and * modes. * * This function maintains cryptographic state between calls for * partial cryptographic operations. If a partial cryptographic * operation is being performed, then on a per-session basis, the next * part of the multi-part message can be submitted prior to previous * parts being completed, the only limitation being that all parts * must be performed in sequential order. * * If for any reason a client wishes to terminate the partial packet * processing on the session (for example if a packet fragment was lost) * then the client MUST remove the session. * * When using partial packet processing with algorithm chaining, only * the cipher state is maintained between calls. The hash state is * not be maintained between calls. Instead the hash digest will be * generated/verified for each call. If both the cipher state and * hash state need to be maintained between calls, algorithm chaining * cannot be used. * The following restrictions apply to the length: * * - When performing block based operations on a partial packet * (excluding the final partial packet), the data that is to be * operated on MUST be a multiple of the block size of the algorithm * being used. This restriction only applies to the cipher state * when using partial packets with algorithm chaining. * * - The final block must not be of length zero (0) if the operation * being performed is the authentication algorithm @ref * CPA_CY_SYM_HASH_AES_XCBC. This is because this algorithm requires * that the final block be XORed with another value internally. * If the length is zero, then the return code @ref * CPA_STATUS_INVALID_PARAM will be returned. * * - The length of the final block must be greater than or equal to * 16 bytes when using the @ref CPA_CY_SYM_CIPHER_AES_XTS cipher * algorithm. * * Partial packet processing is supported only when the following * conditions are true: * * - The cipher, hash or authentication operation is "in place" (that is, * pDstBuffer == pSrcBuffer) * * - The cipher or hash algorithm is NOT one of Kasumi or SNOW3G * * - The cipher mode is NOT F8 mode. * * - The hash algorithm is NOT SHAKE * * - The cipher algorithm is not SM4 * * - The cipher algorithm is not CPA_CY_SYM_CIPHER_CHACHA and the hash * algorithm is not CPA_CY_SYM_HASH_POLY. * * - The cipher algorithm is not CPA_CY_SYM_CIPHER_AES_GCM and the hash * algorithm is not CPA_CY_SYM_HASH_AES_GCM. * * - The instance/implementation supports partial packets as one of * its capabilities (see @ref CpaCySymCapabilitiesInfo). * * The term "in-place" means that the result of the cryptographic * operation is written into the source buffer. The term "out-of-place" * means that the result of the cryptographic operation is written into * the destination buffer. To perform "in-place" processing, set the * pDstBuffer parameter to point at the same location as the pSrcBuffer * parameter. * * @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] pCallbackTag Opaque data that will be returned to the client * in the callback. * @param[in] pOpData Pointer to a structure containing request * parameters. The client code allocates the memory * for this structure. This component takes * ownership of the memory until it is returned in * the callback. * @param[in] pSrcBuffer The source buffer. The caller MUST allocate * the source buffer and populate it * with data. For optimum performance, the data * pointed to SHOULD be 8-byte aligned. For * block ciphers, the data passed in MUST be * a multiple of the relevant block size. * i.e. padding WILL NOT be applied to the data. * For optimum performance, the buffer should * only contain the data region that the * cryptographic operation(s) must be performed on. * Any additional data in the source buffer may be * copied to the destination buffer and this copy * may degrade performance. * @param[out] pDstBuffer The destination buffer. The caller MUST * allocate a sufficiently sized destination * buffer to hold the data output (including * the authentication tag in the case of CCM). * Furthermore, the destination buffer must be the * same size as the source buffer (i.e. the sum of * lengths of the buffers in the buffer list must * be the same). This effectively means that the * source buffer must in fact be big enough to hold * the output data, too. This is because, * for out-of-place processing, the data outside the * regions in the source buffer on which * cryptographic operations are performed are copied * into the destination buffer. To perform * "in-place" processing set the pDstBuffer * parameter in cpaCySymPerformOp function to point * at the same location as pSrcBuffer. For optimum * performance, the data pointed to SHOULD be * 8-byte aligned. * @param[out] pVerifyResult In synchronous mode, this parameter is returned * when the verifyDigest option is set in the * CpaCySymSessionSetupData structure. A value of * CPA_TRUE indicates that the compare succeeded. A * value of CPA_FALSE indicates that the compare * failed for an unspecified reason. * * @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 resource. * @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. * A Cryptographic session has been previously setup using the * @ref cpaCySymInitSession function call. * @post * None * * @note * When in asynchronous mode, a callback of type CpaCySymCbFunc is * generated in response to this function call. Any errors generated during * processing are reported as part of the callback status code. * * @see * CpaCySymOpData, * cpaCySymInitSession(), * cpaCySymRemoveSession() *****************************************************************************/ CpaStatus cpaCySymPerformOp(const CpaInstanceHandle instanceHandle, void *pCallbackTag, const CpaCySymOpData *pOpData, const CpaBufferList *pSrcBuffer, CpaBufferList *pDstBuffer, CpaBoolean *pVerifyResult); /** ***************************************************************************** * @ingroup cpaCySym * Query symmetric cryptographic statistics for a specific instance. * * @deprecated * As of v1.3 of the cryptographic API, this function has been * deprecated, replaced by @ref cpaCySymQueryStats64(). * * @description * This function will query a specific instance for statistics. The * user MUST allocate the CpaCySymStats structure and pass the * reference to that into this function call. This function will write * the statistic results into the passed in CpaCySymStats * 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 * Yes * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pSymStats 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, i.e. no asynchronous * callback will be generated. * @see * CpaCySymStats *****************************************************************************/ CpaStatus CPA_DEPRECATED cpaCySymQueryStats(const CpaInstanceHandle instanceHandle, struct _CpaCySymStats *pSymStats); /** ***************************************************************************** * @ingroup cpaCySym * Query symmetric cryptographic statistics (64-bit version) for a * specific instance. * * @description * This function will query a specific instance for statistics. The * user MUST allocate the CpaCySymStats64 structure and pass the * reference to that into this function call. This function will write * the statistic results into the passed in CpaCySymStats64 * 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 * Yes * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[out] pSymStats 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, i.e. no asynchronous * callback will be generated. * @see * CpaCySymStats64 *****************************************************************************/ CpaStatus cpaCySymQueryStats64(const CpaInstanceHandle instanceHandle, CpaCySymStats64 *pSymStats); /** ***************************************************************************** * @ingroup cpaCySym * Symmetric Capabilities Info * * @description * This structure contains the capabilities that vary across * implementations of the symmetric sub-API of the cryptographic API. * This structure is used in conjunction with @ref * cpaCySymQueryCapabilities() to determine the capabilities supported * by a particular API implementation. * * For example, to see if an implementation supports cipher * @ref CPA_CY_SYM_CIPHER_AES_CBC, use the code * * @code if (CPA_BITMAP_BIT_TEST(capInfo.ciphers, CPA_CY_SYM_CIPHER_AES_CBC)) { // algo is supported } else { // algo is not supported } * @endcode * * The client MUST allocate memory for this structure and any members * that require memory. 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 the function returns. *****************************************************************************/ typedef struct _CpaCySymCapabilitiesInfo { CPA_BITMAP(ciphers, CPA_CY_SYM_CIPHER_CAP_BITMAP_SIZE); /**< Bitmap representing which cipher algorithms (and modes) are * supported by the instance. * Bits can be tested using the macro @ref CPA_BITMAP_BIT_TEST. * The bit positions are those specified in the enumerated type * @ref CpaCySymCipherAlgorithm. */ CPA_BITMAP(hashes, CPA_CY_SYM_HASH_CAP_BITMAP_SIZE); /**< Bitmap representing which hash/authentication algorithms are * supported by the instance. * Bits can be tested using the macro @ref CPA_BITMAP_BIT_TEST. * The bit positions are those specified in the enumerated type * @ref CpaCySymHashAlgorithm. */ CpaBoolean partialPacketSupported; /**< CPA_TRUE if instance supports partial packets. * See @ref CpaCySymPacketType. */ } CpaCySymCapabilitiesInfo; /** ***************************************************************************** * @ingroup cpaCySym * Returns capabilities of the symmetric API group of a Cryptographic * API instance. * * @description * This function is used to determine which specific capabilities are * supported within the symmetric sub-group of the Cryptographic API. * * @context * The function shall not be called in an interrupt context. * @assumptions * None * @sideEffects * None * @blocking * This function is synchronous and blocking. * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Handle to an instance of this API. * @param[out] pCapInfo Pointer to capabilities info structure. * All fields in the structure * are populated by the API instance. * * @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_UNSUPPORTED Function is not supported. * * @pre * The instance has been initialized via the @ref cpaCyStartInstance * function. * @post * None *****************************************************************************/ CpaStatus cpaCySymQueryCapabilities(const CpaInstanceHandle instanceHandle, CpaCySymCapabilitiesInfo * pCapInfo); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_SYM_H */ diff --git a/sys/dev/qat/qat_api/include/lac/cpa_cy_sym_dp.h b/sys/dev/qat/qat_api/include/lac/cpa_cy_sym_dp.h index a023b2e6eb6a..24c1eaeeab4b 100644 --- a/sys/dev/qat/qat_api/include/lac/cpa_cy_sym_dp.h +++ b/sys/dev/qat/qat_api/include/lac/cpa_cy_sym_dp.h @@ -1,986 +1,953 @@ -/*************************************************************************** - * - * BSD LICENSE - * - * Copyright(c) 2007-2025 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. - * - * - ***************************************************************************/ +/* SPDX-License-Identifier: BSD-3-Clause */ +/* Copyright(c) 2007-2025 Intel Corporation */ /* ***************************************************************************** * Doxygen group definitions ****************************************************************************/ /** ***************************************************************************** * @file cpa_cy_sym_dp.h * * @defgroup cpaCySymDp Symmetric cryptographic Data Plane API * * @ingroup cpaCySym * * @description * These data structures and functions specify the Data Plane API * for symmetric cipher, hash, and combined cipher and hash * operations. * * This API is recommended for data plane applications, in which the * cost of offload - that is, the cycles consumed by the driver in * sending requests to the hardware, and processing responses - needs * to be minimized. In particular, use of this API is recommended * if the following constraints are acceptable to your application: * * - Thread safety is not guaranteed. Each software thread should * have access to its own unique instance (CpaInstanceHandle) to * avoid contention. * - Polling is used, rather than interrupts (which are expensive). * Implementations of this API will provide a function (not * defined as part of this API) to read responses from the hardware * response queue and dispatch callback functions, as specified on * this API. * - Buffers and buffer lists are passed using physical addresses, * to avoid virtual to physical address translation costs. * - For GCM and CCM modes of AES, when performing decryption and * verification, if verification fails, then the message buffer * will NOT be zeroed. (This is a consequence of using physical * addresses for the buffers.) * - The ability to enqueue one or more requests without submitting * them to the hardware allows for certain costs to be amortized * across multiple requests. * - Only asynchronous invocation is supported. * - There is no support for partial packets. * - Implementations may provide certain features as optional at * build time, such as atomic counters. * - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not * supported on this API. The specific handle should be obtained * using the instance discovery functions (@ref cpaCyGetNumInstances, * @ref cpaCyGetInstances). * * @note Performance Trade-Offs * Different implementations of this API may have different performance * trade-offs; please refer to the documentation for your implementation * for details. However, the following concepts informed the definition * of this API. * * The API distinguishes between enqueuing a request and actually * submitting that request to the cryptographic acceleration * engine to be performed. This allows multiple requests to be enqueued * (either individually or in batch), and then for all enqueued requests * to be submitted in a single operation. The rationale is that in some * (especially hardware-based) implementations, the submit operation * is expensive; for example, it may incur an MMIO instruction. The * API allows this cost to be amortized over a number of requests. The * precise number of such requests can be tuned for optimal * performance. * * Specifically: * * - The function @ref cpaCySymDpEnqueueOp allows one request to be * enqueued, and optionally for that request (and all previously * enqueued requests) to be submitted. * - The function @ref cpaCySymDpEnqueueOpBatch allows multiple * requests to be enqueued, and optionally for those requests (and all * previously enqueued requests) to be submitted. * - The function @ref cpaCySymDpPerformOpNow enqueues no requests, but * submits all previously enqueued requests. *****************************************************************************/ #ifndef CPA_CY_SYM_DP_H #define CPA_CY_SYM_DP_H #ifdef __cplusplus extern "C" { #endif #include "cpa_cy_common.h" #include "cpa_cy_sym.h" /** ***************************************************************************** * @ingroup cpaCySymDp * Cryptographic component symmetric session context handle for the * data plane API. * @description * Handle to a cryptographic data plane session context. The memory for * this handle is allocated by the client. The size of the memory that * the client needs to allocate is determined by a call to the @ref * cpaCySymDpSessionCtxGetSize or @ref cpaCySymDpSessionCtxGetDynamicSize * functions. The session context memory is initialized with a call to * the @ref cpaCySymInitSession function. * This memory MUST not be freed until a call to @ref * cpaCySymDpRemoveSession has completed successfully. * *****************************************************************************/ typedef void * CpaCySymDpSessionCtx; /** ***************************************************************************** * @ingroup cpaCySymDp * Operation Data for cryptographic data plane API. * * @description * This structure contains data relating to a request to perform * symmetric cryptographic processing on one or more data buffers. * * The physical memory to which this structure points needs to be * at least 8-byte aligned. * * All reserved fields SHOULD NOT be written or read by the * calling code. * * @see * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch ****************************************************************************/ typedef struct _CpaCySymDpOpData { Cpa64U reserved0; /**< Reserved for internal usage. */ Cpa32U cryptoStartSrcOffsetInBytes; /**< Starting point for cipher processing, specified as number of bytes * from start of data in the source buffer. The result of the cipher * operation will be written back into the buffer starting at this * location in the destination buffer. */ Cpa32U messageLenToCipherInBytes; /**< The message length, in bytes, of the source buffer on which the * cryptographic operation will be computed. This must be a multiple of * the block size if a block cipher is being used. This is also the * same as the result length. * * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value * should not include the length of the padding or the length of the * MAC; the driver will compute the actual number of bytes over which * the encryption will occur, which will include these values. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field * should be set to 0. * * @note On some implementations, this length may be limited to a 16-bit * value (65535 bytes). */ CpaPhysicalAddr iv; /**< Initialization Vector or Counter. Specifically, this is the * physical address of one of the following: * * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for * SNOW3G in UEA2 mode, this is the Initialization Vector (IV) * value. * - For ARC4, this is reserved for internal usage. * - For block ciphers in CTR mode, this is the counter. * - For GCM mode, this is either the IV (if the length is 96 bits) or J0 * (for other sizes), where J0 is as defined by NIST SP800-38D. * Regardless of the IV length, a full 16 bytes needs to be allocated. * - For CCM mode, the first byte is reserved, and the nonce should be * written starting at &pIv[1] (to allow space for the implementation * to write in the flags in the first byte). Note that a full 16 bytes * should be allocated, even though the ivLenInBytes field will have * a value less than this. * The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here. */ Cpa64U reserved1; /**< Reserved for internal usage. */ Cpa32U hashStartSrcOffsetInBytes; /**< Starting point for hash processing, specified as number of bytes * from start of packet in source buffer. * * @note For CCM and GCM modes of operation, this value in this field * is ignored, and the field is reserved for internal usage. * The fields @ref additionalAuthData and @ref pAdditionalAuthData * should be set instead. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field specifies the start of the AAD data in * the source buffer. */ Cpa32U messageLenToHashInBytes; /**< The message length, in bytes, of the source buffer that the hash * will be computed on. * * @note For CCM and GCM modes of operation, this value in this field * is ignored, and the field is reserved for internal usage. * The fields @ref additionalAuthData and @ref pAdditionalAuthData * should be set instead. * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field specifies the length of the AAD data in the * source buffer. * * @note On some implementations, this length may be limited to a 16-bit * value (65535 bytes). */ CpaPhysicalAddr additionalAuthData; /**< Physical address of the Additional Authenticated Data (AAD), * which is needed for authenticated cipher mechanisms (CCM and * GCM), and to the IV for SNOW3G authentication (@ref * CPA_CY_SYM_HASH_SNOW3G_UIA2). For other authentication * mechanisms, this value is ignored, and the field is reserved for * internal usage. * * The length of the data pointed to by this field is set up for * the session in the @ref CpaCySymHashAuthModeSetupData structure * as part of the @ref cpaCySymDpInitSession function call. This length * must not exceed 240 bytes. * If AAD is not used, this address must be set to zero. * * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM) and GCM (@ref * CPA_CY_SYM_HASH_AES_GCM), the caller should be setup as described in * the same way as the corresponding field, pAdditionalAuthData, on the * "traditional" API (see the @ref CpaCySymOpData). * * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of * operation, this field is not used and should be set to 0. Instead * the AAD data should be placed in the source buffer. * */ CpaPhysicalAddr digestResult; /**< If the digestIsAppended member of the @ref CpaCySymSessionSetupData * structure is NOT set then this is the physical address of the location * where the digest result should be inserted (in the case of digest * generation) or where the purported digest exists (in the case of digest * verification). * * At session registration time, the client specified the digest result * length with the digestResultLenInBytes member of the @ref * CpaCySymHashSetupData structure. The client must allocate at least * digestResultLenInBytes of physically contiguous memory at this location. * * For digest generation, the digest result will overwrite any data * at this location. * * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result" * read "authentication tag T". * * If the digestIsAppended member of the @ref CpaCySymSessionSetupData * structure is set then this value is ignored and the digest result * is understood to be in the destination buffer for digest generation, * and in the source buffer for digest verification. The location of the * digest result in this case is immediately following the region over * which the digest is computed. */ CpaInstanceHandle instanceHandle; /**< Instance to which the request is to be enqueued. * @note A callback function must have been registered on the instance * using @ref cpaCySymDpRegCbFunc. */ CpaCySymDpSessionCtx sessionCtx; /**< Session context specifying the cryptographic parameters for this * request. * @note The session must have been created using @ref * cpaCySymDpInitSession. */ Cpa32U ivLenInBytes; /**< Length of valid IV data pointed to by the pIv parameter. * * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for * SNOW3G in UEA2 mode, this is the length of the IV (which * must be the same as the block length of the cipher). * - For block ciphers in CTR mode, this is the length of the counter * (which must be the same as the block length of the cipher). * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which * case pIv points to J0. * - For CCM mode, this is the length of the nonce, which can be in the * range 7 to 13 inclusive. */ CpaPhysicalAddr srcBuffer; /**< Physical address of the source buffer on which to operate. * This is either: * * - The location of the data, of length srcBufferLen; or, * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then * srcBuffer contains the location where a @ref CpaPhysBufferList is * stored. In this case, the CpaPhysBufferList MUST be aligned * on an 8-byte boundary. * - For optimum performance, the buffer should only contain the data * region that the cryptographic operation(s) must be performed on. * Any additional data in the source buffer may be copied to the * destination buffer and this copy may degrade performance. */ Cpa32U srcBufferLen; /**< Length of source buffer, or @ref CPA_DP_BUFLIST. */ CpaPhysicalAddr dstBuffer; /**< Physical address of the destination buffer on which to operate. * This is either: * * - The location of the data, of length srcBufferLen; or, * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then * srcBuffer contains the location where a @ref CpaPhysBufferList is * stored. In this case, the CpaPhysBufferList MUST be aligned * on an 8-byte boundary. * * For "in-place" operation, the dstBuffer may be identical to the * srcBuffer. */ Cpa32U dstBufferLen; /**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */ CpaPhysicalAddr thisPhys; /**< Physical address of this data structure */ Cpa8U* pIv; /**< Pointer to (and therefore, the virtual address of) the IV field * above. * Needed here because the driver in some cases writes to this field, * in addition to sending it to the accelerator. */ Cpa8U *pAdditionalAuthData; /**< Pointer to (and therefore, the virtual address of) the * additionalAuthData field above. * Needed here because the driver in some cases writes to this field, * in addition to sending it to the accelerator. */ void* pCallbackTag; /**< Opaque data that will be returned to the client in the function * completion callback. * * This opaque data is not used by the implementation of the API, * but is simply returned as part of the asynchronous response. * It may be used to store information that might be useful when * processing the response later. */ } CpaCySymDpOpData; /** ***************************************************************************** * @ingroup cpaCySymDp * Definition of callback function for cryptographic data plane API. * * @description * This is the callback function prototype. The callback function is * registered by the application using the @ref cpaCySymDpRegCbFunc * function call, and called back on completion of asynchronous * requests made via calls to @ref cpaCySymDpEnqueueOp or @ref * cpaCySymDpEnqueueOpBatch. * * @context * This callback function can be executed in a context that DOES NOT * permit sleeping to occur. * @assumptions * None * @sideEffects * None * @reentrant * No * @threadSafe * No * * @param[in] pOpData Pointer to the CpaCySymDpOpData object which * was supplied as part of the original request. * @param[in] status Status of the operation. Valid values are * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and * CPA_STATUS_UNSUPPORTED. * @param[in] verifyResult This parameter is valid when the verifyDigest * option is set in the CpaCySymSessionSetupData * structure. A value of CPA_TRUE indicates that * the compare succeeded. A value of CPA_FALSE * indicates that the compare failed. * * @return * None * @pre * Component has been initialized. * Callback has been registered with @ref cpaCySymDpRegCbFunc. * @post * None * @note * None * @see * cpaCySymDpRegCbFunc *****************************************************************************/ typedef void (*CpaCySymDpCbFunc)(CpaCySymDpOpData *pOpData, CpaStatus status, CpaBoolean verifyResult); /** ***************************************************************************** * @ingroup cpaCySymDp * Registration of the operation completion callback function. * * @description * This function allows a completion callback function to be registered. * The registered callback function is invoked on completion of * asynchronous requests made via calls to @ref cpaCySymDpEnqueueOp * or @ref cpaCySymDpEnqueueOpBatch. * * If a callback function was previously registered, it is overwritten. * * @context * This is a synchronous function and it cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @reentrant * No * @threadSafe * No * * @param[in] instanceHandle Instance on which the callback function is to be * registered. * @param[in] pSymNewCb Callback function for this instance. * @retval CPA_STATUS_SUCCESS Function executed successfully. * @retval CPA_STATUS_FAIL Function failed. * @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 * None * @see * CpaCySymDpCbFunc *****************************************************************************/ CpaStatus cpaCySymDpRegCbFunc(const CpaInstanceHandle instanceHandle, const CpaCySymDpCbFunc pSymNewCb); /** ***************************************************************************** * @ingroup cpaCySymDp * Gets the size required to store a session context for the data plane * API. * * @description * This function is used by the client to determine the size of the memory * it must allocate in order to store the session context. This MUST be * called before the client allocates the memory for the session context * and before the client calls the @ref cpaCySymDpInitSession function. * * For a given implementation of this API, it is safe to assume that * cpaCySymDpSessionCtxGetSize() will always return the same size and that * the size will not be different for different setup data parameters. * However, it should be noted that the size may change: * (1) between different implementations of the API (e.g. between software * and hardware implementations or between different hardware * implementations) * (2) between different releases of the same API implementation. * * The size returned by this function is the smallest size needed to * support all possible combinations of setup data parameters. Some * setup data parameter combinations may fit within a smaller session * context size. The alternate cpaCySymDpSessionCtxGetDynamicSize() * function will return the smallest size needed to fit the * provided setup data parameters. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pSessionSetupData Pointer to session setup data which * contains parameters which are static * for a given cryptographic session such * as operation type, mechanisms, and keys * for cipher and/or hash operations. * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required * to hold the Session Context. * * @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_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * @see * CpaCySymSessionSetupData * cpaCySymDpSessionCtxGetDynamicSize() * cpaCySymDpInitSession() *****************************************************************************/ CpaStatus cpaCySymDpSessionCtxGetSize(const CpaInstanceHandle instanceHandle, const CpaCySymSessionSetupData *pSessionSetupData, Cpa32U *pSessionCtxSizeInBytes); /** ***************************************************************************** * @ingroup cpaCySymDp * Gets the minimum size required to store a session context for the data * plane API. * * @description * This function is used by the client to determine the smallest size of * the memory it must allocate in order to store the session context. * This MUST be called before the client allocates the memory for the * session context and before the client calls the * @ref cpaCySymDpInitSession function. * * This function is an alternate to cpaCySymDpSessionGetSize(). * cpaCySymDpSessionCtxGetSize() will return a fixed size which is the * minimum memory size needed to support all possible setup data parameter * combinations. cpaCySymDpSessionCtxGetDynamicSize() will return the * minimum memory size needed to support the specific session setup * data parameters provided. This size may be different for different setup * data parameters. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * Yes * * @param[in] instanceHandle Instance handle. * @param[in] pSessionSetupData Pointer to session setup data which * contains parameters which are static * for a given cryptographic session such * as operation type, mechanisms, and keys * for cipher and/or hash operations. * @param[out] pSessionCtxSizeInBytes The amount of memory in bytes required * to hold the Session Context. * * @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_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized. * @post * None * @note * This is a synchronous function and has no completion callback * associated with it. * @see * CpaCySymSessionSetupData * cpaCySymDpSessionCtxGetSize() * cpaCySymDpInitSession() *****************************************************************************/ CpaStatus cpaCySymDpSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle, const CpaCySymSessionSetupData *pSessionSetupData, Cpa32U *pSessionCtxSizeInBytes); /** ***************************************************************************** * @ingroup cpaCySymDp * Initialize a session for the symmetric cryptographic data plane API. * * @description * This function is used by the client to initialize an asynchronous * session context for symmetric cryptographic data plane operations. * The returned session context is the handle to the session and needs to * be passed when requesting cryptographic operations to be performed. * * Only sessions created using this function may be used when * invoking functions on this API * * The session can be removed using @ref cpaCySymDpRemoveSession. * * @context * This is a synchronous function and it cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] instanceHandle Instance to which the requests will be * submitted. * @param[in] pSessionSetupData Pointer to session setup data which * contains parameters that are static * for a given cryptographic session such * as operation type, algorithm, and keys * for cipher and/or hash operations. * @param[out] sessionCtx Pointer to the memory allocated by the * client to store the session context. This * memory must be physically contiguous, and * its length (in bytes) must be at least as * big as specified by a call to @ref * cpaCySymDpSessionCtxGetSize. This memory * will be initialized with this function. This * value needs to be passed to subsequent * processing calls. * * @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 * This is a synchronous function and has no completion callback * associated with it. * @see * cpaCySymDpSessionCtxGetSize, cpaCySymDpRemoveSession *****************************************************************************/ CpaStatus cpaCySymDpInitSession(CpaInstanceHandle instanceHandle, const CpaCySymSessionSetupData *pSessionSetupData, CpaCySymDpSessionCtx sessionCtx); /** ***************************************************************************** * @ingroup cpaCySymDp * Remove (delete) a symmetric cryptographic session for the data plane * API. * * @description * This function will remove a previously initialized session context * and the installed callback handler function. Removal will fail if * outstanding calls still exist for the initialized session handle. * The client needs to retry the remove function at a later time. * The memory for the session context MUST not be freed until this call * has completed successfully. * * @context * This is a synchronous function that cannot sleep. It can be * executed in a context that does not permit sleeping. * @assumptions * None * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] instanceHandle Instance handle. * @param[in,out] sessionCtx Session context to be removed. * * @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 * Note that this is a synchronous function and has no completion callback * associated with it. * * @see * CpaCySymDpSessionCtx, * cpaCySymDpInitSession() * *****************************************************************************/ CpaStatus cpaCySymDpRemoveSession(const CpaInstanceHandle instanceHandle, CpaCySymDpSessionCtx sessionCtx); /** ***************************************************************************** * @ingroup cpaCySymDp * Enqueue a single symmetric cryptographic request. * * @description * This function enqueues a single request to perform a cipher, * hash or combined (cipher and hash) operation. Optionally, the * request is also submitted to the cryptographic engine to be * performed. * * See note about performance trade-offs on the @ref cpaCySymDp API. * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. * Callbacks within a session are guaranteed to be in the same order * in which they were submitted. * * The following restrictions apply to the pOpData parameter: * * - The memory MUST be aligned on an 8-byte boundary. * - The structure MUST reside in physically contiguous memory. * - The reserved fields of the structure SHOULD NOT be written * or read by the calling code. * * @context * This function will not sleep, and hence can be executed in a context * that does not permit sleeping. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] pOpData Pointer to a structure containing the * request parameters. The client code allocates * the memory for this structure. This component * takes ownership of the memory until it is * returned in the callback, which was registered * on the instance via @ref cpaCySymDpRegCbFunc. * See the above Description for restrictions * that apply to this parameter. * @param[in] performOpNow Flag to specify whether the operation should be * performed immediately (CPA_TRUE), or simply * enqueued to be performed later (CPA_FALSE). * In the latter case, the request is submitted * to be performed either by calling this function * again with this flag set to CPA_TRUE, or by * invoking the function @ref * cpaCySymDpPerformOpNow. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The session identified by pOpData->sessionCtx was setup using * @ref cpaCySymDpInitSession. * The instance identified by pOpData->instanceHandle has had a * callback function registered via @ref cpaCySymDpRegCbFunc. * * @post * None * * @note * A callback of type @ref CpaCySymDpCbFunc is generated in response to * this function call. Any errors generated during processing are * reported as part of the callback status code. * * @see * cpaCySymDpInitSession, * cpaCySymDpPerformOpNow *****************************************************************************/ CpaStatus cpaCySymDpEnqueueOp(CpaCySymDpOpData *pOpData, const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaCySymDp * Enqueue multiple requests to the symmetric cryptographic data plane * API. * * @description * This function enqueues multiple requests to perform cipher, hash * or combined (cipher and hash) operations. * See note about performance trade-offs on the @ref cpaCySymDp API. * * The function is asynchronous; control is returned to the user once * the request has been submitted. On completion of the request, the * application may poll for responses, which will cause a callback * function (registered via @ref cpaCySymDpRegCbFunc) to be invoked. * Separate callbacks will be invoked for each request. * Callbacks within a session are guaranteed to be in the same order * in which they were submitted. * * The following restrictions apply to each element of the pOpData * array: * * - The memory MUST be aligned on an 8-byte boundary. * - The structure MUST reside in physically contiguous memory. * - The reserved fields of the structure SHOULD NOT be * written or read by the calling code. * * @context * This function will not sleep, and hence can be executed in a context * that does not permit sleeping. * * @assumptions * Client MUST allocate the request parameters to 8 byte alignment. * Reserved elements of the CpaCySymDpOpData structure MUST be 0. * The CpaCySymDpOpData structure MUST reside in physically * contiguous memory. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] numberRequests The number of requests in the array of * CpaCySymDpOpData structures. * @param[in] pOpData An array of pointers to CpaCySymDpOpData * structures. Each of the CpaCySymDpOpData * structure contains the request parameters for * that request. The client code allocates the * memory for this structure. This component takes * ownership of the memory until it is returned in * the callback, which was registered on the * instance via @ref cpaCySymDpRegCbFunc. * See the above Description for restrictions * that apply to this parameter. * @param[in] performOpNow Flag to specify whether the operation should be * performed immediately (CPA_TRUE), or simply * enqueued to be performed later (CPA_FALSE). * In the latter case, the request is submitted * to be performed either by calling this function * again with this flag set to CPA_TRUE, or by * invoking the function @ref * cpaCySymDpPerformOpNow. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The session identified by pOpData[i]->sessionCtx was setup using * @ref cpaCySymDpInitSession. * The instance identified by pOpData->instanceHandle[i] has had a * callback function registered via @ref cpaCySymDpRegCbFunc. * * @post * None * * @note * Multiple callbacks of type @ref CpaCySymDpCbFunc are generated in * response to this function call (one per request). Any errors * generated during processing are reported as part of the callback * status code. * * @see * cpaCySymDpInitSession, * cpaCySymDpEnqueueOp *****************************************************************************/ CpaStatus cpaCySymDpEnqueueOpBatch(const Cpa32U numberRequests, CpaCySymDpOpData *pOpData[], const CpaBoolean performOpNow); /** ***************************************************************************** * @ingroup cpaCySymDp * Submit any previously enqueued requests to be performed now on the * symmetric cryptographic data plane API. * * @description * If any requests/operations were enqueued via calls to @ref * cpaCySymDpEnqueueOp and/or @ref cpaCySymDpEnqueueOpBatch, but with * the flag performOpNow set to @ref CPA_FALSE, then these operations * will now be submitted to the accelerator to be performed. * * See note about performance trade-offs on the @ref cpaCySymDp API. * * @context * Will not sleep. It can be executed in a context that does not * permit sleeping. * * @sideEffects * None * @blocking * No * @reentrant * No * @threadSafe * No * * @param[in] instanceHandle Instance to which the requests will be * submitted. * * @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_RESTARTING API implementation is restarting. Resubmit * the request. * @retval CPA_STATUS_UNSUPPORTED Function is not supported. * * @pre * The component has been initialized. * A cryptographic session has been previously setup using the * @ref cpaCySymDpInitSession function call. * * @post * None * * @see * cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch *****************************************************************************/ CpaStatus cpaCySymDpPerformOpNow(CpaInstanceHandle instanceHandle); #ifdef __cplusplus } /* close the extern "C" { */ #endif #endif /* CPA_CY_SYM_DP_H */