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