1 /*
2  * Copyright 2018-2021 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 #ifndef FSL_SSCP_MU_H
8 #define FSL_SSCP_MU_H
9 
10 #include "fsl_sscp.h"
11 #include "fsl_elemu.h"
12 
13 /*!
14 @defgroup sscp_mu SSCP over MU
15 @details This section describes definition of the messages for the MU to invoke services
16 and MU implementation specific functions to initialize SSCP MU link, deinitialize SSCP MU link
17 and MU invoke command.
18 @ingroup sscp
19 
20 # MU commands
21 
22 ## Symmetric cipher
23 
24 ### Symmetric cipher in one go
25 
26 @copydetails sss_cipher_one_go
27 
28 <table width="60%" class="markdownTable">
29 <tr class="markdownTableHead">
30 <th class="markdownTableHeadNone" width="30%"> Symmetric Cipher One Go <th class="markdownTableHeadNone" width="10%"> TX
31 <th class="markdownTableHeadNone" width="60%"> MU TXn register value
32 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_SymmetricCipherOneGo
33 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefInput, MemrefOutput
34 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_symmetric
35 <tr><td> word        <td> 3  <td> Pointer to iv
36 <tr><td> word        <td> 4  <td> ivLen
37 <tr><td> word        <td> 5  <td> Pointer to srcData
38 <tr><td> word        <td> 6  <td> dataLen
39 <tr><td> word        <td> 7  <td> Pointer to destData
40 <tr><td> word        <td> 8  <td> Pointer to dataLen
41 </table>
42 
43 ### Symmetric AES in counter mode
44 
45 @copydetails sss_cipher_crypt_ctr
46 
47 <table width="60%" class="markdownTable">
48 <tr class="markdownTableHead">
49 <th class="markdownTableHeadNone" width="30%"> AES in Counter Mode <th class="markdownTableHeadNone" width="10%"> TX <th
50 class="markdownTableHeadNone" width="60%"> MU TXn register value
51 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_SymmetricCryptCtr
52 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefOutput, MemrefInOut, MemrefInOut, MemrefInOut
53 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_symmetric
54 <tr><td> word        <td> 3  <td> Pointer to input data buffer
55 <tr><td> word        <td> 4  <td> Length of the input data buffer in bytes
56 <tr><td> word        <td> 5  <td> Pointer to output data buffer
57 <tr><td> word        <td> 6  <td> Pointer to uint32_t with length of the output data buffer in bytes
58 <tr><td> word        <td> 7  <td> Pointer to Initial Counter Block
59 <tr><td> word        <td> 8  <td> Length of the Initial Counter Block in bytes
60 <tr><td> word        <td> 9  <td> Pointer to Last Encrypted Counter Block
61 <tr><td> word        <td> 10 <td> Length of the Last Encrypted Counter Block in bytes
62 <tr><td> word        <td> 11 <td> Pointer to uint32_t specifying number of bytes left unused in the Last Encrypted
63 Counter Block
64 <tr><td> word        <td> 12 <td> sizeof(uint32_t)
65 </table>
66 
67 ### Authenticated encryption with additional data
68 
69 @copydetails sss_aead_one_go
70 
71 <table width="60%" class="markdownTable">
72 <tr class="markdownTableHead">
73 <th class="markdownTableHeadNone" width="30%"> Authenticated Encryption with Additional Data <th
74 class="markdownTableHeadNone" width="10%"> TX  <th
75 class="markdownTableHeadNone" width="60%"> MU TXn register value
76 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_AeadOneGo
77 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefOutput, MemrefOutput, MemrefInput, MemrefInput,
78 MemrefOutput
79 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_aead
80 <tr><td> word        <td> 3  <td> Pointer to input data buffer
81 <tr><td> word        <td> 4  <td> Length of the input data buffer in bytes
82 <tr><td> word        <td> 5  <td> Pointer to output data buffer
83 <tr><td> word        <td> 6  <td> Pointer to uint32_t with length of the output data buffer in bytes
84 <tr><td> word        <td> 7  <td> Pointer to nonce buffer
85 <tr><td> word        <td> 8  <td> Length of the nonce buffer in bytes
86 <tr><td> word        <td> 9  <td> Pointer to aad buffer
87 <tr><td> word        <td> 10 <td> Length of the aad buffer in bytes
88 <tr><td> word        <td> 11 <td> Pointer to tag buffer
89 <tr><td> word        <td> 12 <td> Pointer to uint32_t with length of the tag buffer in bytes
90 </table>
91 
92 ## Digest
93 
94 ### Message digest in one go
95 
96 @copydetails sss_digest_one_go
97 
98 <table width="60%" class="markdownTable">
99 <tr class="markdownTableHead">
100 <th class="markdownTableHeadNone" width="30%"> Digest One Go <th class="markdownTableHeadNone" width="10%"> TX  <th
101 class="markdownTableHeadNone" width="60%"> MU TXn register value
102 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_DigestOneGo
103 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefOutput
104 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_digest
105 <tr><td> word        <td> 3  <td> Pointer to message
106 <tr><td> word        <td> 4  <td> messageLen
107 <tr><td> word        <td> 5  <td> Pointer to digest
108 <tr><td> word        <td> 6  <td> Pointer to digestLen
109 </table>
110 
111 ### Message digest init
112 
113 @copydetails sss_digest_init
114 
115 <table width="60%" class="markdownTable">
116 <tr class="markdownTableHead">
117 <th class="markdownTableHeadNone" width="30%"> Digest Init <th class="markdownTableHeadNone" width="10%"> TX  <th
118 class="markdownTableHeadNone" width="60%"> MU TXn register value
119 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_DigestInit
120 <tr><td> paramTypes  <td> 1  <td> Context
121 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_digest
122 </table>
123 
124 ### Message digest update
125 
126 @copydetails sss_digest_update
127 
128 <table width="60%" class="markdownTable">
129 <tr class="markdownTableHead">
130 <th class="markdownTableHeadNone" width="30%"> Digest Update <th class="markdownTableHeadNone" width="10%"> TX  <th
131 class="markdownTableHeadNone" width="60%"> MU TXn register value
132 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_DigestUpdate
133 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput
134 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_digest
135 <tr><td> word        <td> 3  <td> Pointer to message
136 <tr><td> word        <td> 4  <td> messageLen
137 </table>
138 
139 ### Message digest finish
140 
141 @copydetails sss_digest_finish
142 
143 <table width="60%" class="markdownTable">
144 <tr class="markdownTableHead">
145 <th class="markdownTableHeadNone" width="30%"> Digest Finish <th class="markdownTableHeadNone" width="10%"> TX  <th
146 class="markdownTableHeadNone" width="60%"> MU TXn register value
147 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_DigestFinish
148 <tr><td> paramTypes  <td> 1  <td> Context, MemrefOutput
149 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_digest
150 <tr><td> word        <td> 3  <td> Pointer to digest
151 <tr><td> word        <td> 4  <td> Pointer to digestLen
152 </table>
153 
154 ## Mac
155 
156 ### Message authentication code (MAC) in one go
157 
158 @copydetails sss_mac_one_go
159 
160 <table width="60%" class="markdownTable">
161 <tr class="markdownTableHead">
162 <th class="markdownTableHeadNone" width="30%"> Mac One Go <th class="markdownTableHeadNone" width="10%"> TX  <th
163 class="markdownTableHeadNone" width="60%"> MU TXn register value
164 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_MacOneGo
165 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefOutput
166 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_mac
167 <tr><td> word        <td> 3  <td> Pointer to message
168 <tr><td> word        <td> 4  <td> messageLen
169 <tr><td> word        <td> 5  <td> Pointer to mac
170 <tr><td> word        <td> 6  <td> Pointer to macLen
171 </table>
172 
173 ### Message mac init
174 
175 @copydetails sss_mac_init
176 
177 <table width="60%" class="markdownTable">
178 <tr class="markdownTableHead">
179 <th class="markdownTableHeadNone" width="30%"> Mac Init <th class="markdownTableHeadNone" width="10%"> TX  <th
180 class="markdownTableHeadNone" width="60%"> MU TXn register value
181 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_MacInit
182 <tr><td> paramTypes  <td> 1  <td> Context
183 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_mac
184 </table>
185 
186 ### Message mac update
187 
188 @copydetails sss_mac_update
189 
190 <table width="60%" class="markdownTable">
191 <tr class="markdownTableHead">
192 <th class="markdownTableHeadNone" width="30%"> Mac Update <th class="markdownTableHeadNone" width="10%"> TX  <th
193 class="markdownTableHeadNone" width="60%"> MU TXn register value
194 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_MacUpdate
195 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput
196 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_mac
197 <tr><td> word        <td> 3  <td> Pointer to message
198 <tr><td> word        <td> 4  <td> messageLen
199 </table>
200 
201 ### Message mac finish
202 
203 @copydetails sss_mac_finish
204 
205 <table width="60%" class="markdownTable">
206 <tr class="markdownTableHead">
207 <th class="markdownTableHeadNone" width="30%"> MAc Finish <th class="markdownTableHeadNone" width="10%"> TX  <th
208 class="markdownTableHeadNone" width="60%"> MU TXn register value
209 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_MacFinish
210 <tr><td> paramTypes  <td> 1  <td> Context, MemrefOutput
211 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_mac
212 <tr><td> word        <td> 3  <td> Pointer to mac
213 <tr><td> word        <td> 4  <td> Pointer to macLen
214 </table>
215 
216 ## Asymmetric
217 
218 ### Asymmetric sign digest
219 
220 @copydetails sss_asymmetric_sign_digest
221 
222 <table width="60%" class="markdownTable">
223 <tr class="markdownTableHead">
224 <th class="markdownTableHeadNone" width="30%"> Asymmetric Sign Digest <th class="markdownTableHeadNone" width="10%"> TX
225 <th class="markdownTableHeadNone" width="60%"> MU TXn register value
226 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_AsymmetricSignDigest
227 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefOutput
228 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_asymmetric
229 <tr><td> word        <td> 3  <td> Pointer to digest
230 <tr><td> word        <td> 4  <td> digestLen
231 <tr><td> word        <td> 5  <td> Pointer to signature
232 <tr><td> word        <td> 6  <td> Pointer to signatureLen
233 </table>
234 
235 ### Asymmetric verify digest
236 
237 @copydetails sss_asymmetric_verify_digest
238 
239 <table width="60%" class="markdownTable">
240 <tr class="markdownTableHead">
241 <th class="markdownTableHeadNone" width="30%"> Asymmetric Verify Digest <th class="markdownTableHeadNone" width="10%">
242 TX  <th class="markdownTableHeadNone" width="60%"> MU TXn register value
243 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_AsymmetricVerifyDigest
244 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, MemrefInput
245 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_asymmetric
246 <tr><td> word        <td> 3  <td> Pointer to digest
247 <tr><td> word        <td> 4  <td> digestLen
248 <tr><td> word        <td> 5  <td> Pointer to signature
249 <tr><td> word        <td> 6  <td> signatureLen
250 </table>
251 
252 ## Tunnel
253 
254 @copydetails sss_tunnel
255 
256 <table width="60%" class="markdownTable">
257 <tr class="markdownTableHead">
258 <th class="markdownTableHeadNone" width="30%"> Tunnel <th class="markdownTableHeadNone" width="10%"> TX
259 <th class="markdownTableHeadNone" width="60%"> MU TXn register value
260 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_Tunnel
261 <tr><td> paramTypes  <td> 1  <td> Context, MemrefInput, Context, ValueInput
262 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_tunnel
263 <tr><td> word        <td> 3  <td> Pointer to input data buffer
264 <tr><td> word        <td> 4  <td> Length of the input data buffer in bytes
265 <tr><td> word        <td> 5  <td> Pointer to an array of ::_sss_sscp_object
266 <tr><td> word        <td> 6  <td> Number of the elements in the array of ::_sss_sscp_object
267 <tr><td> word        <td> 7  <td> Tunnel type id
268 </table>
269 
270 ## Derive key
271 
272 ### Asymmetric shared secret - Diffie-Helmann
273 
274 @copydetails sss_asymmetric_dh_derive_key
275 
276 <table width="60%" class="markdownTable">
277 <tr class="markdownTableHead">
278 <th class="markdownTableHeadNone" width="30%"> Asymmetric Derive Key <th class="markdownTableHeadNone" width="10%"> TX
279 <th class="markdownTableHeadNone" width="60%"> MU TXn register value
280 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_AsymmetricDeriveKey
281 <tr><td> paramTypes  <td> 1  <td> Context, Context, Context
282 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_derive_key
283 <tr><td> word        <td> 3  <td> Pointer to ::_sss_sscp_object
284 <tr><td> word        <td> 4  <td> Pointer to ::_sss_sscp_object
285 </table>
286 
287 ## Key Object
288 
289 ### Key Object Allocate Handle
290 
291 @copydetails sss_key_object_allocate_handle
292 
293 <table width="60%" class="markdownTable">
294 <tr class="markdownTableHead">
295 <th class="markdownTableHeadNone" width="30%"> Key Object Allocate Handle <th class="markdownTableHeadNone" width="10%">
296 TX  <th class="markdownTableHeadNone" width="60%"> MU TXn register value
297 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_KeyObjectAllocateHandle
298 <tr><td> paramTypes  <td> 1  <td> Context, ValueInput, ValueInput
299 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_object
300 <tr><td> word        <td> 3  <td> keyId
301 <tr><td> word        <td> 4  <td> keyType
302 <tr><td> word        <td> 5  <td> keyByteLenMax
303 <tr><td> word        <td> 6  <td> options
304 </table>
305 
306 ## Key Store
307 
308 ### Key Store Allocate
309 
310 @copydetails sss_key_store_allocate
311 
312 <table width="60%" class="markdownTable">
313 <tr class="markdownTableHead">
314 <th class="markdownTableHeadNone" width="30%"> Key Store Allocate <th class="markdownTableHeadNone" width="10%"> TX  <th
315 class="markdownTableHeadNone" width="60%"> MU TXn register value
316 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_KeyStoreAllocate
317 <tr><td> paramTypes  <td> 1  <td> Context, ValueInput
318 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_key_store
319 <tr><td> word        <td> 3  <td> keyStoreId
320 <tr><td> word        <td> 4  <td> Zero
321 </table>
322 
323 ### Set key into key store
324 
325 @copydetails sss_key_store_set_key
326 
327 <table width="60%" class="markdownTable">
328 <tr class="markdownTableHead">
329 <th class="markdownTableHeadNone" width="30%"> Key Store Set Key <th class="markdownTableHeadNone" width="10%"> TX  <th
330 class="markdownTableHeadNone" width="60%"> MU TXn register value
331 <tr><td> Command     <td> 0  <td> kSSCP_CMD_SSS_KeyStoreSetKey
332 <tr><td> paramTypes  <td> 1  <td> Context, Context, MemrefInput, ValueInput, MemrefInput
333 <tr><td> word        <td> 2  <td> Pointer to ::_sss_sscp_key_store
334 <tr><td> word        <td> 3  <td> Pointer to ::_sss_sscp_object
335 <tr><td> word        <td> 4  <td> Pointer to key buffer
336 <tr><td> word        <td> 5  <td> Length of key buffer in bytes
337 <tr><td> word        <td> 6  <td> Key Length in bits
338 <tr><td> word        <td> 7  <td> Zero
339 <tr><td> word        <td> 8  <td> Pointer to options buffer
340 <tr><td> word        <td> 9  <td> Length of the options buffer in bytes
341 </table>
342 
343 */
344 
345 /*******************************************************************************
346  * API
347  ******************************************************************************/
348 #if defined(__cplusplus)
349 extern "C" {
350 #endif
351 
352 /*!
353  * @addtogroup sscp_mu
354  * @{
355  */
356 
357 /**
358  * struct sscp_mu_context_t - SSCP context struct for MU implementation
359  *
360  * This data type is used to keep context of the SSCP link.
361  * It is completely implementation specific.
362  *
363  * @param context Container for the implementation specific data.
364  */
365 typedef struct
366 {
367     fn_sscp_invoke_command_t invoke;
368 
369     /*! Implementation specific part */
370     ELEMU_Type *base;
371 } sscp_mu_context_t;
372 
373 /*! @brief Initializes the SSCP link
374  *
375  * This function initializes the SSCP for operation - e.g.underlaying hardware is initialized
376  * and prepared for data exchange.
377  *
378  * @param context Context structure for the SSCP.
379  * @param base The MU peripheral base address to be used for communication
380  *
381  * @returns Status of the operation
382  * @retval kStatus_SSCP_Success SSCP init success
383  * @retval kStatus_SSCP_Fail SSCP init failure
384  */
385 sscp_status_t sscp_mu_init(sscp_context_t *context, ELEMU_Type *base);
386 
387 /*! @brief Close the SSCP link
388  *
389  * This function closes the SSCP link - e.g.underlying hardware is disabled.
390  *
391  * @param context Context structure for the SSCP.
392  */
393 void sscp_mu_deinit(sscp_context_t *context);
394 
395 /*! @brief Sends a command and associated parameters to security sub-system
396  *
397  *  The commandID and operation content is serialized and sent over to the selected security sub-system.
398  *  This is implementation specific function.
399  *  The function can invoke both blocking and non-blocking secure functions in the selected security sub-system.
400  *
401  * @param context Initialized SSCP context
402  * @param commandID Command - an id of a remote secure function to be invoked
403  * @param op Description of function arguments as a sequence of buffers and values
404  * @param ret Return code of the remote secure function (application layer return value)
405  *
406  * @returns Status of the operation
407  * @retval kStatus_SSCP_Success A blocking command has completed or a non-blocking command has been accepted.
408  * @retval kStatus_SSCP_Fail Operation failure, for example hardware fail.
409  * @retval kStatus_SSCP_InvalidArgument One of the arguments is invalid for the function to execute.
410  */
411 sscp_status_t sscp_mu_invoke_command(sscp_context_t *context,
412                                      sscp_command_t commandId,
413                                      sscp_operation_t *op,
414                                      uint32_t *ret);
415 
416 void MU_Init(void);
417 
418 sscp_status_t MU_ReceiveMsg(ELEMU_Type *base, uint32_t msg[ELEMU_RR_COUNT], size_t wordNum);
419 
420 sscp_status_t MU_SendMsg(ELEMU_Type *base, uint32_t msg[ELEMU_TR_COUNT], size_t wordNum);
421 
422 #if defined(__cplusplus)
423 }
424 #endif
425 
426 /*!
427  *@}
428  */ /* end of sscp_mu */
429 
430 #endif /* FSL_SSCP_MU_H */
431