MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClEcc_Functions

Defines all functions of mcuxClEcc. More...

Functions

mcuxClEcc_Status_t mcuxClEcc_KeyGen (mcuxClSession_Handle_t pSession, const mcuxClEcc_KeyGen_Param_t *pParam)
 implements ECDSA key generation. More...
 
mcuxClEcc_Status_t mcuxClEcc_Sign (mcuxClSession_Handle_t pSession, const mcuxClEcc_Sign_Param_t *pParam)
 implements ECDSA signature generation. More...
 
mcuxClEcc_Status_t mcuxClEcc_Verify (mcuxClSession_Handle_t pSession, const mcuxClEcc_Verify_Param_t *pParam)
 implements ECDSA signature verification. More...
 
mcuxClEcc_Status_t mcuxClEcc_PointMult (mcuxClSession_Handle_t pSession, const mcuxClEcc_PointMult_Param_t *pParam)
 implements ECC point multiplication. More...
 
mcuxClEcc_Status_t mcuxClEcc_Mont_DhKeyGeneration (mcuxClSession_Handle_t pSession, mcuxClKey_Type_t type, mcuxClKey_Protection_t protection, mcuxClKey_Handle_t privKey, uint8_t *pPrivData, uint32_t *const pPrivDataLength, mcuxClKey_Handle_t pubKey, uint8_t *pPubData, uint32_t *const pPubDataLength)
 implements ECC key pair generation step for a MontDh key agreement according to rfc7748. More...
 
mcuxClEcc_Status_t mcuxClEcc_Mont_DhKeyAgreement (mcuxClSession_Handle_t pSession, mcuxClKey_Handle_t key, mcuxClKey_Handle_t otherKey, uint8_t *pOut, uint32_t *const pOutLength)
 implements ECC key agreement according to rfc7748. More...
 
mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateKeyPair (mcuxClSession_Handle_t pSession, const mcuxClEcc_EdDSA_GenerateKeyPairDescriptor_t *mode, mcuxClKey_Handle_t privKey, mcuxClKey_Handle_t pubKey)
 This function implements the EdDSA key pair generation for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.5 and 5.2.5 of https://datatracker.ietf.org/doc/html/rfc8032). More...
 
mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateSignature (mcuxClSession_Handle_t pSession, mcuxClKey_Handle_t key, const mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t *mode, const uint8_t *pIn, uint32_t inSize, uint8_t *pSignature, uint32_t *const pSignatureSize)
 This function implements the EdDSA signature generation for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.6 and 5.2.6 of https://datatracker.ietf.org/doc/html/rfc8032). More...
 
mcuxClEcc_Status_t mcuxClEcc_EdDSA_VerifySignature (mcuxClSession_Handle_t session, mcuxClKey_Handle_t key, const mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t *mode, const uint8_t *pIn, uint32_t inSize, const uint8_t *pSignature, uint32_t signatureSize)
 This function implements the EdDSA signature verification for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.7 and 5.2.7 of https://datatracker.ietf.org/doc/html/rfc8032). More...
 
mcuxClEcc_Status_t mcuxClEcc_EdDSA_InitPrivKeyInputMode (mcuxClSession_Handle_t pSession, mcuxClEcc_EdDSA_GenerateKeyPairDescriptor_t *mode, const uint8_t *pPrivKey)
 This function initializes an EdDSA mode descriptor for EdDSA key pair generation with private key input. More...
 
mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateProtocolDescriptor (mcuxClSession_Handle_t pSession, const mcuxClEcc_EdDSA_DomainParams_t *pDomainParams, mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t *pProtocolDescriptor, uint32_t phflag, mcuxCl_InputBuffer_t pContext, uint32_t contextLen)
 This function implements the protocol descriptor generation for Ed25519ctx, Ed25519ph, Ed448 and Ed448ph. More...
 

Detailed Description

Defines all functions of mcuxClEcc.

Function Documentation

◆ mcuxClEcc_KeyGen()

mcuxClEcc_Status_t mcuxClEcc_KeyGen ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_KeyGen_Param_t pParam 
)

implements ECDSA key generation.

Return values
MCUXCLECC_STATUS_OKif private key and public key are generated successfully;
MCUXCLECC_STATUS_INVALID_PARAMSif parameters are invalid;
MCUXCLECC_STATUS_RNG_ERRORif random number (DRBG / PRNG) error (unexpected behavior);
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Attention
This function uses DRBG and PRNG. Caller needs to check if DRBG and PRNG are ready.
Parameters
[in]pSessionpointer to mcuxClSession_Descriptor.
[in]pParampointer to ECDSA Key Generation parameter structure.

◆ mcuxClEcc_Sign()

mcuxClEcc_Status_t mcuxClEcc_Sign ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_Sign_Param_t pParam 
)

implements ECDSA signature generation.

Return values
MCUXCLECC_STATUS_OKif signature is generated successfully;
MCUXCLECC_STATUS_INVALID_PARAMSif parameters are invalid;
MCUXCLECC_STATUS_RNG_ERRORif random number (DRBG / PRNG) error (unexpected behavior);
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Attention
This function uses DRBG and PRNG. Caller needs to check if DRBG and PRNG are ready.
Parameters
[in]pSessionpointer to mcuxClSession_Descriptor.
[in]pParampointer to ECDSA Sign parameter structure.

◆ mcuxClEcc_Verify()

mcuxClEcc_Status_t mcuxClEcc_Verify ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_Verify_Param_t pParam 
)

implements ECDSA signature verification.

Return values
MCUXCLECC_STATUS_OKif ECDSA Signature is valid;
MCUXCLECC_STATUS_INVALID_SIGNATUREif ECDSA Signature is invalid;
MCUXCLECC_STATUS_INVALID_PARAMSif parameters are invalid;
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Parameters
[in]pSessionpointer to mcuxClSession_Descriptor.
[in]pParampointer to ECDSA Verify parameter structure.

◆ mcuxClEcc_PointMult()

mcuxClEcc_Status_t mcuxClEcc_PointMult ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_PointMult_Param_t pParam 
)

implements ECC point multiplication.

This API performs elliptic curve point multiplication on the given elliptic curve in short Weierstrass form. This API does not check if the curve parameters and the given point are valid or not. Invalid curve parameters or point might cause the return of MCUXCLECC_STATUS_INVALID_PARAMS, invalid result, and unexpected behavior (e.g., the return of MCUXCLECC_STATUS_FAULT_ATTACK).

Parameters
[in]pSessionpointer to mcuxClSession_Descriptor.
[in]pParampointer to ECC point multiplication parameter structure.
Parameter properties
pParam.curveParam.pG
the base point is not used in this API. This pointer can be left unspecified.
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKif point multiplication is calculated successfully, and the result is not the neutral point;
MCUXCLECC_STATUS_INVALID_PARAMSif parameters are invalid;
MCUXCLECC_STATUS_NEUTRAL_POINTif result is the neutral point;
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Attention
This function uses PRNG. Caller needs to check if PRNG is ready.

◆ mcuxClEcc_Mont_DhKeyGeneration()

mcuxClEcc_Status_t mcuxClEcc_Mont_DhKeyGeneration ( mcuxClSession_Handle_t  pSession,
mcuxClKey_Type_t  type,
mcuxClKey_Protection_t  protection,
mcuxClKey_Handle_t  privKey,
uint8_t *  pPrivData,
uint32_t *const  pPrivDataLength,
mcuxClKey_Handle_t  pubKey,
uint8_t *  pPubData,
uint32_t *const  pPubDataLength 
)

implements ECC key pair generation step for a MontDh key agreement according to rfc7748.

This API performs elliptic curve key generation of the private key and calculates corresponding public key for MontDh key agreement This API does not check if the curve parameters are correct. This API might return MCUXCLECC_STATUS_RNG_ERROR when RNG behave in unexpected way Unexpected behavior will return MCUXCLECC_STATUS_FAULT_ATTACK.

Parameters
[in]pSessionmcuxClSession_Descriptor structure
[in]typetype structure specifying requested key type to be generated. Also contains domain parameters
[in]protection#mcuxClKey_Protection structure
[out]privKeyprivate key handling structure
[out]pPrivDatabuffer for private key of the MCUXCLECC_MONT_CURVE25519/448_SIZE_PRIVATEKEY length
[out]pPrivDataLengthprivate key length
[out]pubKeypublic key handling structure
[out]pPubDatabuffer for public key x-coordinate of MCUXCLECC_MONT_CURVE25519/448_SIZE_PUBLICKEY length
[out]pPubDataLengthpublic key x-coordinate length
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_ and MCUXCLECC_MONTDH_STATUS_)
Return values
MCUXCLECC_STATUS_OKif key generation correctly calculate private and public keys, public key does not belong to the small subgroup.
MCUXCLECC_STATUS_RNG_ERRORif RNG return an error.
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Attention
This function uses PRNG. Caller needs to check if PRNG is ready.
Examples
mcuxClEcc_Mont_Curve25519_example.c, and mcuxClEcc_Mont_Curve448_example.c.

◆ mcuxClEcc_Mont_DhKeyAgreement()

mcuxClEcc_Status_t mcuxClEcc_Mont_DhKeyAgreement ( mcuxClSession_Handle_t  pSession,
mcuxClKey_Handle_t  key,
mcuxClKey_Handle_t  otherKey,
uint8_t *  pOut,
uint32_t *const  pOutLength 
)

implements ECC key agreement according to rfc7748.

This API performs elliptic curve key agreement to compute shared secret between two parties using the function X25519 This API does not check if the curve parameters are correct. This API might return MCUXCLECC_STATUS_RNG_ERROR when RNG behave in unexpected way This API might return MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUP if generated public key lies in the small subgroup Unexpected behavior will return MCUXCLECC_STATUS_FAULT_ATTACK.

Parameters
[in]pSessionpointer to mcuxClSession_Descriptor.
[in]keyprivate key handling structure
[in]otherKeypublic key handling structure
[out]pOutbuffer for shared secret of length MCUXCLECC_MONT_CURVE25519/448_SIZE_SHAREDSECRET
[out]pOutLengthshared secret length
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_ and MCUXCLECC_MONTDH_STATUS_)
Return values
MCUXCLECC_STATUS_OKif key generation correctly calculate private and public keys, public key does not belong to the small subgroup.
MCUXCLECC_STATUS_RNG_ERRORif RNG return an error.
MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUPif calculated public key lies in small subgroup.
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.
Attention
This function uses PRNG. Caller needs to check if PRNG is ready.
Examples
mcuxClEcc_Mont_Curve25519_example.c, and mcuxClEcc_Mont_Curve448_example.c.

◆ mcuxClEcc_EdDSA_GenerateKeyPair()

mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateKeyPair ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_EdDSA_GenerateKeyPairDescriptor_t mode,
mcuxClKey_Handle_t  privKey,
mcuxClKey_Handle_t  pubKey 
)

This function implements the EdDSA key pair generation for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.5 and 5.2.5 of https://datatracker.ietf.org/doc/html/rfc8032).

For an M byte private key d, which is either generated internally at random or passed as input, this function calculates the private key hash H(d)=(h0,...,h{2b-1}) and deduces and returns

  • the secret integer s
  • the second half (hb,...,h{2b-1}) of the private key hash
  • the public key Qenc=(s*G)enc where G is the base point.

This API does not check if the curve parameters are correct. This API might return MCUXCLECC_STATUS_RNG_ERROR when RNG behave in unexpected way Unexpected behavior will return MCUXCLECC_STATUS_FAULT_ATTACK.

Parameters
[in]pSessionHandle for the current CL session
[in]modeMode descriptor specifying the EdDSA GenerateKeyPair variant
[in/out]privKey Key handle for the private key.
[in/out]pubKey Key handle for the public key.
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKprivate key data and public key have been generated successfully
MCUXCLECC_STATUS_RNG_ERRORrandom number generation (DRBG / PRNG) error (unexpected behavior)
MCUXCLECC_STATUS_FAULT_ATTACKfault attack (unexpected behavior) is detected
Examples
mcuxClEcc_EdDSA_Ed25519_example.c, mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, and mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c.

◆ mcuxClEcc_EdDSA_GenerateSignature()

mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateSignature ( mcuxClSession_Handle_t  pSession,
mcuxClKey_Handle_t  key,
const mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t mode,
const uint8_t *  pIn,
uint32_t  inSize,
uint8_t *  pSignature,
uint32_t *const  pSignatureSize 
)

This function implements the EdDSA signature generation for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.6 and 5.2.6 of https://datatracker.ietf.org/doc/html/rfc8032).

For given hash prefix prefix (either dom2(x, y) or dom4(x, y) according to the chosen EdDSA variant; see Sections 5.1 and 5.2 of https://datatracker.ietf.org/doc/html/rfc8032), a message digest m', i.e. either the message itself for PureEdDSA or the message hash for HashEdDSA (see Section 4 of https://datatracker.ietf.org/doc/html/rfc8032), the signing keys s and (hb,...,h{2b-1}) derived from the private key d (see mcuxClEcc_EdDSA_GenerateKeyPair) and a public key Qenc, this function calculates an EdDSA signature (Renc,S), where Renc and S are given by

- Renc = (r*G)enc
- S = r+H(prefix||Renc||Qenc||m')*s mod n

where the secret scalar r is given by r=H(prefix||(hb,...,h{2b-1})||m') and G is the base point.

This API does not check if the curve parameters are correct. This API might return MCUXCLECC_STATUS_RNG_ERROR when RNG behave in unexpected way Unexpected behavior will return MCUXCLECC_STATUS_FAULT_ATTACK.

Parameters
[in]pSessionHandle for the current CL session
[in]keyKey handle for private key related data which a.o. references the secret signing keys s and (hb,...,h{2b-1}) as well as the public key Qenc.
[in]modeMode descriptor specifying the EdDSA variant
[in]pInPointer to message digest m'
[in]inSizeSize of message digest m'
[out]pSignaturePointer to buffer where the signature (Renc,S) will be stored
[out]pSignatureSizeWill be set to the number of bytes of data that have been written to the pSignature buffer
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKsignature generation was successful
MCUXCLECC_STATUS_RNG_ERRORrandom number generation (DRBG / PRNG) error (unexpected behavior)
MCUXCLECC_STATUS_FAULT_ATTACKfault attack (unexpected behavior) is detected
Examples
mcuxClEcc_EdDSA_Ed25519_example.c, mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, and mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c.

◆ mcuxClEcc_EdDSA_VerifySignature()

mcuxClEcc_Status_t mcuxClEcc_EdDSA_VerifySignature ( mcuxClSession_Handle_t  session,
mcuxClKey_Handle_t  key,
const mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t mode,
const uint8_t *  pIn,
uint32_t  inSize,
const uint8_t *  pSignature,
uint32_t  signatureSize 
)

This function implements the EdDSA signature verification for Ed25519 and Ed448 as specified in rfc8032 (see Sections 5.1.7 and 5.2.7 of https://datatracker.ietf.org/doc/html/rfc8032).

For given hash prefix prefix (either dom2(x, y) or dom4(x, y) according to the chosen EdDSA variant; see Sections 5.1 and 5.2 of https://datatracker.ietf.org/doc/html/rfc8032), a message digest m', i.e. either the message itself for PureEdDSA or the message hash for HashEdDSA (see Section 4 of https://datatracker.ietf.org/doc/html/rfc8032), and a public key Qenc, this function:

  • verifies the public key Qenc
  • verifies that the signature component S satisfies S in [0,n-1]
  • verifies if the following signature equation holds:
    • h*S*G=h*R+h*H(prefix||Renc||Qenc||m')*Q

This API does not check if the curve parameters are correct. This API might return MCUXCLECC_STATUS_RNG_ERROR when RNG behave in unexpected way Unexpected behavior will return MCUXCLECC_STATUS_FAULT_ATTACK.

Parameters
[in]sessionHandle for the current CL session
[in]keyKey handle for public key Qenc
[in]modeMode descriptor specifying the EdDSA variant
[in]pInPointer to message digest m'
[in]inSizeSize of message digest m'
[in]pSignaturePointer to buffer containing the signature (Renc,S)
[in]signatureSizeNumber of bytes of data in the pSignature buffer
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKsignature verification passed
MCUXCLECC_STATUS_INVALID_SIGNATUREEdDSA signature is invalid
MCUXCLECC_STATUS_INVALID_PARAMSinput parameters are invalid
MCUXCLECC_STATUS_FAULT_ATTACKfault attack (unexpected behavior) is detected
Examples
mcuxClEcc_EdDSA_Ed25519_example.c, mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c, and mcuxClEcc_EdDSA_VerifySignature_Ed25519_example.c.

◆ mcuxClEcc_EdDSA_InitPrivKeyInputMode()

mcuxClEcc_Status_t mcuxClEcc_EdDSA_InitPrivKeyInputMode ( mcuxClSession_Handle_t  pSession,
mcuxClEcc_EdDSA_GenerateKeyPairDescriptor_t mode,
const uint8_t *  pPrivKey 
)

This function initializes an EdDSA mode descriptor for EdDSA key pair generation with private key input.

Parameters
[in]pSessionHandle for the current CL session
[in/out]mode Pointer to mode descriptor to be initialized for EdDSA key pair generation with private key input
[in]pPrivKeyPointer to private key input
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKEdDSA mode descriptor has been initialized successfully
MCUXCLECC_STATUS_FAULT_ATTACKfault attack (unexpected behavior) is detected
Examples
mcuxClEcc_EdDSA_Ed25519ctx_example.c, mcuxClEcc_EdDSA_Ed25519ph_example.c, and mcuxClEcc_EdDSA_GenerateSignature_Ed25519_example.c.

◆ mcuxClEcc_EdDSA_GenerateProtocolDescriptor()

mcuxClEcc_Status_t mcuxClEcc_EdDSA_GenerateProtocolDescriptor ( mcuxClSession_Handle_t  pSession,
const mcuxClEcc_EdDSA_DomainParams_t pDomainParams,
mcuxClEcc_EdDSA_SignatureProtocolDescriptor_t pProtocolDescriptor,
uint32_t  phflag,
mcuxCl_InputBuffer_t  pContext,
uint32_t  contextLen 
)

This function implements the protocol descriptor generation for Ed25519ctx, Ed25519ph, Ed448 and Ed448ph.

Parameters
[in]pSessionpointer to mcuxClSession_Descriptor
[in]pDomainParamsPointer to domain parameters of the used curve
[in]pProtocolDescriptorProtocol descriptor specifying the EdDSA variant
[in]phflagOption whether pre-hashing is enabled
[in]pContextUser input context for the hash prefix
[in]contextLenLength of the context
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKsignature verification passed
MCUXCLECC_STATUS_FAULT_ATTACKfault attack (unexpected behavior) is detected
Examples
mcuxClEcc_EdDSA_Ed25519ctx_example.c, and mcuxClEcc_EdDSA_Ed25519ph_example.c.