1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 4 /** 5 *************************************************************************** 6 * @file lac_sym.h 7 * 8 * @defgroup LacSym Symmetric 9 * 10 * @ingroup Lac 11 * 12 * Symmetric component includes cipher, Hash, chained cipher & hash, 13 * authenticated encryption and key generation. 14 * 15 * @lld_start 16 * @lld_overview 17 * 18 * The symmetric component demuliplexes the following crypto operations to 19 * the appropriate sub-components: cipher, hash, algorithm chaining and 20 * authentication encryption. It is a common layer between the above 21 * mentioned components where common resources are allocated and paramater 22 * checks are done. The operation specific resource allocation and parameter 23 * checks are done in the sub-component itself. 24 * 25 * The symmetric component demultiplexes the session register/deregister 26 * and perform functions to the appropriate subcomponents. 27 * 28 * @lld_dependencies 29 * - \ref LacSymPartial "Partial Packet Code": This code manages the partial 30 * packet state for a session. 31 * - \ref LacBufferDesc "Common Buffer Code" : This code traverses a buffer 32 * chain to ensure it is valid. 33 * - \ref LacSymStats "Statistics": Manages statistics for symmetric 34 * - \ref LacSymQat "Symmetric QAT": The symmetric qat component is 35 * initialiased by the symmetric component. 36 * - \ref LacCipher "Cipher" : demultiplex cipher opertions to this component. 37 * - \ref LacHash "Hash" : demultiplex hash opertions to this component. 38 * to this component. 39 * - \ref LacAlgChain "Algorithm Chaining": The algorithm chaining component 40 * - OSAL : Memory allocation, Mutex's, atomics 41 * 42 * @lld_initialisation 43 * This component is initialied during the LAC initialisation sequence. It 44 * initialises the session table, statistics, symmetric QAT, initialises the 45 * hash definitions lookup table, the hash alg supported lookup table and 46 * registers a callback function with the symmetric response handler to process 47 * response messages for Cipher, Hash and Algorithm-Chaining requests. 48 * 49 * @lld_module_algorithms 50 * 51 * @lld_process_context 52 * Refer to \ref LacHash "Hash" and \ref LacCipher "Cipher" for sequence 53 * diagrams from the symmetric component through the sub components. 54 * 55 * @lld_end 56 * 57 ***************************************************************************/ 58 59 /***************************************************************************/ 60 61 #ifndef LAC_SYM_H 62 #define LAC_SYM_H 63 64 #include "cpa.h" 65 #include "cpa_cy_sym.h" 66 #include "cpa_cy_sym_dp.h" 67 #include "lac_common.h" 68 #include "lac_mem_pools.h" 69 #include "lac_sym_cipher_defs.h" 70 #include "icp_qat_fw_la.h" 71 72 #define LAC_SYM_KEY_TLS_PREFIX_SIZE 128 73 /**< Hash Prefix size in bytes for TLS (128 = MAX = SHA2 (384, 512)*/ 74 75 #define LAC_SYM_OPTIMISED_CD_SIZE 64 76 /**< The size of the optimised content desc in DRAM*/ 77 78 #define LAC_SYM_KEY_MAX_HASH_STATE_BUFFER (LAC_SYM_KEY_TLS_PREFIX_SIZE * 2) 79 /**< hash state prefix buffer structure that holds the maximum sized secret */ 80 81 #define LAC_SYM_HASH_BUFFER_LEN 64 82 /**< Buffer length to hold 16 byte MD5 key and 20 byte SHA1 key */ 83 84 /* The ARC4 key will not be stored in the content descriptor so we only need to 85 * reserve enough space for the next biggest cipher setup block. 86 * Kasumi needs to store 2 keys and to have the size of 2 blocks for fw*/ 87 #define LAC_SYM_QAT_MAX_CIPHER_SETUP_BLK_SZ \ 88 (sizeof(icp_qat_hw_cipher_config_t) + 2 * ICP_QAT_HW_KASUMI_KEY_SZ + \ 89 2 * ICP_QAT_HW_KASUMI_BLK_SZ) 90 /**< @ingroup LacSymQat 91 * Maximum size for the cipher setup block of the content descriptor */ 92 93 #define LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ sizeof(icp_qat_hw_auth_algo_blk_t) 94 /**< @ingroup LacSymQat 95 * Maximum size for the hash setup block of the content descriptor */ 96 97 #define LAC_SYM_QAT_CONTENT_DESC_MAX_SIZE \ 98 LAC_ALIGN_POW2_ROUNDUP(LAC_SYM_QAT_MAX_CIPHER_SETUP_BLK_SZ + \ 99 LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ, \ 100 (1 << LAC_64BYTE_ALIGNMENT_SHIFT)) 101 /**< @ingroup LacSymQat 102 * Maximum size of content descriptor. This is incremented to the next multiple 103 * of 64 so that it can be 64 byte aligned */ 104 105 #define LAC_SYM_QAT_API_ALIGN_COOKIE_OFFSET \ 106 (offsetof(CpaCySymDpOpData, instanceHandle)) 107 /**< @ingroup LacSymQat 108 * Size which needs to be reserved before the instanceHandle field of 109 * lac_sym_bulk_cookie_s to align it to the correspondent instanceHandle 110 * in CpaCySymDpOpData */ 111 112 #define LAC_SIZE_OF_CACHE_HDR_IN_LW 6 113 /**< Size of Header part of reqCache/shramReqCache */ 114 115 #define LAC_SIZE_OF_CACHE_MID_IN_LW 2 116 /**< Size of Mid part (LW14/15) of reqCache/shramReqCache */ 117 118 #define LAC_SIZE_OF_CACHE_FTR_IN_LW 6 119 /**< Size of Footer part of reqCache/shramReqCache */ 120 121 #define LAC_SIZE_OF_CACHE_TO_CLEAR_IN_LW 20 122 /**< Size of dummy reqCache/shramReqCache to clear */ 123 124 #define LAC_START_OF_CACHE_MID_IN_LW 14 125 /**< Starting LW of reqCache/shramReqCache Mid */ 126 127 #define LAC_START_OF_CACHE_FTR_IN_LW 26 128 /**< Starting LW of reqCache/shramReqCache Footer */ 129 130 /** 131 ******************************************************************************* 132 * @ingroup LacSym 133 * Symmetric cookie 134 * 135 * @description 136 * This cookie stores information for a particular symmetric perform op. 137 * This includes the request params, re-aligned Cipher IV, the request 138 * message sent to the QAT engine, and various user-supplied parameters 139 * for the operation which will be needed in our callback function. 140 * A pointer to this cookie is stored in the opaque data field of the QAT 141 * message so that it can be accessed in the asynchronous callback. 142 * Cookies for multiple operations on a given session can be linked 143 * together to allow queuing of requests using the pNext field. 144 * 145 * The parameters are placed in order to match the CpaCySymDpOpData 146 *structure 147 *****************************************************************************/ 148 typedef struct lac_sym_bulk_cookie_s { 149 150 /* CpaCySymDpOpData struct so need to keep this here for correct 151 * alignment*/ 152 Cpa8U reserved[LAC_SYM_QAT_API_ALIGN_COOKIE_OFFSET]; 153 /** NOTE: Field must be correctly aligned in memory for access by QAT 154 * engine 155 */ 156 CpaInstanceHandle instanceHandle; 157 /**< Instance handle for the operation */ 158 CpaCySymSessionCtx sessionCtx; 159 /**< Session context */ 160 void *pCallbackTag; 161 /**< correlator supplied by the client */ 162 icp_qat_fw_la_bulk_req_t qatMsg; 163 /**< QAT request message */ 164 const CpaCySymOpData *pOpData; 165 /**< pointer to the op data structure that the user supplied in the 166 * perform 167 * operation. The op data is modified in the process callback function 168 * and the pointer is returned to the user in their callback function */ 169 CpaBoolean updateSessionIvOnSend; 170 /**< Boolean flag to indicate if the session cipher IV buffer should be 171 * updated prior to sending the request */ 172 CpaBoolean updateUserIvOnRecieve; 173 /**< Boolean flag to indicate if the user's cipher IV buffer should be 174 * updated after receiving the response from the QAT */ 175 CpaBoolean updateKeySizeOnRecieve; 176 /**< Boolean flag to indicate if the cipher key size should be 177 * updated after receiving the response from the QAT */ 178 CpaBufferList *pDstBuffer; 179 /**< Pointer to destination buffer to hold the data output */ 180 struct lac_sym_bulk_cookie_s *pNext; 181 /**< Pointer to next node in linked list (if request is queued) */ 182 } lac_sym_bulk_cookie_t; 183 184 /** 185 ******************************************************************************* 186 * @ingroup LacSymKey 187 * symmetric Key cookie 188 * @description 189 * This cookie stores information for a particular keygen perform op. 190 * This includes a hash content descriptor, request params, hash state 191 * buffer, and various user-supplied parameters for the operation which 192 * will be needed in our callback function. 193 * A pointer to this cookie is stored in the opaque data field of the QAT 194 * message so that it can be accessed in the asynchronous callback. 195 *****************************************************************************/ 196 typedef struct lac_sym_key_cookie_s { 197 CpaInstanceHandle instanceHandle; 198 /**< QAT device id supplied by the client */ 199 void *pCallbackTag; 200 /**< Mechanism used. TLS, SSL or MGF */ 201 Cpa8U contentDesc[LAC_SYM_QAT_MAX_HASH_SETUP_BLK_SZ]; 202 /**< Content descriptor. 203 **< NOTE: Field must be correctly aligned in memory for access by QAT 204 * engine */ 205 union { 206 icp_qat_fw_la_ssl_key_material_input_t sslKeyInput; 207 /**< SSL key material input structure */ 208 icp_qat_fw_la_tls_key_material_input_t tlsKeyInput; 209 /**< TLS key material input structure */ 210 icp_qat_fw_la_hkdf_key_material_input_t tlsHKDFKeyInput; 211 /**< TLS HHKDF key material input structure */ 212 } u; 213 /**< NOTE: Field must be correctly aligned in memory for access by QAT 214 * engine */ 215 Cpa8U hashStateBuffer[LAC_SYM_KEY_MAX_HASH_STATE_BUFFER]; 216 /**< hash state prefix buffer 217 * NOTE: Field must be correctly aligned in memory for access by QAT 218 * engine 219 */ 220 CpaCyGenFlatBufCbFunc pKeyGenCb; 221 /**< callback function supplied by the client */ 222 void *pKeyGenOpData; 223 /**< pointer to the (SSL/TLS) or MGF op data structure that the user 224 * supplied in the perform operation */ 225 CpaFlatBuffer *pKeyGenOutputData; 226 /**< Output data pointer supplied by the client */ 227 Cpa8U hashKeyBuffer[LAC_SYM_HASH_BUFFER_LEN]; 228 /**< 36 byte buffer to store MD5 key and SHA1 key */ 229 } lac_sym_key_cookie_t; 230 231 /** 232 ******************************************************************************* 233 * @ingroup LacSymNrbg 234 * symmetric NRBG cookie 235 * @description 236 * This cookie stores information for a particular NRBG operation. 237 * This includes various user-supplied parameters for the operation which 238 * will be needed in our callback function. 239 * A pointer to this cookie is stored in the opaque data field of the QAT 240 * message so that it can be accessed in the asynchronous callback. 241 *****************************************************************************/ 242 typedef struct lac_sym_nrbg_cookie_s { 243 CpaInstanceHandle instanceHandle; 244 /**< QAT device id supplied by the client */ 245 void *pCallbackTag; 246 /**< Opaque data supplied by the client */ 247 icp_qat_fw_la_trng_test_result_t trngHTResult; 248 /**< TRNG health test result 249 **< NOTE: Field must be correctly aligned in memory for access by QAT 250 * engine */ 251 icp_qat_fw_la_trng_req_t trngReq; 252 /**< TRNG request message */ 253 CpaCyGenFlatBufCbFunc pCb; 254 /**< Callback function supplied by the client */ 255 void *pOpData; 256 /**< Op data pointer supplied by the client */ 257 CpaFlatBuffer *pOutputData; 258 /**< Output data pointer supplied by the client */ 259 } lac_sym_nrbg_cookie_t; 260 261 /** 262 ******************************************************************************* 263 * @ingroup LacSym 264 * symmetric cookie 265 * @description 266 * used to determine the amount of memory to allocate for the symmetric 267 * cookie pool. As symmetric, random and key generation shared the same 268 * pool 269 *****************************************************************************/ 270 typedef struct lac_sym_cookie_s { 271 union { 272 lac_sym_bulk_cookie_t bulkCookie; 273 /**< symmetric bulk cookie */ 274 lac_sym_key_cookie_t keyCookie; 275 /**< symmetric key cookie */ 276 lac_sym_nrbg_cookie_t nrbgCookie; 277 /**< symmetric NRBG cookie */ 278 } u; 279 Cpa64U keyContentDescPhyAddr; 280 Cpa64U keyHashStateBufferPhyAddr; 281 Cpa64U keySslKeyInputPhyAddr; 282 Cpa64U keyTlsKeyInputPhyAddr; 283 } lac_sym_cookie_t; 284 285 typedef struct icp_qat_la_auth_req_params_s { 286 /** equivalent of LW26 of icp_qat_fw_la_auth_req_params_s */ 287 union { 288 uint8_t inner_prefix_sz; 289 /**< Size in bytes of the inner prefix data */ 290 291 uint8_t aad_sz; 292 /**< Size in bytes of padded AAD data to prefix to the packet 293 * for CCM 294 * or GCM processing */ 295 } u2; 296 297 uint8_t resrvd1; 298 /**< reserved */ 299 300 uint8_t hash_state_sz; 301 /**< Number of quad words of inner and outer hash prefix data to process 302 * Maximum size is 240 */ 303 304 uint8_t auth_res_sz; 305 /**< Size in bytes of the authentication result */ 306 } icp_qat_la_auth_req_params_t; 307 308 /* Header (LW's 0 - 5) of struct icp_qat_fw_la_bulk_req_s */ 309 typedef struct icp_qat_la_bulk_req_hdr_s { 310 /**< LWs 0-1 */ 311 icp_qat_fw_comn_req_hdr_t comn_hdr; 312 /**< Common request header - for Service Command Id, 313 * use service-specific Crypto Command Id. 314 * Service Specific Flags - use Symmetric Crypto Command Flags 315 * (all of cipher, auth, SSL3, TLS and MGF, 316 * excluding TRNG - field unused) */ 317 318 /**< LWs 2-5 */ 319 icp_qat_fw_comn_req_hdr_cd_pars_t cd_pars; 320 /**< Common Request content descriptor field which points either to a 321 * content descriptor 322 * parameter block or contains the service-specific data itself. */ 323 } icp_qat_la_bulk_req_hdr_t; 324 325 /** Footer (LW's 26 - 31) of struct icp_qat_fw_la_bulk_req_s */ 326 typedef struct icp_qat_la_bulk_req_ftr_s { 327 /**< LW 0 - equivalent to LW26 of icp_qat_fw_la_bulk_req_t */ 328 icp_qat_la_auth_req_params_t serv_specif_rqpars; 329 /**< Common request service-specific parameter field */ 330 331 /**< LW's 1-5, equivalent to LWs 27-31 of icp_qat_fw_la_bulk_req_s */ 332 icp_qat_fw_comn_req_cd_ctrl_t cd_ctrl; 333 /**< Common request content descriptor control block - 334 * this field is service-specific */ 335 } icp_qat_la_bulk_req_ftr_t; 336 337 /** 338 *** 339 ******************************************************************************* 340 * @ingroup LacSym 341 * Compile time check of lac_sym_bulk_cookie_t 342 * 343 * @description 344 * Performs a compile time check of lac_sym_bulk_cookie_t to ensure IA 345 * assumptions are valid. 346 * 347 *****************************************************************************/ 348 void LacSym_CompileTimeAssertions(void); 349 350 void LacDp_WriteRingMsgFull(CpaCySymDpOpData *pRequest, 351 icp_qat_fw_la_bulk_req_t *pCurrentQatMsg); 352 void LacDp_WriteRingMsgOpt(CpaCySymDpOpData *pRequest, 353 icp_qat_fw_la_bulk_req_t *pCurrentQatMsg); 354 355 #endif /* LAC_SYM_H */ 356