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