MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClEls_Ecc.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 
26 #ifndef MCUXCLELS_ECC_H_
27 #define MCUXCLELS_ECC_H_
28 
29 #include <mcuxClConfig.h> // Exported features flags header
30 #include <mcuxClEls_Common.h> // Common types & functionality
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
44 /**********************************************
45  * CONSTANTS
46  **********************************************/
60 #define MCUXCLELS_ECC_VALUE_HASHED ((uint32_t) 0u<< 0u)
61 #define MCUXCLELS_ECC_VALUE_NOT_HASHED ((uint32_t) 1u<< 0u)
62 #define MCUXCLELS_ECC_VALUE_RTF ((uint32_t) 1u<< 1u)
63 #define MCUXCLELS_ECC_VALUE_NO_RTF ((uint32_t) 0u<< 1u)
64 
74 #define MCUXCLELS_KEYGEN_VALUE_SIGN_PUBLICKEY ((uint32_t) 1u<< 0u)
75 #define MCUXCLELS_KEYGEN_VALUE_TYPE_SIGN ((uint32_t) 0u<< 1u)
76 #define MCUXCLELS_KEYGEN_VALUE_TYPE_KEYEXCHANGE ((uint32_t) 1u<< 1u)
77 #define MCUXCLELS_KEYGEN_VALUE_DETERMINISTIC ((uint32_t) 0u<< 2u)
78 #define MCUXCLELS_KEYGEN_VALUE_RANDOM ((uint32_t) 1u<< 2u)
79 #define MCUXCLELS_KEYGEN_VALUE_GEN_PUB_KEY ((uint32_t) 0u<< 3u)
80 #define MCUXCLELS_KEYGEN_VALUE_NO_PUB_KEY ((uint32_t) 1u<< 3u)
81 #define MCUXCLELS_KEYGEN_VALUE_NO_RANDOM_DATA ((uint32_t) 0u<< 5u)
82 #define MCUXCLELS_KEYGEN_VALUE_USE_RANDOM_DATA ((uint32_t) 1u<< 5u)
83 
93 #define MCUXCLELS_ECC_HASHED ((uint32_t) 0U)
94 #define MCUXCLELS_ECC_NOT_HASHED ((uint32_t) 1U)
95 
96 #define MCUXCLELS_ECC_RTF ((uint32_t) 1U)
97 #define MCUXCLELS_ECC_NO_RTF ((uint32_t) 0U)
98 
108 #define MCUXCLELS_ECC_PUBLICKEY_SIGN_ENABLE 1U
109 #define MCUXCLELS_ECC_PUBLICKEY_SIGN_DISABLE 0U
110 
111 #define MCUXCLELS_ECC_OUTPUTKEY_SIGN 0U
112 #define MCUXCLELS_ECC_OUTPUTKEY_KEYEXCHANGE 1U
113 
114 #define MCUXCLELS_ECC_OUTPUTKEY_DETERMINISTIC 0U
115 #define MCUXCLELS_ECC_OUTPUTKEY_RANDOM 1U
116 
117 #define MCUXCLELS_ECC_GEN_PUBLIC_KEY 0U
118 #define MCUXCLELS_ECC_SKIP_PUBLIC_KEY 1U
119 
121 #define MCUXCLELS_ECC_NO_RANDOM_DATA 0U
122 #define MCUXCLELS_ECC_INCLUDE_RANDOM_DATA 1U
123 
134 #define MCUXCLELS_ECC_REVERSEFETCH_ENABLE (0x01U)
135 #define MCUXCLELS_ECC_REVERSEFETCH_DISABLE (0x00U)
136 
137 #ifdef MCUXCL_FEATURE_ELS_PUK_INTERNAL_BIT
138 #define MCUXCLELS_ECC_EXTKEY_EXTERNAL (0x01U)
139 #define MCUXCLELS_ECC_EXTKEY_INTERNAL (0x00U)
140 #endif /* MCUXCL_FEATURE_ELS_PUK_INTERNAL_BIT */
141 
151 #define MCUXCLELS_ECC_PUBLICKEY_SIZE ((size_t) 64U)
152 #define MCUXCLELS_ECC_SIGNATURE_SIZE ((size_t) 64U)
153 #define MCUXCLELS_ECC_SIGNATURE_R_SIZE ((size_t) 32U)
154  /* mcuxClEls_Ecc_Macros */
161 
162 
163 /**********************************************
164  * TYPEDEFS
165  **********************************************/
177 typedef uint8_t mcuxClEls_EccByte_t;
178 
183 typedef union
184 {
185  struct
186  {
187  uint32_t value;
188  } word;
189  struct
190  {
191  uint32_t echashchl :1;
192  uint32_t signrtf :1;
193  uint32_t :2;
194  uint32_t revf :1;
195  uint32_t :27;
196  } bits;
198 
203 typedef union
204 {
205  struct
206  {
207  uint32_t value;
208  } word;
209  struct
210  {
211  uint32_t echashchl :1;
212  uint32_t :3;
213  uint32_t revf :1;
214 #ifdef MCUXCL_FEATURE_ELS_PUK_INTERNAL_BIT
215  uint32_t :8;
216  uint32_t extkey :1;
217  uint32_t :18;
218 #else
219  uint32_t :27;
220 #endif /* MCUXCL_FEATURE_ELS_PUK_INTERNAL_BIT */
221  } bits;
223 
228 typedef union
229 {
230  struct
231  {
232  uint32_t value;
233  } word;
234  struct
235  {
236  uint32_t kgsign :1;
237  uint32_t kgtypedh :1;
238  uint32_t kgsrc :1;
239  uint32_t skip_pbk :1;
240  uint32_t revf :1;
241  uint32_t kgsign_rnd :1;
242  uint32_t :26;
243  } bits;
245 
250 typedef union
251 {
252  struct
253  {
254  uint32_t value;
255  } word;
256  struct
257  {
258  uint32_t :4;
259  uint32_t revf :1;
260  uint32_t :8;
261  uint32_t extkey :1;
262  uint32_t :18;
263  } bits;
265  /* mcuxClEls_Ecc_Types */
269 
270 
271 /**********************************************
272  * FUNCTIONS
273  **********************************************/
322  mcuxClEls_KeyIndex_t signingKeyIdx,
323  mcuxClEls_KeyIndex_t privateKeyIdx,
324  mcuxClEls_KeyProp_t generatedKeyProperties,
325  uint8_t const * pRandomData,
326  uint8_t * pPublicKey
327  );
328 
362  mcuxClEls_KeyIndex_t privateKeyIdx,
363  uint8_t const * pPublicKey,
364  mcuxClEls_KeyIndex_t sharedSecretIdx,
365  mcuxClEls_KeyProp_t sharedSecretProperties
366  );
367 
368 #ifdef MCUXCL_FEATURE_ELS_PUK_INTERNAL
369 
390 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_EccKeyExchangeInt_Async)
391 MCUXCLELS_API MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClEls_Status_t) mcuxClEls_EccKeyExchangeInt_Async(
392  mcuxClEls_KeyIndex_t privateKeyIdx,
393  mcuxClEls_KeyIndex_t publicKeyIdx,
394  mcuxClEls_KeyIndex_t sharedSecretIdx,
395  mcuxClEls_KeyProp_t sharedSecretProperties
396  );
397 #endif /* MCUXCL_FEATURE_ELS_PUK_INTERNAL */
398 
446  mcuxClEls_KeyIndex_t keyIdx,
447  uint8_t const * pInputHash,
448  uint8_t const * pInputMessage,
449  size_t inputMessageLength,
450  uint8_t * pOutput
451  );
452 
508  uint8_t const * pInputHash,
509  uint8_t const * pInputMessage,
510  size_t inputMessageLength,
511  uint8_t const * pSignatureAndPubKey,
512  uint8_t * pOutput
513  );
514 
515 #ifdef MCUXCL_FEATURE_ELS_PUK_INTERNAL
516 
568 MCUX_CSSL_FP_FUNCTION_DECL(mcuxClEls_EccVerifyInt_Async)
569 MCUXCLELS_API MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClEls_Status_t) mcuxClEls_EccVerifyInt_Async(
571  mcuxClEls_KeyIndex_t publicKeyIdx,
572  uint8_t const * pInputHash,
573  uint8_t const * pInputMessage,
574  size_t inputMessageLength,
575  uint8_t const * pSignature,
576  uint8_t * pOutput
577  );
578 
579 #endif /* MCUXCL_FEATURE_ELS_PUK_INTERNAL */
580  /* mcuxClEls_Ecc_Functions */
584  /* mcuxClEls_Ecc */
588 
589 #ifdef __cplusplus
590 } /* extern "C" */
591 #endif
592 
593 #endif /* MCUXCLELS_ECC_H_ */
uint32_t mcuxClEls_Status_t
Type for ELS driver status codes.
Definition: mcuxClEls_Types.h:211
uint32_t skip_pbk
Define if generating a public key.
Definition: mcuxClEls_Ecc.h:239
ELS header for common functionality.
Command option bit field for mcuxClEls_EccKeyExchange_Async, for internal use only.
Definition: mcuxClEls_Ecc.h:250
Command option bit field for mcuxClEls_EccKeyGen_Async Bit field to configure mcuxClEls_EccKeyGenOpti...
Definition: mcuxClEls_Ecc.h:228
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_EccVerify_Async(mcuxClEls_EccVerifyOption_t options, uint8_t const *pInputHash, uint8_t const *pInputMessage, size_t inputMessageLength, uint8_t const *pSignatureAndPubKey, uint8_t *pOutput)
Verifies an ECDSA signature of a given message.
uint32_t value
Accesses the bit field as a full word; initialize with a combination of constants from MCUXCLELS_KEYG...
Definition: mcuxClEls_Ecc.h:232
uint8_t mcuxClEls_EccByte_t
Data type for ECC parameters in ELS format.
Definition: mcuxClEls_Ecc.h:177
uint32_t revf
This field is managed internally.
Definition: mcuxClEls_Ecc.h:213
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_EccSign_Async(mcuxClEls_EccSignOption_t options, mcuxClEls_KeyIndex_t keyIdx, uint8_t const *pInputHash, uint8_t const *pInputMessage, size_t inputMessageLength, uint8_t *pOutput)
Generates an ECDSA signature of a given message.
uint32_t value
Access the bit field as a full word; initialize with a combination of constants from MCUXCLELS_ECC (S...
Definition: mcuxClEls_Ecc.h:207
uint32_t revf
This field is managed internally.
Definition: mcuxClEls_Ecc.h:240
uint32_t kgsrc
Define if the output key is deterministic or random.
Definition: mcuxClEls_Ecc.h:238
Type for ELS key store key properties.
Definition: mcuxClEls_Types.h:224
uint32_t value
Accesses the bit field as a full word.
Definition: mcuxClEls_Ecc.h:254
#define MCUX_CSSL_FP_FUNCTION_DECL(...)
Declaration of a flow protected function.
Definition: mcuxCsslFlowProtection.h:125
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_EccKeyGen_Async(mcuxClEls_EccKeyGenOption_t options, mcuxClEls_KeyIndex_t signingKeyIdx, mcuxClEls_KeyIndex_t privateKeyIdx, mcuxClEls_KeyProp_t generatedKeyProperties, uint8_t const *pRandomData, uint8_t *pPublicKey)
Generates an ECC key pair on the NIST P-256 curve.
#define MCUXCLELS_API
Marks a function as a public API function of the mcuxClEls component.
Definition: mcuxClEls_Common.h:47
uint32_t mcuxClEls_KeyIndex_t
Type for ELS keystore indices.
Definition: mcuxClEls_Types.h:221
uint32_t kgsign
Define if signing the output public key.
Definition: mcuxClEls_Ecc.h:236
uint32_t echashchl
Define type of input, plain message or hash of message.
Definition: mcuxClEls_Ecc.h:191
uint32_t kgsign_rnd
Define if using user provided random data for the signature.
Definition: mcuxClEls_Ecc.h:241
uint32_t kgtypedh
Define the usage of the output key.
Definition: mcuxClEls_Ecc.h:237
#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
Access the bit field as a full word; initialize with a combination of constants from MCUXCLELS_ECC (S...
Definition: mcuxClEls_Ecc.h:187
uint32_t echashchl
Define type of input, plain message or hash of message.
Definition: mcuxClEls_Ecc.h:211
Command option bit field for mcuxClEls_EccVerify_Async Bit field to configure mcuxClEls_EccVerifyOpti...
Definition: mcuxClEls_Ecc.h:203
Command option bit field for mcuxClEls_EccSign_Async Bit field to configure mcuxClEls_EccSign_Async.
Definition: mcuxClEls_Ecc.h:183
MCUXCLELS_API mcuxClEls_Status_t mcuxClEls_EccKeyExchange_Async(mcuxClEls_KeyIndex_t privateKeyIdx, uint8_t const *pPublicKey, mcuxClEls_KeyIndex_t sharedSecretIdx, mcuxClEls_KeyProp_t sharedSecretProperties)
Performs a Diffie-Hellman key exchange with an internal ECC private key and an external ECC public ke...
uint32_t signrtf
Define if signing the Run-Time Fingerprint.
Definition: mcuxClEls_Ecc.h:192
uint32_t extkey
This field is managed internally.
Definition: mcuxClEls_Ecc.h:261
uint32_t revf
This field is managed internally.
Definition: mcuxClEls_Ecc.h:194
uint32_t revf
This field is managed internally.
Definition: mcuxClEls_Ecc.h:259