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