MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClEls_Common.h
Go to the documentation of this file.
1 /*--------------------------------------------------------------------------*/
2 /* Copyright 2020-2023 NXP */
3 /* */
4 /* NXP Confidential. This software is owned or controlled by NXP and may */
5 /* only be used strictly in accordance with the applicable license terms. */
6 /* By expressly accepting such terms or by downloading, installing, */
7 /* activating and/or otherwise using the software, you are agreeing that */
8 /* you have read, and that you agree to comply with and are bound by, such */
9 /* license terms. If you do not agree to be bound by the applicable license */
10 /* terms, then you may not retain, install, activate or otherwise use the */
11 /* software. */
12 /*--------------------------------------------------------------------------*/
13 
27 #ifndef MCUXCLELS_COMMON_H_
28 #define MCUXCLELS_COMMON_H_
29 
30 #include <mcuxClConfig.h> // Exported features flags header
31 #include <mcuxClEls_Types.h> // Common types
32 #include <mcuxCsslFlowProtection.h>
34 #include <platform_specific_headers.h>
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39 
47 #define MCUXCLELS_API
48 
49 /**********************************************
50  * CONSTANTS
51  **********************************************/
52 
57 #ifndef MCUXCL_FEATURE_ELS_GET_FW_VERSION
58 #define MCUXCLELS_HW_VERSION ((mcuxClEls_HwVersion_t) { \
59  .bits = { \
60  .revision = (uint32_t) ELS_HW_VERSION_REVISION, \
61  .minor = (uint32_t) ELS_HW_VERSION_MINOR, \
62  .major = (uint32_t) ELS_HW_VERSION_MAJOR, \
63  .level = (uint32_t) ELS_HW_VERSION_LEVEL \
64  } \
65  })
66 #else /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
67 #define MCUXCLELS_HW_VERSION ((mcuxClEls_HwVersion_t) { \
68  .bits = { \
69  .revision = (uint32_t) ELS_HW_VERSION_REVISION, \
70  .minor = (uint32_t) ELS_HW_VERSION_MINOR, \
71  .major = (uint32_t) ELS_HW_VERSION_MAJOR, \
72  .fw_revision = (uint32_t) ELS_HW_VERSION_FW_REVISION, \
73  .fw_minor = (uint32_t) ELS_HW_VERSION_FW_MINOR, \
74  .fw_major = (uint32_t) ELS_HW_VERSION_FW_MAJOR \
75  } \
76  })
77 #endif /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
78 
79 #ifdef MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK
80  #define MCUXCLELS_DMA_READBACK_PROTECTION_TOKEN MCUX_CSSL_FP_FUNCTION_CALLED(mcuxClEls_CompareDmaFinalOutputAddress)
81 #else
82  #define MCUXCLELS_DMA_READBACK_PROTECTION_TOKEN (0u)
83 #endif
84 
85 
92 #define MCUXCLELS_ELS_INTERRUPT_ENABLE (0x01U)
93 #define MCUXCLELS_ELS_INTERRUPT_DISABLE (0x00U)
94 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
95 #define MCUXCLELS_GLITCH_DETECTOR_INTERRUPT_ENABLE ((uint32_t) 1U)
96 #define MCUXCLELS_GLITCH_DETECTOR_INTERRUPT_DISABLE ((uint32_t) 0U)
97 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
98 
106 #define MCUXCLELS_ELS_RESET_CLEAR (0x01U)
107 #define MCUXCLELS_ELS_RESET_KEEP (0x00U)
108 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
109 #define MCUXCLELS_GLITCH_DETECTOR_RESET_CLEAR ((uint32_t) 1U)
110 #define MCUXCLELS_GLITCH_DETECTOR_RESET_KEEP ((uint32_t) 0U)
111 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
112 
120 #define MCUXCLELS_ELS_INTERRUPT_SET (0x01U)
121 #define MCUXCLELS_ELS_INTERRUPT_KEEP (0x00U)
122 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
123 #define MCUXCLELS_GLITCH_DETECTOR_NEG_SET (0x01U)
124 #define MCUXCLELS_GLITCH_DETECTOR_NEG_KEEP (0x00U)
125 #define MCUXCLELS_GLITCH_DETECTOR_POS_SET (0x01U)
126 #define MCUXCLELS_GLITCH_DETECTOR_POS_KEEP (0x00U)
127 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
128 
136 #define MCUXCLELS_ERROR_FLAGS_KEEP ((mcuxClEls_ErrorHandling_t) 0x0u)
137 #define MCUXCLELS_ERROR_FLAGS_CLEAR ((mcuxClEls_ErrorHandling_t) 0x1u)
138 
146 #define MCUXCLELS_RESET_DO_NOT_CANCEL ((mcuxClEls_ResetOption_t) 0x0u)
147 #define MCUXCLELS_RESET_CANCEL ((mcuxClEls_ResetOption_t) 0x1u)
148 
161 #define MCUXCLELS_STATUS_PPROT_UNPRIVILEGED_SECURE ((uint32_t) 0x0u)
162 #define MCUXCLELS_STATUS_PPROT_PRIVILEGED_SECURE ((uint32_t) 0x1u)
163 #define MCUXCLELS_STATUS_PPROT_UNPRIVILEGED_NONSECURE ((uint32_t) 0x2u)
164 #define MCUXCLELS_STATUS_PPROT_PRIVILEGED_NONSECURE ((uint32_t) 0x3u)
165 
173 #define MCUXCLELS_STATUS_ECDSAVFY_NORUN ((uint32_t) 0x0u)
174 #define MCUXCLELS_STATUS_ECDSAVFY_FAIL ((uint32_t) 0x1u)
175 #define MCUXCLELS_STATUS_ECDSAVFY_OK ((uint32_t) 0x2u)
176 #define MCUXCLELS_STATUS_ECDSAVFY_ERROR ((uint32_t) 0x3u)
177 
184 #define MCUXCLELS_STATUS_DRBGENTLVL_NONE ((uint32_t) 0x0u)
185 #define MCUXCLELS_STATUS_DRBGENTLVL_LOW ((uint32_t) 0x1u)
186 #define MCUXCLELS_STATUS_DRBGENTLVL_HIGH ((uint32_t) 0x2u)
187 
189 #ifdef MCUXCL_FEATURE_ELS_LOCKING
190 
195 #define MCUXCLELS_MASTER_UNLOCK_ANY ((uint32_t) 0x1Fu)
196 
197 #endif /* MCUXCL_FEATURE_ELS_LOCKING */
198 
199 
200 
205 /**********************************************
206  * TYPEDEFS
207  **********************************************/
208 
221 typedef union
222 {
223  struct
224  {
225  uint32_t value;
226  } word;
227  struct
228  {
229  uint32_t revision :4;
230  uint32_t minor :8;
231  uint32_t major :4;
232 #ifndef MCUXCL_FEATURE_ELS_GET_FW_VERSION
233  uint32_t level :4;
234  uint32_t :12;
235 #else /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
236  uint32_t fw_revision :4;
237  uint32_t fw_minor :8;
238  uint32_t fw_major :4;
239 #endif /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
240  } bits;
242 
248 typedef union
249 {
250  struct
251  {
252  uint32_t value;
253  } word;
254  struct
255  {
256  uint32_t busy :1;
257  uint32_t irq :1;
258  uint32_t err :1;
259  uint32_t prngready :1;
260  uint32_t ecdsavfy :2;
261  uint32_t pprot :2;
262  uint32_t drbgentlvl :2;
263  uint32_t dtrng_busy: 1;
264 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
265  uint32_t gdet_pos :1;
266  uint32_t gdet_neg :1;
267 #else
268  uint32_t :2;
269 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
270  uint32_t :3;
271 #ifdef MCUXCL_FEATURE_ELS_LOCKING
272  uint32_t els_locked :1;
273 #else
274  uint32_t :1;
275 #endif /* MCUXCL_FEATURE_ELS_LOCKING */
276  uint32_t :15;
277  } bits;
279 
285 typedef uint32_t mcuxClEls_ErrorHandling_t;
286 
292 typedef uint32_t mcuxClEls_ResetOption_t;
293 
299 typedef union
300 {
301  struct
302  {
303  uint32_t value;
304  } word;
305  struct
306  {
307  uint32_t elsint :1;
308 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
309  uint32_t gdetint :1;
310 #else
311  uint32_t :1;
312 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
313  uint32_t :30;
314  } bits;
316 
320 typedef union
321 {
322  struct
323  {
324  uint32_t value;
325  } word;
326  struct
327  {
328  uint32_t elsint :1;
329 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
330  uint32_t gdetint :1;
331 #else
332  uint32_t :1;
333 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
334  uint32_t :30;
335  } bits;
337 
341 typedef union
342 {
343  struct
344  {
345  uint32_t value;
346  } word;
347  struct
348  {
349  uint32_t elsint :1;
350 #ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
351  uint32_t gdetint_neg :1;
352  uint32_t gdetint_pos :1;
353 #else
354  uint32_t :2;
355 #endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
356  uint32_t :29;
357  } bits;
359 
365 typedef union
366 {
367  struct
368  {
369  uint32_t value;
370  } word;
371  struct
372  {
373  uint32_t ciphersup :1;
374  uint32_t authciphersup :1;
375  uint32_t ecsignsup :1;
376  uint32_t ecvfysup :1;
377  uint32_t eckxchsup :1;
378  uint32_t keygensup :1;
379  uint32_t keyinsup :1;
380  uint32_t keyoutsup :1;
381  uint32_t kdeletesup :1;
382  uint32_t keyprovsup :1;
383  uint32_t ckdfsup :1;
384  uint32_t hkdfsup :1;
385  uint32_t tlsinitsup :1;
386  uint32_t hashsup :1;
387  uint32_t hmacsup :1;
388  uint32_t cmacsup :1;
389  uint32_t drbgreqsup :1;
390  uint32_t drbgtestsup :1;
391  uint32_t dtrgncfgloadsup :1;
392  uint32_t dtrngevalsup :1;
393  uint32_t gdetcfgloadsup :1;
394  uint32_t gdettrimsup :1;
395  uint32_t :10;
396  } bits;
398 
399 #define drbgreqsub drbgreqsup
400 
401 
406 /**********************************************
407  * FUNCTIONS
408  **********************************************/
430  mcuxClEls_HwVersion_t * result
431  );
432 
433 #ifdef MCUXCL_FEATURE_ELS_HWCONFIG
434 
445 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetHwConfig)
447  mcuxClEls_HwConfig_t * result
448  );
449 #endif /* MCUXCL_FEATURE_ELS_HWCONFIG */
450 
464  mcuxClEls_HwState_t * result
465  );
466 
480  void
481  );
482 
510  );
511 
525  void
526 );
527 
542  );
543 
558  );
559 
574  );
575 
590  );
591 
611  mcuxClEls_ErrorHandling_t errorHandling
612  );
613 
637  uint32_t counterLimit,
638  mcuxClEls_ErrorHandling_t errorHandling
639  );
640 
652  void);
653 
669  mcuxClEls_ErrorHandling_t errorHandling
670  );
671 
689  mcuxClEls_ErrorHandling_t errorHandling,
690  uint32_t *errorLevel
691  );
692 
708  uint32_t delay
709  );
710 
726  uint32_t * delay
727  );
728 
729 #ifdef MCUXCL_FEATURE_ELS_LOCKING
730 
753 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetLock)
755  uint32_t * pSessionId
756  );
757 
777 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_ReleaseLock)
779  uint32_t sessionId
780  );
781 
796 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_IsLocked)
798 
815 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_SetMasterUnlock)
817  uint32_t masterId
818  );
819 
820 #endif /* MCUXCL_FEATURE_ELS_LOCKING */
821 
822 
823 #ifdef MCUXCL_FEATURE_ELS_DMA_ADDRESS_READBACK
824 
835 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetLastDmaAddress)
837  uint32_t* pLastAddress
838  );
839 #endif /* MCUXCL_FEATURE_ELS_DMA_ADDRESS_READBACK */
840 
841 #ifdef MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK
842 
859 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_CompareDmaFinalOutputAddress)
860 MCUXCLELS_API MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClEls_Status_t) mcuxClEls_CompareDmaFinalOutputAddress(
861  uint8_t *outputStartAddress,
862  size_t expectedLength
863  );
864 #endif /* MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK */
865 
866 #ifdef __cplusplus
867 } /* extern "C" */
868 #endif
869 
870 #endif /* MCUXCLELS_COMMON_H_ */
871 
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetIntEnableFlags(mcuxClEls_InterruptOptionEn_t options)
Set interrupt enable flags.
uint32_t drbgreqsup
Indicates whether the drbg_req command is supported.
Definition: mcuxClEls_Common.h:389
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:252
uint32_t gdettrimsup
Indicates whether the gdet_trim command is supported.
Definition: mcuxClEls_Common.h:394
uint32_t ciphersup
Indicates whether the cipher command is supported.
Definition: mcuxClEls_Common.h:373
uint32_t elsint
Whether ELS interrupt should be reset. (For possible values of this field, see mcuxClEls_InterruptOpt...
Definition: mcuxClEls_Common.h:328
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetIntFlags(mcuxClEls_InterruptOptionSet_t options)
Set the interrupt status register, for debug and testing purposes.
uint32_t keyinsup
Indicates whether the keyin command is supported.
Definition: mcuxClEls_Common.h:379
uint32_t drbgentlvl
Entropy quality of the current DRBG instance (For possible values of this field, see MCUXCLELS_STATUS...
Definition: mcuxClEls_Common.h:262
uint32_t eckxchsup
Indicates whether the dhkey_xch command is supported.
Definition: mcuxClEls_Common.h:377
uint32_t dtrgncfgloadsup
Indicates whether the dtrng_cfg_load command is is supported.
Definition: mcuxClEls_Common.h:391
uint32_t gdetcfgloadsup
Indicates whether the gdet_cfg_load command is supported.
Definition: mcuxClEls_Common.h:393
uint32_t minor
Minor version.
Definition: mcuxClEls_Common.h:230
Result type of #mcuxClEls_GetHwConfig.
Definition: mcuxClEls_Common.h:365
uint32_t elsint
Whether ELS interrupt should be set. (For possible values of this field, see mcuxClEls_InterruptOptio...
Definition: mcuxClEls_Common.h:349
uint32_t major
Major version.
Definition: mcuxClEls_Common.h:231
uint32_t hashsup
Indicates whether the hash command is supported.
Definition: mcuxClEls_Common.h:386
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_LimitedWaitForOperation(uint32_t counterLimit, mcuxClEls_ErrorHandling_t errorHandling)
Await the completion of an ELS operation for a limited amount of time and optionally clear the error ...
uint32_t kdeletesup
Indicates whether the kdelete command is supported.
Definition: mcuxClEls_Common.h:381
uint32_t keygensup
Indicates whether the keygen command is supported.
Definition: mcuxClEls_Common.h:378
uint32_t keyprovsup
Indicates whether the keyprov command is supported.
Definition: mcuxClEls_Common.h:382
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Disable(void)
Disable the ELS.
uint32_t hkdfsup
Indicates whether the hkdf command is supported.
Definition: mcuxClEls_Common.h:384
uint32_t authciphersup
Indicates whether the auth_cipher command is supported.
Definition: mcuxClEls_Common.h:374
uint32_t keyoutsup
Indicates whether the keyout command is supported.
Definition: mcuxClEls_Common.h:380
uint32_t pprot
The privilege/security level of the most recently started ELS command (For possible values of this fi...
Definition: mcuxClEls_Common.h:261
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetRandomStartDelay(uint32_t *delay)
Get the random start delay for AES based operations.
Provides the API for the CSSL flow protection mechanism.
uint32_t err
ELS is in error state.
Definition: mcuxClEls_Common.h:258
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_ResetIntFlags(mcuxClEls_InterruptOptionRst_t options)
Clear the interrupt status register.
uint32_t cmacsup
Indicates whether the cmac command is supported.
Definition: mcuxClEls_Common.h:388
uint32_t hmacsup
Indicates whether the hmac command is supported.
Definition: mcuxClEls_Common.h:387
uint32_t irq
ELS interrupt activated.
Definition: mcuxClEls_Common.h:257
#define MCUXCLELS_API
Marks a function as a public API function of the mcuxClEls component.
Definition: mcuxClEls_Common.h:47
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_WaitForOperation(mcuxClEls_ErrorHandling_t errorHandling)
Wait for an ELS operation and optionally clear the error status.
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:324
uint32_t ecsignsup
Indicates whether the ecsign command is supported.
Definition: mcuxClEls_Common.h:375
uint32_t drbgtestsup
Indicates whether the drbg_test command is supported.
Definition: mcuxClEls_Common.h:390
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:369
uint32_t ecdsavfy
ECDSA verify operation state (For possible values of this field, see MCUXCLELS_STATUS_ECDSAVFY_)
Definition: mcuxClEls_Common.h:260
ELS type header.
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:225
uint32_t tlsinitsup
Indicates whether the tls_init command is supported.
Definition: mcuxClEls_Common.h:385
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetErrorLevel(mcuxClEls_ErrorHandling_t errorHandling, uint32_t *errorLevel)
Get the last ELS error code and level and optionally clear the error status.
uint32_t prngready
ELS PRNG is seeded and ready to use.
Definition: mcuxClEls_Common.h:259
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetRandomStartDelay(uint32_t delay)
Set the random start delay for AES based operations.
Type to control which ELS interrupts should be set when calling mcuxClEls_SetIntFlags.
Definition: mcuxClEls_Common.h:341
#define MCUX_CSSL_FP_FUNCTION_DECL(...)
Declaration of a flow protected function.
Definition: mcuxCsslFlowProtection.h:125
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:345
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Enable_Async(void)
Enables the ELS.
uint32_t ckdfsup
Indicates whether the ckdf command is supported.
Definition: mcuxClEls_Common.h:383
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetHwState(mcuxClEls_HwState_t *result)
Determines the current state of the ELS.
uint32_t mcuxClEls_ResetOption_t
Type to handle ELS reset options.
Definition: mcuxClEls_Common.h:292
uint32_t dtrng_busy
Indicates the DTRNG is gathering entropy.
Definition: mcuxClEls_Common.h:263
uint32_t revision
Revision number.
Definition: mcuxClEls_Common.h:229
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_ResetErrorFlags(void)
Resets all error flags that have been set by a previous operation.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetHwVersion(mcuxClEls_HwVersion_t *result)
Determines the version of the underlying ELS hardware IP.
Definition of function identifiers for the flow protection mechanism.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetErrorCode(mcuxClEls_ErrorHandling_t errorHandling)
Get the last ELS error code and optionally clear the error status.
uint32_t ecvfysup
Indicates whether the ecvfy command is supported.
Definition: mcuxClEls_Common.h:376
uint32_t mcuxClEls_ErrorHandling_t
Type to handle ELS error clearing options.
Definition: mcuxClEls_Common.h:285
uint32_t level
Release level version.
Definition: mcuxClEls_Common.h:233
Type to control which ELS interrupts should be reset when calling mcuxClEls_ResetIntFlags.
Definition: mcuxClEls_Common.h:320
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Reset_Async(mcuxClEls_ResetOption_t options)
Perform a synchronous reset of the ELS.
Command option type for mcuxClEls_SetIntEnableFlags and mcuxClEls_GetIntEnableFlags.
Definition: mcuxClEls_Common.h:299
#define MCUX_CSSL_FP_PROTECTED_TYPE(resultType)
Based on a given base type, builds a return type with flow protection.
Definition: mcuxCsslFlowProtection.h:81
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Common.h:303
uint32_t mcuxClEls_Status_t
Type for ELS driver status codes.
Definition: mcuxClEls_Types.h:211
Result type of mcuxClEls_GetHwState.
Definition: mcuxClEls_Common.h:248
Result type of mcuxClEls_GetHwVersion.
Definition: mcuxClEls_Common.h:221
uint32_t busy
ELS is busy.
Definition: mcuxClEls_Common.h:256
uint32_t dtrngevalsup
Indicates whether the dtrng_eval command is supported.
Definition: mcuxClEls_Common.h:392
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetIntEnableFlags(mcuxClEls_InterruptOptionEn_t *result)
Get interrupt enable flags.
uint32_t elsint
Whether ELS interrupt should be used. (For possible values of this field, see mcuxClEls_InterruptOpti...
Definition: mcuxClEls_Common.h:307