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 *****************************************************************************/
63Cpa8U
64LacSymQat_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 *****************************************************************************/
80Cpa32U 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 *****************************************************************************/
115CpaStatus
116LacSymQat_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 *****************************************************************************/
145void 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 *****************************************************************************/
166void 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 *****************************************************************************/
182void 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 *****************************************************************************/
211void 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 *****************************************************************************/
236void 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 *****************************************************************************/
258void 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 *****************************************************************************/
293void 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