1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /** 5 ***************************************************************************** 6 * @file lac_sym_alg_chain.h 7 * 8 * @defgroup LacAlgChain Algorithm Chaining 9 * 10 * @ingroup LacSym 11 * 12 * Interfaces exposed by the Algorithm Chaining Component 13 * 14 * @lld_start 15 * 16 * @lld_overview 17 * This is the LAC Algorithm-Chaining feature component. This component 18 * implements session registration and cleanup functions, and a perform 19 * function. Statistics are maintained to track requests issued and completed, 20 * errors incurred, and authentication verification failures. For each 21 * function the parameters supplied by the client are checked, and then the 22 * function proceeds if all the parameters are valid. This component also 23 * incorporates support for Authenticated-Encryption (CCM and GCM) which 24 * essentially comprises of a cipher operation and a hash operation combined. 25 * 26 * This component can combine a cipher operation with a hash operation or just 27 * simply create a hash only or cipher only operation and is called from the 28 * LAC Symmetric API component. In turn it calls the LAC Cipher, LAC Hash, and 29 * LAC Symmetric QAT components. The goal here is to duplicate as little code 30 * as possible from the Cipher and Hash components. 31 * 32 * The cipher and hash operations can be combined in either order, i.e. cipher 33 * first then hash or hash first then cipher. The client specifies this via 34 * the algChainOrder field in the session context. This ordering choice is 35 * stored as part of the session descriptor, so that it is known when a 36 * perform request is issued. In the case of Authenticated-Encryption, the 37 * ordering is an implicit part of the CCM or GCM protocol. 38 * 39 * When building a content descriptor, as part of session registration, this 40 * component asks the Cipher and Hash components to build their respective 41 * parts of the session descriptor. The key aspect here is to provide the 42 * correct offsets to the Cipher and Hash components for where in the content 43 * descriptor to write their Config and Hardware Setup blocks. Also the 44 * Config block in each case must specify the appropriate next slice. 45 * 46 * When building request parameters, as part of a perform operation, this 47 * component asks the Cipher and Hash components to build their respective 48 * parts of the request parameters block. Again the key aspect here is to 49 * provide the correct offsets to the Cipher and Hash components for where in 50 * the request parameters block to write their parameters. Also the request 51 * parameters block in each case must specify the appropriate next slice. 52 * 53 * Parameter checking for session registration and for operation perform is 54 * mostly delegated to the Cipher and Hash components. There are a few 55 * extra checks that this component must perform: check the algChainOrder 56 * parameter, ensure that CCM/GCM are specified for hash/cipher algorithms 57 * as appropriate, and ensure that requests are for full packets (partial 58 * packets are not supported for Algorithm-Chaining). 59 * 60 * The perform operation allocates a cookie to capture information required 61 * in the request callback. This cookie is then freed in the callback. 62 * 63 * @lld_dependencies 64 * - \ref LacCipher "Cipher" : For taking care of the cipher aspects of 65 * session registration and operation perform 66 * - \ref LacHash "Hash" : For taking care of the hash aspects of session 67 * registration and operation perform 68 * - \ref LacSymCommon "Symmetric Common" : statistics. 69 * - \ref LacSymQat "Symmetric QAT": To build the QAT request message, 70 * request param structure, and populate the content descriptor. Also 71 * for registering a callback function to process the QAT response. 72 * - \ref QatComms "QAT Comms" : For sending messages to the QAT, and for 73 * setting the response callback 74 * - \ref LacMem "Mem" : For memory allocation and freeing, virtual/physical 75 * address translation, and translating between scalar and pointer types 76 * - OSAL : For atomics and locking 77 * 78 * @lld_module_algorithms 79 * This component builds up a chain of slices at session init time 80 * and stores it in the session descriptor. This is used for building up the 81 * content descriptor at session init time and the request parameters structure 82 * in the perform operation. 83 * 84 * The offsets for the first slice are updated so that the second slice adds 85 * its configuration information after that of the first slice. The first 86 * slice also configures the next slice appropriately. 87 * 88 * This component is very much hard-coded to just support cipher+hash or 89 * hash+cipher. It should be quite possible to extend this idea to support 90 * an arbitrary chain of commands, by building up a command chain that can 91 * be traversed in order to build up the appropriate configuration for the 92 * QAT. This notion should be looked at in the future if other forms of 93 * Algorithm-Chaining are desired. 94 * 95 * @lld_process_context 96 * 97 * @lld_end 98 * 99 *****************************************************************************/ 100 101 /*****************************************************************************/ 102 103 #ifndef LAC_SYM_ALG_CHAIN_H 104 #define LAC_SYM_ALG_CHAIN_H 105 106 /* 107 ****************************************************************************** 108 * Include public/global header files 109 ****************************************************************************** 110 */ 111 112 #include "cpa.h" 113 #include "cpa_cy_sym.h" 114 #include "lac_session.h" 115 116 /* 117 ******************************************************************************* 118 * Include private header files 119 ******************************************************************************* 120 */ 121 122 /* Macro for checking if zero length buffer are supported 123 * only for cipher is AES-GCM and hash are AES-GCM/AES-GMAC */ 124 #define IS_ZERO_LENGTH_BUFFER_SUPPORTED(cipherAlgo, hashAlgo) \ 125 (CPA_CY_SYM_CIPHER_AES_GCM == cipherAlgo && \ 126 (CPA_CY_SYM_HASH_AES_GMAC == hashAlgo || \ 127 CPA_CY_SYM_HASH_AES_GCM == hashAlgo)) 128 129 /** 130 ******************************************************************************* 131 * @ingroup LacAlgChain 132 * This function registers a session for an Algorithm-Chaining operation. 133 * 134 * @description 135 * This function is called from the LAC session register API function for 136 * Algorithm-Chaining operations. It validates all input parameters. If 137 * an invalid parameter is passed, an error is returned to the calling 138 * function. If all parameters are valid an Algorithm-Chaining session is 139 * registered. 140 * 141 * @param[in] instanceHandle Instance Handle 142 * 143 * @param[in] pSessionCtx Pointer to session context which contains 144 * parameters which are static for a given 145 * cryptographic session such as operation type, 146 * mechanisms, and keys for cipher and/or digest 147 * operations. 148 * @param[out] pSessionDesc Pointer to session descriptor 149 * 150 * @retval CPA_STATUS_SUCCESS Function executed successfully. 151 * @retval CPA_STATUS_FAIL Function failed. 152 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 153 * @retval CPA_STATUS_RESOURCE Error related to system resources. 154 * 155 * @see cpaCySymInitSession() 156 * 157 *****************************************************************************/ 158 CpaStatus LacAlgChain_SessionInit(const CpaInstanceHandle instanceHandle, 159 const CpaCySymSessionSetupData *pSessionCtx, 160 lac_session_desc_t *pSessionDesc); 161 162 /** 163 ******************************************************************************* 164 * @ingroup LacAlgChain 165 * Data path function for the Algorithm-Chaining component 166 * 167 * @description 168 * This function gets called from cpaCySymPerformOp() which is the 169 * symmetric LAC API function. It is the data path function for the 170 * Algorithm-Chaining component. It does the parameter checking on the 171 * client supplied parameters and if the parameters are valid, the 172 * operation is performed and a request sent to the QAT, otherwise an 173 * error is returned to the client. 174 * 175 * @param[in] instanceHandle Instance Handle 176 * 177 * @param[in] pSessionDesc Pointer to session descriptor 178 * @param[in] pCallbackTag The application's context for this call 179 * @param[in] pOpData Pointer to a structure containing request 180 * parameters. The client code allocates the memory for 181 * this structure. This component takes ownership of 182 * the memory until it is returned in the callback. 183 * 184 * @param[in] pSrcBuffer Source Buffer List 185 * @param[out] pDstBuffer Destination Buffer List 186 * @param[out] pVerifyResult Verify Result 187 * 188 * @retval CPA_STATUS_SUCCESS Function executed successfully. 189 * @retval CPA_STATUS_FAIL Function failed. 190 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 191 * @retval CPA_STATUS_RESOURCE Error related to system resource. 192 * 193 * @see cpaCySymPerformOp() 194 * 195 *****************************************************************************/ 196 CpaStatus LacAlgChain_Perform(const CpaInstanceHandle instanceHandle, 197 lac_session_desc_t *pSessionDesc, 198 void *pCallbackTag, 199 const CpaCySymOpData *pOpData, 200 const CpaBufferList *pSrcBuffer, 201 CpaBufferList *pDstBuffer, 202 CpaBoolean *pVerifyResult); 203 204 /** 205 ******************************************************************************* 206 * @ingroup LacAlgChain 207 * This function is used to update cipher key, as specified in provided 208 * input. 209 * 210 * @description 211 * This function is called from the LAC session register API function for 212 * Algorithm-Chaining operations. It validates all input parameters. If 213 * an invalid parameter is passed, an error is returned to the calling 214 * function. If all parameters are valid an Algorithm-Chaining session is 215 * updated. 216 * 217 * @threadSafe 218 * No 219 * 220 * @param[in] pSessionDesc Pointer to session descriptor 221 * @param[in] pCipherKey Pointer to new cipher key. 222 * 223 * @retval CPA_STATUS_SUCCESS Function executed successfully. 224 * @retval CPA_STATUS_FAIL Function failed. 225 * @retval CPA_STATUS_RETRY Resubmit the request. 226 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 227 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 228 * 229 *****************************************************************************/ 230 CpaStatus LacAlgChain_SessionCipherKeyUpdate(lac_session_desc_t *pSessionDesc, 231 Cpa8U *pCipherKey); 232 233 /** 234 ******************************************************************************* 235 * @ingroup LacAlgChain 236 * This function is used to update authentication key, as specified in 237 * provided input. 238 * 239 * @description 240 * This function is called from the LAC session register API function for 241 * Algorithm-Chaining operations. It validates all input parameters. If 242 * an invalid parameter is passed, an error is returned to the calling 243 * function. If all parameters are valid an Algorithm-Chaining session is 244 * updated. 245 * 246 * @threadSafe 247 * No 248 * 249 * @param[in] pSessionDesc Pointer to session descriptor 250 * @param[in] pCipherKey Pointer to new authentication key. 251 * 252 * @retval CPA_STATUS_SUCCESS Function executed successfully. 253 * @retval CPA_STATUS_FAIL Function failed. 254 * @retval CPA_STATUS_RETRY Resubmit the request. 255 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 256 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 257 * 258 *****************************************************************************/ 259 CpaStatus LacAlgChain_SessionAuthKeyUpdate(lac_session_desc_t *pSessionDesc, 260 Cpa8U *pAuthKey); 261 262 /** 263 ******************************************************************************* 264 * @ingroup LacAlgChain 265 * This function is used to update AAD length as specified in provided 266 * input. 267 * 268 * @description 269 * This function is called from the LAC session register API function for 270 * Algorithm-Chaining operations. It validates all input parameters. If 271 * an invalid parameter is passed, an error is returned to the calling 272 * function. If all parameters are valid an Algorithm-Chaining session is 273 * updated. 274 * 275 * @threadSafe 276 * No 277 * 278 * @param[in] pSessionDesc Pointer to session descriptor 279 * @param[in] newAADLength New AAD length. 280 * 281 * @retval CPA_STATUS_SUCCESS Function executed successfully. 282 * @retval CPA_STATUS_FAIL Function failed. 283 * @retval CPA_STATUS_RETRY Resubmit the request. 284 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 285 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 286 * 287 *****************************************************************************/ 288 CpaStatus LacAlgChain_SessionAADUpdate(lac_session_desc_t *pSessionDesc, 289 Cpa32U newAADLength); 290 291 #endif /* LAC_SYM_ALG_CHAIN_H */ 292