MCUX CLNS
MCUX Crypto Library Normal Secure
 
Loading...
Searching...
No Matches
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
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
46#define MCUXCLELS_API
47
48/**********************************************
49 * CONSTANTS
50 **********************************************/
51
52#ifdef MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK
53 #define MCUXCLELS_DMA_READBACK_PROTECTION_TOKEN MCUX_CSSL_FP_FUNCTION_CALLED(mcuxClEls_CompareDmaFinalOutputAddress)
54#else
55 #define MCUXCLELS_DMA_READBACK_PROTECTION_TOKEN (0u)
56#endif
57
58
65#define MCUXCLELS_ELS_INTERRUPT_ENABLE (0x01U)
66#define MCUXCLELS_ELS_INTERRUPT_DISABLE (0x00U)
67#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
68#define MCUXCLELS_GLITCH_DETECTOR_INTERRUPT_ENABLE ((uint32_t) 1U)
69#define MCUXCLELS_GLITCH_DETECTOR_INTERRUPT_DISABLE ((uint32_t) 0U)
70#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
79#define MCUXCLELS_ELS_RESET_CLEAR (0x01U)
80#define MCUXCLELS_ELS_RESET_KEEP (0x00U)
81#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
82#define MCUXCLELS_GLITCH_DETECTOR_RESET_CLEAR ((uint32_t) 1U)
83#define MCUXCLELS_GLITCH_DETECTOR_RESET_KEEP ((uint32_t) 0U)
84#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
93#define MCUXCLELS_ELS_INTERRUPT_SET (0x01U)
94#define MCUXCLELS_ELS_INTERRUPT_KEEP (0x00U)
95#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
96#define MCUXCLELS_GLITCH_DETECTOR_NEG_SET (0x01U)
97#define MCUXCLELS_GLITCH_DETECTOR_NEG_KEEP (0x00U)
98#define MCUXCLELS_GLITCH_DETECTOR_POS_SET (0x01U)
99#define MCUXCLELS_GLITCH_DETECTOR_POS_KEEP (0x00U)
100#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
109#define MCUXCLELS_ERROR_FLAGS_KEEP ((mcuxClEls_ErrorHandling_t) 0x0u)
110#define MCUXCLELS_ERROR_FLAGS_CLEAR ((mcuxClEls_ErrorHandling_t) 0x1u)
119#define MCUXCLELS_RESET_DO_NOT_CANCEL ((mcuxClEls_ResetOption_t) 0x0u)
120#define MCUXCLELS_RESET_CANCEL ((mcuxClEls_ResetOption_t) 0x1u)
134#define MCUXCLELS_STATUS_PPROT_UNPRIVILEGED_SECURE ((uint32_t) 0x0u)
135#define MCUXCLELS_STATUS_PPROT_PRIVILEGED_SECURE ((uint32_t) 0x1u)
136#define MCUXCLELS_STATUS_PPROT_UNPRIVILEGED_NONSECURE ((uint32_t) 0x2u)
137#define MCUXCLELS_STATUS_PPROT_PRIVILEGED_NONSECURE ((uint32_t) 0x3u)
146#define MCUXCLELS_STATUS_ECDSAVFY_NORUN ((uint32_t) 0x0u)
147#define MCUXCLELS_STATUS_ECDSAVFY_FAIL ((uint32_t) 0x1u)
148#define MCUXCLELS_STATUS_ECDSAVFY_OK ((uint32_t) 0x2u)
149#define MCUXCLELS_STATUS_ECDSAVFY_ERROR ((uint32_t) 0x3u)
157#define MCUXCLELS_STATUS_DRBGENTLVL_NONE ((uint32_t) 0x0u)
158#define MCUXCLELS_STATUS_DRBGENTLVL_LOW ((uint32_t) 0x1u)
159#define MCUXCLELS_STATUS_DRBGENTLVL_HIGH ((uint32_t) 0x2u)
162#ifdef MCUXCL_FEATURE_ELS_LOCKING
168#define MCUXCLELS_MASTER_UNLOCK_ANY ((uint32_t) 0x1Fu)
170#endif /* MCUXCL_FEATURE_ELS_LOCKING */
171
172
173
178/**********************************************
179 * TYPEDEFS
180 **********************************************/
181
194typedef union
195{
196 struct
197 {
198 uint32_t value;
199 } word;
200 struct
201 {
202 uint32_t revision :4;
203 uint32_t minor :8;
204 uint32_t major :4;
205#ifndef MCUXCL_FEATURE_ELS_GET_FW_VERSION
206 uint32_t level :4;
207 uint32_t :12;
208#else /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
209 uint32_t fw_revision :4;
210 uint32_t fw_minor :8;
211 uint32_t fw_major :4;
212#endif /* MCUXCL_FEATURE_ELS_GET_FW_VERSION */
213 } bits;
215
221typedef union
222{
223 struct
224 {
225 uint32_t value;
226 } word;
227 struct
228 {
229 uint32_t busy :1;
230 uint32_t irq :1;
231 uint32_t err :1;
232 uint32_t prngready :1;
233 uint32_t ecdsavfy :2;
234 uint32_t pprot :2;
235 uint32_t drbgentlvl :2;
236 uint32_t dtrng_busy: 1;
237#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
238 uint32_t gdet_pos :1;
239 uint32_t gdet_neg :1;
240#else
241 uint32_t :2;
242#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
243 uint32_t :3;
244#ifdef MCUXCL_FEATURE_ELS_LOCKING
245 uint32_t els_locked :1;
246#else
247 uint32_t :1;
248#endif /* MCUXCL_FEATURE_ELS_LOCKING */
249 uint32_t :15;
250 } bits;
252
259
265typedef uint32_t mcuxClEls_ResetOption_t;
266
272typedef union
273{
274 struct
275 {
276 uint32_t value;
277 } word;
278 struct
279 {
280 uint32_t elsint :1;
281#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
282 uint32_t gdetint :1;
283#else
284 uint32_t :1;
285#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
286 uint32_t :30;
287 } bits;
289
293typedef union
294{
295 struct
296 {
297 uint32_t value;
298 } word;
299 struct
300 {
301 uint32_t elsint :1;
302#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
303 uint32_t gdetint :1;
304#else
305 uint32_t :1;
306#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
307 uint32_t :30;
308 } bits;
310
314typedef union
315{
316 struct
317 {
318 uint32_t value;
319 } word;
320 struct
321 {
322 uint32_t elsint :1;
323#ifdef MCUXCL_FEATURE_ELS_GLITCHDETECTOR
324 uint32_t gdetint_neg :1;
325 uint32_t gdetint_pos :1;
326#else
327 uint32_t :2;
328#endif /* MCUXCL_FEATURE_ELS_GLITCHDETECTOR */
329 uint32_t :29;
330 } bits;
332
338typedef union
339{
340 struct
341 {
342 uint32_t value;
343 } word;
344 struct
345 {
346 uint32_t ciphersup :1;
347 uint32_t authciphersup :1;
348 uint32_t ecsignsup :1;
349 uint32_t ecvfysup :1;
350 uint32_t eckxchsup :1;
351 uint32_t keygensup :1;
352 uint32_t keyinsup :1;
353 uint32_t keyoutsup :1;
354 uint32_t kdeletesup :1;
355 uint32_t keyprovsup :1;
356 uint32_t ckdfsup :1;
357 uint32_t hkdfsup :1;
358 uint32_t tlsinitsup :1;
359 uint32_t hashsup :1;
360 uint32_t hmacsup :1;
361 uint32_t cmacsup :1;
362 uint32_t drbgreqsup :1;
363 uint32_t drbgtestsup :1;
364 uint32_t dtrgncfgloadsup :1;
365 uint32_t dtrngevalsup :1;
366 uint32_t gdetcfgloadsup :1;
367 uint32_t gdettrimsup :1;
368 uint32_t :10;
369 } bits;
371
372#define drbgreqsub drbgreqsup
373
374
379/**********************************************
380 * FUNCTIONS
381 **********************************************/
402 mcuxClEls_HwVersion_t * result
403 );
404
405#ifdef MCUXCL_FEATURE_ELS_HWCONFIG
417MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetHwConfig)
419 mcuxClEls_HwConfig_t * result
420 );
421#endif /* MCUXCL_FEATURE_ELS_HWCONFIG */
422
436 mcuxClEls_HwState_t * result
437 );
438
452 void
453 );
454
482 );
483
497 void
498);
499
514 );
515
530 );
531
546 );
547
562 );
563
583 mcuxClEls_ErrorHandling_t errorHandling
584 );
585
609 uint32_t counterLimit,
610 mcuxClEls_ErrorHandling_t errorHandling
611 );
612
624 void);
625
641 mcuxClEls_ErrorHandling_t errorHandling
642 );
643
661 mcuxClEls_ErrorHandling_t errorHandling,
662 uint32_t *errorLevel
663 );
664
680 uint32_t startDelay
681 );
682
698 uint32_t * startDelay
699 );
700
701#ifdef MCUXCL_FEATURE_ELS_LOCKING
725MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetLock)
727 uint32_t * pSessionId
728 );
729
749MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_ReleaseLock)
751 uint32_t sessionId
752 );
753
768MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_IsLocked)
770
787MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_SetMasterUnlock)
789 uint32_t masterId
790 );
791
792#endif /* MCUXCL_FEATURE_ELS_LOCKING */
793
794
795#ifdef MCUXCL_FEATURE_ELS_DMA_ADDRESS_READBACK
807MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_GetLastDmaAddress)
809 uint32_t* pLastAddress
810 );
811#endif /* MCUXCL_FEATURE_ELS_DMA_ADDRESS_READBACK */
812
813#ifdef MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK
831MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_CompareDmaFinalOutputAddress)
832MCUXCLELS_API MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClEls_Status_t) mcuxClEls_CompareDmaFinalOutputAddress(
833 uint8_t *outputStartAddress,
834 size_t expectedLength
835 );
836#endif /* MCUXCL_FEATURE_ELS_DMA_FINAL_ADDRESS_READBACK */
837
838#ifdef __cplusplus
839} /* extern "C" */
840#endif
841
842#endif /* MCUXCLELS_COMMON_H_ */
843
Definition of function identifiers for the flow protection mechanism.
ELS type header.
Provides the API for the CSSL flow protection mechanism.
#define MCUXCLELS_API
Marks a function as a public API function of the mcuxClEls component.
Definition mcuxClEls_Common.h:46
uint32_t mcuxClEls_ErrorHandling_t
Type to handle ELS error clearing options.
Definition mcuxClEls_Common.h:258
uint32_t mcuxClEls_ResetOption_t
Type to handle ELS reset options.
Definition mcuxClEls_Common.h:265
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_ResetIntFlags(mcuxClEls_InterruptOptionRst_t options)
Clear the interrupt status register.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetRandomStartDelay(uint32_t startDelay)
Set the random start delay for AES based operations.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetIntEnableFlags(mcuxClEls_InterruptOptionEn_t options)
Set interrupt enable flags.
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 ...
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetIntEnableFlags(mcuxClEls_InterruptOptionEn_t *result)
Get interrupt enable flags.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Enable_Async(void)
Enables the ELS.
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.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_SetIntFlags(mcuxClEls_InterruptOptionSet_t options)
Set the interrupt status register, for debug and testing purposes.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Reset_Async(mcuxClEls_ResetOption_t options)
Perform a synchronous reset of the ELS.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetHwVersion(mcuxClEls_HwVersion_t *result)
Determines the version of the underlying ELS hardware IP.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Disable(void)
Disable the ELS.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetHwState(mcuxClEls_HwState_t *result)
Determines the current state of the ELS.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetErrorCode(mcuxClEls_ErrorHandling_t errorHandling)
Get the last ELS error code and optionally clear the error status.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_WaitForOperation(mcuxClEls_ErrorHandling_t errorHandling)
Wait for an ELS operation and optionally clear the error status.
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_GetRandomStartDelay(uint32_t *startDelay)
Get the random start delay for AES based operations.
uint32_t mcuxClEls_Status_t
Type for ELS driver status codes.
Definition mcuxClEls_Types.h:212
#define MCUX_CSSL_FP_FUNCTION_DECL(...)
Declaration of a flow protected function.
Definition mcuxCsslFlowProtection.h:125
#define MCUX_CSSL_FP_PROTECTED_TYPE(resultType)
Based on a given base type, builds a return type with flow protection.
Definition mcuxCsslFlowProtection.h:81
Result type of mcuxClEls_GetHwVersion.
Definition mcuxClEls_Common.h:195
uint32_t major
Major version.
Definition mcuxClEls_Common.h:204
uint32_t revision
Revision number.
Definition mcuxClEls_Common.h:202
uint32_t level
Release level version.
Definition mcuxClEls_Common.h:206
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:198
uint32_t minor
Minor version.
Definition mcuxClEls_Common.h:203
Result type of mcuxClEls_GetHwState.
Definition mcuxClEls_Common.h:222
uint32_t dtrng_busy
Indicates the DTRNG is gathering entropy.
Definition mcuxClEls_Common.h:236
uint32_t ecdsavfy
ECDSA verify operation state (For possible values of this field, see MCUXCLELS_STATUS_ECDSAVFY_)
Definition mcuxClEls_Common.h:233
uint32_t busy
ELS is busy.
Definition mcuxClEls_Common.h:229
uint32_t err
ELS is in error state.
Definition mcuxClEls_Common.h:231
uint32_t drbgentlvl
Entropy quality of the current DRBG instance (For possible values of this field, see MCUXCLELS_STATUS...
Definition mcuxClEls_Common.h:235
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:225
uint32_t pprot
The privilege/security level of the most recently started ELS command (For possible values of this fi...
Definition mcuxClEls_Common.h:234
uint32_t irq
ELS interrupt activated.
Definition mcuxClEls_Common.h:230
uint32_t prngready
ELS PRNG is seeded and ready to use.
Definition mcuxClEls_Common.h:232
Command option type for mcuxClEls_SetIntEnableFlags and mcuxClEls_GetIntEnableFlags.
Definition mcuxClEls_Common.h:273
uint32_t elsint
Whether ELS interrupt should be used. (For possible values of this field, see mcuxClEls_InterruptOpti...
Definition mcuxClEls_Common.h:280
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:276
Type to control which ELS interrupts should be reset when calling mcuxClEls_ResetIntFlags.
Definition mcuxClEls_Common.h:294
uint32_t elsint
Whether ELS interrupt should be reset. (For possible values of this field, see mcuxClEls_InterruptOpt...
Definition mcuxClEls_Common.h:301
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:297
Type to control which ELS interrupts should be set when calling mcuxClEls_SetIntFlags.
Definition mcuxClEls_Common.h:315
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:318
uint32_t elsint
Whether ELS interrupt should be set. (For possible values of this field, see mcuxClEls_InterruptOptio...
Definition mcuxClEls_Common.h:322
Result type of #mcuxClEls_GetHwConfig.
Definition mcuxClEls_Common.h:339
uint32_t ckdfsup
Indicates whether the ckdf command is supported.
Definition mcuxClEls_Common.h:356
uint32_t ecvfysup
Indicates whether the ecvfy command is supported.
Definition mcuxClEls_Common.h:349
uint32_t keyinsup
Indicates whether the keyin command is supported.
Definition mcuxClEls_Common.h:352
uint32_t drbgreqsup
Indicates whether the drbg_req command is supported.
Definition mcuxClEls_Common.h:362
uint32_t dtrgncfgloadsup
Indicates whether the dtrng_cfg_load command is is supported.
Definition mcuxClEls_Common.h:364
uint32_t value
Accesses the bit field as a full word.
Definition mcuxClEls_Common.h:342
uint32_t hmacsup
Indicates whether the hmac command is supported.
Definition mcuxClEls_Common.h:360
uint32_t gdettrimsup
Indicates whether the gdet_trim command is supported.
Definition mcuxClEls_Common.h:367
uint32_t keyprovsup
Indicates whether the keyprov command is supported.
Definition mcuxClEls_Common.h:355
uint32_t keyoutsup
Indicates whether the keyout command is supported.
Definition mcuxClEls_Common.h:353
uint32_t dtrngevalsup
Indicates whether the dtrng_eval command is supported.
Definition mcuxClEls_Common.h:365
uint32_t gdetcfgloadsup
Indicates whether the gdet_cfg_load command is supported.
Definition mcuxClEls_Common.h:366
uint32_t tlsinitsup
Indicates whether the tls_init command is supported.
Definition mcuxClEls_Common.h:358
uint32_t ecsignsup
Indicates whether the ecsign command is supported.
Definition mcuxClEls_Common.h:348
uint32_t ciphersup
Indicates whether the cipher command is supported.
Definition mcuxClEls_Common.h:346
uint32_t hashsup
Indicates whether the hash command is supported.
Definition mcuxClEls_Common.h:359
uint32_t eckxchsup
Indicates whether the dhkey_xch command is supported.
Definition mcuxClEls_Common.h:350
uint32_t authciphersup
Indicates whether the auth_cipher command is supported.
Definition mcuxClEls_Common.h:347
uint32_t cmacsup
Indicates whether the cmac command is supported.
Definition mcuxClEls_Common.h:361
uint32_t keygensup
Indicates whether the keygen command is supported.
Definition mcuxClEls_Common.h:351
uint32_t drbgtestsup
Indicates whether the drbg_test command is supported.
Definition mcuxClEls_Common.h:363
uint32_t hkdfsup
Indicates whether the hkdf command is supported.
Definition mcuxClEls_Common.h:357
uint32_t kdeletesup
Indicates whether the kdelete command is supported.
Definition mcuxClEls_Common.h:354