1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 /* $FreeBSD$ */ 4 5 /** 6 ***************************************************************************** 7 * @file lac_sym_qat_cipher.h 8 * 9 * @defgroup LacSymQat_Cipher Cipher QAT 10 * 11 * @ingroup LacSymQat 12 * 13 * external interfaces for populating QAT structures for cipher operations. 14 * 15 *****************************************************************************/ 16 17 /*****************************************************************************/ 18 19 #ifndef LAC_SYM_QAT_CIPHER_H 20 #define LAC_SYM_QAT_CIPHER_H 21 22 /* 23 ****************************************************************************** 24 * Include public/global header files 25 ****************************************************************************** 26 */ 27 28 #include "cpa_cy_sym.h" 29 #include "icp_qat_fw_la.h" 30 #include "lac_session.h" 31 #include "lac_sal_types_crypto.h" 32 33 /* 34 ************************************************************************** 35 * @ingroup LacSymQat_Cipher 36 * 37 * @description 38 * Defines for building the cipher request params cache 39 * 40 ************************************************************************** */ 41 42 #define LAC_SYM_QAT_CIPHER_NEXT_ID_BIT_OFFSET 24 43 #define LAC_SYM_QAT_CIPHER_CURR_ID_BIT_OFFSET 16 44 #define LAC_SYM_QAT_CIPHER_STATE_SIZE_BIT_OFFSET 8 45 #define LAC_SYM_QAT_CIPHER_GCM_SPC_OFFSET_IN_DRAM 9 46 #define LAC_SYM_QAT_CIPHER_CCM_SPC_OFFSET_IN_DRAM 8 47 #define LAC_SYM_QAT_CIPHER_CHACHA_SPC_OFFSET_IN_DRAM 2 48 #define LAC_SYM_QAT_CIPHER_SPC_STATE_SIZE 48 49 50 /** 51 ****************************************************************************** 52 * @ingroup LacSymQat_Cipher 53 * Retrieve the cipher block size in bytes for a given algorithm 54 * 55 * @description 56 * This function returns a hard-coded block size for the specific cipher 57 * algorithm 58 * 59 * @param[in] cipherAlgorithm Cipher algorithm for the current session 60 * 61 * @retval The block size, in bytes, for the given cipher algorithm 62 * 63 *****************************************************************************/ 64 Cpa8U 65 LacSymQat_CipherBlockSizeBytesGet(CpaCySymCipherAlgorithm cipherAlgorithm); 66 67 /** 68 ****************************************************************************** 69 * @ingroup LacSymQat_Cipher 70 * Retrieve the cipher IV/state size in bytes for a given algorithm 71 * 72 * @description 73 * This function returns a hard-coded IV/state size for the specific cipher 74 * algorithm 75 * 76 * @param[in] cipherAlgorithm Cipher algorithm for the current session 77 * 78 * @retval The IV/state size, in bytes, for the given cipher algorithm 79 * 80 *****************************************************************************/ 81 Cpa32U LacSymQat_CipherIvSizeBytesGet(CpaCySymCipherAlgorithm cipherAlgorithm); 82 83 /** 84 ****************************************************************************** 85 * @ingroup LacSymQat_Cipher 86 * Populate the cipher request params structure 87 * 88 * @description 89 * This function is passed a pointer to the 128B request block. 90 * (This memory must be allocated prior to calling this function). It 91 * populates: 92 * - the cipher fields of the req_params block in the request. No 93 * need to zero this first, all fields will be populated. 94 * - the corresponding CIPH_IV_FLD flag in the serv_specif_flags field 95 * of the common header. 96 * To do this it uses the parameters described below and the following 97 *fields from the request block which must be populated prior to calling this 98 *function: 99 * - cd_ctrl.cipher_state_sz 100 * - UPDATE_STATE flag in comn_hdr.serv_specif_flags 101 * 102 * 103 * @param[in] pReq Pointer to request block. 104 * * 105 * @param[in] cipherOffsetInBytes Offset to cipher data in user data buffer 106 * 107 * @param[in] cipherLenInBytes Length of cipher data in buffer 108 * 109 * @param[in] ivBufferPhysAddr Physical address of aligned IV/state 110 * buffer 111 * @param[in] pIvBufferVirt Virtual address of aligned IV/state 112 * buffer 113 * @retval void 114 * 115 *****************************************************************************/ 116 CpaStatus 117 LacSymQat_CipherRequestParamsPopulate(lac_session_desc_t *pSessionDesc, 118 icp_qat_fw_la_bulk_req_t *pReq, 119 Cpa32U cipherOffsetInBytes, 120 Cpa32U cipherLenInBytes, 121 Cpa64U ivBufferPhysAddr, 122 Cpa8U *pIvBufferVirt); 123 124 /** 125 ****************************************************************************** 126 * @ingroup LacSymQat_Cipher 127 * Derive initial ARC4 cipher state from a base key 128 * 129 * @description 130 * An initial state for an ARC4 cipher session is derived from the base 131 * key provided by the user, using the ARC4 Key Scheduling Algorithm (KSA) 132 * 133 * @param[in] pKey The base key provided by the user 134 * 135 * @param[in] keyLenInBytes The length of the base key provided. 136 * The range of valid values is 1-256 bytes 137 * 138 * @param[out] pArc4CipherState The initial state is written to this buffer, 139 * including i and j values, and 6 bytes of padding 140 * so 264 bytes must be allocated for this buffer 141 * by the caller 142 * 143 * @retval void 144 * 145 *****************************************************************************/ 146 void LacSymQat_CipherArc4StateInit(const Cpa8U *pKey, 147 Cpa32U keyLenInBytes, 148 Cpa8U *pArc4CipherState); 149 150 /** 151 ****************************************************************************** 152 * @ingroup LacSymQat_CipherXTSModeUpdateKeyLen 153 * Update the initial XTS key after the first partial has been received. 154 * 155 * @description 156 * For XTS mode using partial packets, after the first partial response 157 * has been received, the key length needs to be halved for subsequent 158 * partials. 159 * 160 * @param[in] pSessionDesc The session descriptor. 161 * 162 * @param[in] newKeySizeInBytes The new key size.. 163 * 164 * @retval void 165 * 166 *****************************************************************************/ 167 void LacSymQat_CipherXTSModeUpdateKeyLen(lac_session_desc_t *pSessionDesc, 168 Cpa32U newKeySizeInBytes); 169 170 /** 171 ****************************************************************************** 172 * @ingroup LacSymQat_Cipher 173 * LacSymQat_CipherCtrlBlockInitialize() 174 * 175 * @description 176 * intialize the cipher control block with all zeros 177 * 178 * @param[in] pMsg Pointer to the common request message 179 * 180 * @retval void 181 * 182 *****************************************************************************/ 183 void LacSymQat_CipherCtrlBlockInitialize(icp_qat_fw_la_bulk_req_t *pMsg); 184 185 /** 186 ****************************************************************************** 187 * @ingroup LacSymQat_Cipher 188 * LacSymQat_CipherCtrlBlockWrite() 189 * 190 * @description 191 * This function populates the cipher control block of the common request 192 * message 193 * 194 * @param[in] pMsg Pointer to the common request message 195 * 196 * @param[in] cipherAlgorithm Cipher Algorithm to be used 197 * 198 * @param[in] targetKeyLenInBytes cipher key length in bytes of selected 199 * algorithm 200 * 201 * @param[in] sliceType Cipher slice type to be used 202 * 203 * @param[out] nextSlice SliceID for next control block 204 * entry. This value is known only by 205 * the calling component 206 * 207 * @param[out] cipherCfgOffsetInQuadWord Offset into the config table in QW 208 * 209 * @retval void 210 * 211 *****************************************************************************/ 212 void LacSymQat_CipherCtrlBlockWrite(icp_qat_la_bulk_req_ftr_t *pMsg, 213 Cpa32U cipherAlgorithm, 214 Cpa32U targetKeyLenInBytes, 215 Cpa32U sliceType, 216 icp_qat_fw_slice_t nextSlice, 217 Cpa8U cipherCfgOffsetInQuadWord); 218 219 /** 220 ****************************************************************************** 221 * @ingroup LacSymQat_Cipher 222 * LacSymQat_CipherHwBlockPopulateCfgData() 223 * 224 * @description 225 * Populate the physical HW block with config data 226 * 227 * @param[in] pSession Pointer to the session data 228 * 229 * @param[in] pCipherHwBlock pointer to the hardware control block 230 * in the common message 231 * 232 * @param[in] pSizeInBytes 233 * 234 * @retval void 235 * 236 *****************************************************************************/ 237 void LacSymQat_CipherHwBlockPopulateCfgData(lac_session_desc_t *pSession, 238 const void *pCipherHwBlock, 239 Cpa32U *pSizeInBytes); 240 241 /** 242 ****************************************************************************** 243 * @ingroup LacSymQat_Cipher 244 * LacSymQat_CipherGetCfgData() 245 * 246 * @description 247 * setup the config data for cipher 248 * 249 * @param[in] pSession Pointer to the session data 250 * 251 * @param[in] pAlgorithm * 252 * @param[in] pMode 253 * @param[in] pDir 254 * @param[in] pKey_convert 255 * 256 * @retval void 257 * 258 *****************************************************************************/ 259 void LacSymQat_CipherGetCfgData(lac_session_desc_t *pSession, 260 icp_qat_hw_cipher_algo_t *pAlgorithm, 261 icp_qat_hw_cipher_mode_t *pMode, 262 icp_qat_hw_cipher_dir_t *pDir, 263 icp_qat_hw_cipher_convert_t *pKey_convert); 264 265 /** 266 ****************************************************************************** 267 * @ingroup LacSymQat_Cipher 268 * LacSymQat_CipherHwBlockPopulateKeySetup() 269 * 270 * @description 271 * populate the key setup data in the cipher hardware control block 272 * in the common request message 273 * 274 * param[in] pCipherSetupData Pointer to cipher setup data 275 * 276 * @param[in] targetKeyLenInBytes Target key length. If key length given 277 * in cipher setup data is less that this, 278 * the key will be "rounded up" to this 279 * target length by padding it with 0's. 280 * In normal no-padding case, the target 281 * key length MUST match the key length 282 * in the cipher setup data. 283 * 284 * @param[in] sliceType Cipher slice type to be used 285 * 286 * @param[in] pCipherHwBlock Pointer to the cipher hardware block 287 * 288 * @param[out] pCipherHwBlockSizeBytes Size in bytes of cipher setup block 289 * 290 * 291 * @retval void 292 * 293 *****************************************************************************/ 294 void LacSymQat_CipherHwBlockPopulateKeySetup( 295 lac_session_desc_t *pSessionDesc, 296 const CpaCySymCipherSetupData *pCipherSetupData, 297 Cpa32U targetKeyLenInBytes, 298 Cpa32U sliceType, 299 const void *pCipherHwBlock, 300 Cpa32U *pCipherHwBlockSizeBytes); 301 302 #endif /* LAC_SYM_QAT_CIPHER_H */ 303