MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClExample_ELS_Key_Helper.h
1 /*--------------------------------------------------------------------------*/
2 /* Copyright 2022 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 
14 #ifndef MCUXCLEXAMPLE_ELS_KEY_HELPER_H_
15 #define MCUXCLEXAMPLE_ELS_KEY_HELPER_H_
16 
17 #include <mcuxClConfig.h> // Exported features flags header
18 #include <mcuxClCore_Platform.h>
19 #include <mcuxClEls.h>
20 #include <mcuxClExample_RFC3394_Helper.h>
21 #include <mcuxCsslFlowProtection.h>
23 
28 static inline bool mcuxClExample_Els_KeyDelete(mcuxClEls_KeyIndex_t keyIdx)
29 {
31  // mcuxClEls_KeyDelete_Async is a flow-protected function: Check the protection token and the return value
33  {
34  return false; // Expect that no error occurred, meaning that the mcuxClEls_KeyDelete_Async operation was started.
35  }
37 
38  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_WaitForOperation(MCUXCLELS_ERROR_FLAGS_CLEAR)); // Wait for the mcuxClEls_KeyDelete_Async operation to complete.
39  // mcuxClEls_WaitForOperation is a flow-protected function: Check the protection token and the return value
41  {
42  return false;
43  }
45  return true;
46 }
47 
51 static inline bool mcuxClExample_Els_KeyDeleteAll(void)
52 {
54  // mcuxClEls_Reset_Async is a flow-protected function: Check the protection token and the return value
56  {
57  return false;
58  }
60 
61  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_WaitForOperation(MCUXCLELS_ERROR_FLAGS_CLEAR)); // Wait for the mcuxClEls_Reset_Async operation to complete.
62  // mcuxClEls_WaitForOperation is a flow-protected function: Check the protection token and the return value
64  {
65  return false;
66  }
68  return true;
69 }
70 
71 
72 /*
73  * Check only if the mcuxClEls_KeyDelete_Async is defined "because mcuxClEls_KeyProvision_Async will be always defined"
74  * via CL library or via the TEST OS
75  * Function that loads a known key into the ELS key store
76  * [in] helperKeyIdx: The index of the helper key
77  * [in] targetKeyIdx: The key index at which the target key shall be loaded
78  * [in] targetKeyProperties: The target properties of the key
79  * [in] pKey: Pointer to the key to be loaded
80 */
81 #define ELS_RFC_PADDING_LENGTH 16U
82 
83 static bool mcuxClExample_load_els_key(
84  mcuxClEls_KeyIndex_t helperKeyIdx,
85  mcuxClEls_KeyIndex_t targetKeyIdx,
86  mcuxClEls_KeyProp_t properties,
87  const uint8_t* pKey
88 )
89 {
91  uint8_t wrapped_key[MCUXCLELS_CIPHER_KEY_SIZE_AES_256 + ELS_RFC_PADDING_LENGTH];
92 
96  mcuxClEls_KeyProp_t key_properties_targeted;
97  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_GetKeyProperties(targetKeyIdx, &key_properties_targeted));
99  {
100  return false;
101  }
103  if (MCUXCLELS_KEYPROPERTY_ACTIVE_TRUE == key_properties_targeted.bits.kactv)
104  {
105  return true;
106  }
107 
111  mcuxClEls_KeyProp_t AesHelperKeyProp = {0};
112  AesHelperKeyProp.bits.ksize = MCUXCLELS_KEYPROPERTY_KEY_SIZE_256;
115  AesHelperKeyProp.bits.uaes = MCUXCLELS_KEYPROPERTY_AES_TRUE;
116  AesHelperKeyProp.bits.kactv = MCUXCLELS_KEYPROPERTY_ACTIVE_TRUE;
117  AesHelperKeyProp.bits.kbase = MCUXCLELS_KEYPROPERTY_BASE_SLOT;
118 
119  if(true != mcuxClExample_provision_key(helperKeyIdx, AesHelperKeyProp))
120  {
121  return false;
122  }
123 
127  mcuxClExample_rfc3394_wrap(pKey, key_size, NULL, helperKeyIdx, MCUXCLELS_CIPHER_INTERNAL_KEY, MCUXCLELS_CIPHER_KEY_SIZE_AES_256, wrapped_key, properties);
128 
132  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_KeyDelete_Async(helperKeyIdx));
133  // mcuxClEls_KeyDelete_Async is a flow-protected function: Check the protection token and the return value
135  {
136  return false; // Expect that no error occurred, meaning that the mcuxClEls_KeyDelete_Async operation was started.
137  }
139 
140  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_WaitForOperation(MCUXCLELS_ERROR_FLAGS_CLEAR)); // Wait for the mcuxClEls_KeyDelete_Async operation to complete.
141  // mcuxClEls_WaitForOperation is a flow-protected function: Check the protection token and the return value
143  {
144  return false;
145  }
147 
151  mcuxClEls_KeyProp_t kwkHelperKeyProp = {0};
152  kwkHelperKeyProp.bits.ukwk = MCUXCLELS_KEYPROPERTY_KWK_TRUE;
153  kwkHelperKeyProp.bits.ksize = MCUXCLELS_KEYPROPERTY_KEY_SIZE_256;
156  kwkHelperKeyProp.bits.kactv = MCUXCLELS_KEYPROPERTY_ACTIVE_TRUE;
157  kwkHelperKeyProp.bits.kbase = MCUXCLELS_KEYPROPERTY_BASE_SLOT;
158 
159  if(true != mcuxClExample_provision_key(helperKeyIdx, kwkHelperKeyProp))
160  {
161  return false;
162  }
163 
164  mcuxClEls_KeyImportOption_t wrapped_key_options = {0};
165  wrapped_key_options.bits.kfmt = MCUXCLELS_KEYIMPORT_KFMT_RFC3394;
166 
167  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_KeyImport_Async(wrapped_key_options, wrapped_key, key_size + ELS_RFC_PADDING_LENGTH, helperKeyIdx, targetKeyIdx));
168  // mcuxClEls_KeyImport_Async is a flow-protected function: Check the protection token and the return value
170  {
171  return false; // Expect that no error occurred, meaning that the mcuxClEls_KeyDelete_Async operation was started.
172  }
174 
175  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_WaitForOperation(MCUXCLELS_ERROR_FLAGS_CLEAR)); // Wait for the mcuxClEls_KeyDelete_Async operation to complete.
176  // mcuxClEls_WaitForOperation is a flow-protected function: Check the protection token and the return value
178  {
179  return false;
180  }
182 
186  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_KeyDelete_Async(helperKeyIdx));
187  // mcuxClEls_KeyDelete_Async is a flow-protected function: Check the protection token and the return value
189  {
190  return false; // Expect that no error occurred, meaning that the mcuxClEls_KeyDelete_Async operation was started.
191  }
193 
194  MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(result, token, mcuxClEls_WaitForOperation(MCUXCLELS_ERROR_FLAGS_CLEAR)); // Wait for the mcuxClEls_KeyDelete_Async operation to complete.
195  // mcuxClEls_WaitForOperation is a flow-protected function: Check the protection token and the return value
197  {
198  return false;
199  }
201  return true;
202 }
203 
204 #endif /* MCUXCLEXAMPLE_ELS_KEY_HELPER_H_ */
Top-level include file for the ELS driver.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_KeyImport_Async(mcuxClEls_KeyImportOption_t options, uint8_t const *pImportKey, size_t importKeyLength, mcuxClEls_KeyIndex_t wrappingKeyIdx, mcuxClEls_KeyIndex_t targetKeyIdx)
Imports a key from external storage to an internal key register.
#define MCUXCLELS_KEYPROPERTY_SECURE_TRUE
This value of mcuxClEls_KeyProp_t.upprot_sec indicates that the caller must be in secure mode to use ...
Definition: mcuxClEls_Types.h:158
#define MCUXCLELS_KEYPROPERTY_AES_TRUE
This value of mcuxClEls_KeyProp_t.uaes indicates that the key is an AES key.
Definition: mcuxClEls_Types.h:136
#define MCUXCLELS_KEYPROPERTY_KWK_TRUE
This value of mcuxClEls_KeyProp_t.ukwk indicates that the key is a Key Wrapping Key.
Definition: mcuxClEls_Types.h:140
uint32_t kbase
Status flag to indicate whether the key slot is a base slot or the second slot of a 256-bit key.
Definition: mcuxClEls_Types.h:240
uint32_t upprot_sec
Access restriction to TrustZone secure mode.
Definition: mcuxClEls_Types.h:269
uint32_t mcuxClEls_KeyIndex_t
Type for ELS keystore indices.
Definition: mcuxClEls_Types.h:221
#define MCUX_CSSL_FP_FUNCTION_CALLED(...)
Expectation of a called function.
Definition: mcuxCsslFlowProtection.h:730
uint32_t kactv
Status flag to indicate whether the key slot contains an active key or not.
Definition: mcuxClEls_Types.h:239
Provides the API for the CSSL flow protection mechanism.
#define MCUXCLELS_CIPHER_KEY_SIZE_AES_128
Size of an AES128 key: 128 bit (16 bytes)
Definition: mcuxClEls_Cipher.h:96
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_GetKeyProperties(mcuxClEls_KeyIndex_t keyIdx, mcuxClEls_KeyProp_t *pKeyProp)
Exports the properties of the keys stored in the ELS internal keystore.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_KeyDelete_Async(mcuxClEls_KeyIndex_t keyIdx)
Deletes a key from keystore at the given index.
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_WaitForOperation(mcuxClEls_ErrorHandling_t errorHandling)
Wait for an ELS operation and optionally clear the error status.
#define MCUXCLELS_KEYIMPORT_KFMT_RFC3394
Key format RFC3394 with shares in memory.
Definition: mcuxClEls_KeyManagement.h:83
uint32_t kfmt
Defines the key import format, one of MCUXCLELS_KEYIMPORT_KFMT_.
Definition: mcuxClEls_KeyManagement.h:147
#define MCUXCLELS_KEYPROPERTY_BASE_SLOT
This value of mcuxClEls_KeyProp_t.kbase indicates that the slot is the base slot of a 2-slot key.
Definition: mcuxClEls_Types.h:108
#define MCUXCLELS_STATUS_OK
No error occurred.
Definition: mcuxClEls_Types.h:170
uint32_t ksize
Key size.
Definition: mcuxClEls_Types.h:236
#define MCUX_CSSL_FP_FUNCTION_CALL_BEGIN(...)
Call a flow protected function and check the protection token.
Definition: mcuxCsslFlowProtection.h:576
uint32_t uaes
Usage permission for AES.
Definition: mcuxClEls_Types.h:258
uint32_t ukwk
Usage permission for key wrapping.
Definition: mcuxClEls_Types.h:260
#define MCUXCLELS_CIPHER_KEY_SIZE_AES_256
Size of an AES192 key: 256 bit (32 bytes)
Definition: mcuxClEls_Cipher.h:98
struct mcuxClEls_KeyProp_t::@41 bits
Access mcuxClEls_KeyProp_t bit-wise.
Type for ELS key store key properties.
Definition: mcuxClEls_Types.h:224
Command option bit field for mcuxClEls_KeyImport_Async.
Definition: mcuxClEls_KeyManagement.h:136
#define MCUXCLELS_KEYPROPERTY_ACTIVE_TRUE
This value of mcuxClEls_KeyProp_t.kactv indicates that the slot contains an active key.
Definition: mcuxClEls_Types.h:106
Definition of function identifiers for the flow protection mechanism.
struct mcuxClEls_KeyImportOption_t::@39 bits
Access mcuxClEls_KeyImportOption_t bit-wise.
#define MCUXCLELS_STATUS_OK_WAIT
An _Async function successfully started an ELS command. Call mcuxClEls_WaitForOperation to complete i...
Definition: mcuxClEls_Types.h:171
#define MCUXCLELS_CIPHER_INTERNAL_KEY
Set this option at mcuxClEls_CipherOption_t.extkey to use a key located in ELS keystore privded by ke...
Definition: mcuxClEls_Cipher.h:74
#define MCUXCLELS_ERROR_FLAGS_CLEAR
Set this option at mcuxClEls_ErrorHandling_t to clear all ELS error flags.
Definition: mcuxClEls_Common.h:137
#define MCUXCLELS_KEYPROPERTY_KEY_SIZE_256
This value of mcuxClEls_KeyProp_t.ksize indicates a 256 bit key.
Definition: mcuxClEls_Types.h:102
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_Reset_Async(mcuxClEls_ResetOption_t options)
Perform a synchronous reset of the ELS.
#define MCUX_CSSL_FP_FUNCTION_CALL_END(...)
End a function call section started by MCUX_CSSL_FP_FUNCTION_CALL_BEGIN.
Definition: mcuxCsslFlowProtection.h:611
#define MCUXCLELS_KEYPROPERTY_PRIVILEGED_TRUE
This value of mcuxClEls_KeyProp_t.upprot_priv indicates that the caller must be in privileged mode to...
Definition: mcuxClEls_Types.h:156
uint32_t upprot_priv
Access restriction to privileged mode.
Definition: mcuxClEls_Types.h:268