MCUX CLNS
MCUX Crypto Library Normal Secure
mcuxClEcc_Macros

Defines all macros of mcuxClEcc. More...

Modules

 MCUXCLECC_STATUS_
 mcuxClEcc return code definitions
 
 MCUXCLECC_MONTDH_STATUS_
 mcuxClEcc_Mont return code definitions
 

Typedefs

typedef uint32_t mcuxClEcc_Status_t
 Type for mcuxClEcc component return codes. More...
 

Functions

typedef MCUX_CSSL_FP_PROTECTED_TYPE (mcuxClEcc_Status_t) mcuxClEcc_Status_Protected_t
 Deprecated type for mcuxClEcc component return codes. More...
 

Detailed Description

Defines all macros of mcuxClEcc.

Typedef Documentation

◆ mcuxClEcc_Status_t

typedef uint32_t mcuxClEcc_Status_t

Type for mcuxClEcc component return codes.

Function Documentation

◆ MCUX_CSSL_FP_PROTECTED_TYPE()

typedef MCUX_CSSL_FP_PROTECTED_TYPE ( mcuxCsslParamIntegrity_Checksum_t  )

Deprecated type for mcuxClEcc component return codes.

Deprecated type for mcuxClEcc component return codes.

Destroy a Crypto Library session.

Clean up a Crypto Library session.

Set the RTF option in a Crypto Library session.

RSA key generation of private plain key operation.

Generates an RSA key in CRT format.

RSA verify operation.

This function updates the entropy input pointer in a TEST_MODE descriptor.

Non-cryptographic PRNG data generation function.

Non-cryptographic PRNG initialization function.

Random data generator security strength check.

Random data generator self-test function.

Random data generator uninitialization function.

Random data generation function.

Random data generator reseed function.

Randomize UPTR table and operands in PKC workarea.

Securely calculates modular exponentiation.

Finalize a MAC generation for a multipart MAC computation.

Data processing for a multipart MAC computation.

Initialization for a multipart MAC computation.

Set the requested key properties of the destination key.

Flush key from destination which can be a key slot of coprocessor or memory buffer.

Load key into destination memory buffer.

Load key into destination key slot of a coprocessor.

Configures they protection mechanism for to the given key handle.

Establishes a key pair link between a private and public key handle.

Multi-part Hash computation finalization function.

Multi-part Hash processing function.

Multi-part Hash initialization function.

Writes random data from the ELS PRNG to the given buffer.

Returns one random word from the ELS PRNG.

Performs characterization of the ELS DTRNG.

Loads a configuration of the ELS DTRNG.

Encrypts data using the AES-CTR engine of the DRBG.

Encrypts data using the AES-ECB engine of the DRBG.

Performs a DRBG extraction.

Instantiates the DRBG in test mode.

Exports the properties of the keys stored in the ELS internal keystore.

Exports a key from an internal key register to external storage, using a wrapping key.

Imports a key from external storage to an internal key register.

Generates TLS session keys based on a master key and derivation data, according to the TLS 1.2 specification.

Generates a TLS master key based on a pre-master key and derivation data, according to the TLS 1.2 specification.

Derives a key using the NIST SP 800-108 CMAC-based Extract-and-Expand Key Derivation Function.

Derives a key using the HKDF (HMAC-based key derivation function) according to SP800-56C one-step approach with Sha2-256.

Verifies an ECDSA signature of a given message.

Generates an ECDSA signature of a given message.

Performs a Diffie-Hellman key exchange with an internal ECC private key and an external ECC public key.

Updates a reference CRC with the parameters of an ELS command.

Verifies a reference CRC against the computed ELS command CRC.

Get the current command CRC value.

Get the random start delay for AES based operations.

Set the random start delay for AES based operations.

Get the last ELS error code and level and optionally clear the error status.

Get the last ELS error code and optionally clear the error status.

Resets all error flags that have been set by a previous operation.

Await the completion of an ELS operation for a limited amount of time and optionally clear the error status.

Wait for an ELS operation and optionally clear the error status.

Set the interrupt status register, for debug and testing purposes.

Clear the interrupt status register.

Get interrupt enable flags.

Set interrupt enable flags.

Disable the ELS.

Perform a synchronous reset of the ELS.

Enables the ELS.

Determines the current state of the ELS.

AES-GCM final encryption/decryption.

AES-GCM update of the encrypted data.

AES-GCM update of the Additional Authenticated Data (AAD)

AES-GCM partial initialization.

Key type constructor.

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

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).

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).

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).

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

implements ECC key agreement according to rfc7748.

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

implements ECC point multiplication.

implements ECDSA signature verification.

implements ECDSA signature generation.

Multi-part encryption/decryption finalization function.

Multi-part encryption/decryption processing function.

Multi-part encryption/decryption initialization function.

Multi-part authenticated decryption verification function.

Multi-part authenticated encryption/decryption finalization function.

Multi-part authenticated encryption/decryption processing function for the associated data (authenticated only)

Multi-part authenticated encryption/decryption processing function for the regular data (authenticated and encrypted)

Multi-part authenticated encryption/decryption initialization function.

This function performs an authenticated encryption/decryption operation in one shot. The algorithm to be used will be determined based on the mode that is provided.

For example, to perform an AES authenticated encryption operation with a 128-bit key in GCM mode on padded data, the following needs to be provided:

  • AES128 key
  • AES GCM encryption mode
  • Nonce
  • Plain input data
  • Associated data
  • Output data buffer
  • Output length buffer, to store the amount of written bytes
  • Tag buffer, to store the authentication tag
Parameters
sessionHandle for the current CL session.
keyKey to be used to encrypt the data.
modeAEAD mode that should be used during the encryption operation.
[in]pNoncePointer to the buffer that contains the nonce.
nonceLengthNumber of bytes of nonce data in the nonce buffer.
[in]pInPointer to the input buffer that contains the plain data that need to be authenticated and encrypted.
inLengthNumber of bytes of plain data in the in buffer.
[in]pAdataAssociated data for the authenticated encryption operation. Data format depends on the chosen mode.
adataLengthNumber of bytes of associated data in the adata buffer.
[out]pOutPointer to the output buffer where the authenticated encrypted data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of authenticated encrypted data that have been written to the out buffer.
[out]pTagPointer to the output buffer where the tag needs to be written.
tagLengthNumber of bytes of tag data that will be written to the tag buffer.
Returns
status

This function performs the initialization for a multi part authenticated encryption/decryption operation. The algorithm to be used will be determined based on the key and mode that are provided.

Parameters
sessionHandle for the current CL session.
pContextAEAD context which is used to maintain the state and store other relevant information about the operation.
keyKey to be used to encrypt the data.
modeAEAD mode that should be used during the encryption/decryption operation.
[in]pNoncePointer to the buffer that contains the nonce.
nonceLengthNumber of bytes of nonce data in the nonce buffer.
inLengthNumber of bytes of plain data that will be processed.
adataLengthNumber of bytes of associated data that will be processed.
tagLengthNumber of bytes to be used for the authentication tag.
Returns
status

This function performs the processing of (a part of) a data stream for an authenticated encryption/decryption operation. The algorithm and key to be used will be determined based on the context that is provided.

Parameters
sessionHandle for the current CL session.
pContextAEAD context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that needs to be processed.
inLengthNumber of bytes of data in the in buffer.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the out buffer.
Returns
status

This function performs the processing of (a part of) an associated data stream for an authenticated encryption/decryption operation. The algorithm and key to be used will be determined based on the context that is provided.

Parameters
sessionHandle for the current CL session.
pContextAEAD context which is used to maintain the state and store other relevant information about the operation.
[in]pAdataAssociated data that needs to be proccessed.
adataLengthNumber of bytes of associated data in the adata buffer.
Returns
status

This function performs the finalization of an authenticated encryption or decryption operation and produces the authentication tag. The algorithm and key to be used will be determined based on the context that is provided.

Note: the taglength is already specified when the INIT function is called.

Parameters
sessionHandle for the current CL session.
pContextAEAD context which is used to maintain the state and store other relevant information about the operation.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the out buffer.
[out]pTagPointer to the output buffer where the tag needs to be written.
Returns
status

This function performs the finalization of an authenticated decryption operation and verifies the authentication tag. The algorithm and key to be used will be determined based on the context that is provided.

This function can be used as an alternative for mcuxClAead_finish when one also wants to perform the tag verification step.

Note: the taglength is already specified when the INIT function is called.

Parameters
sessionHandle for the current CL session.
pContextAEAD context which is used to maintain the state and store other relevant information about the operation.
[in]pTagPointer to the buffer that contains the tag.
[out]pOutPointer to the output buffer where the authenticated decrypted data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of authenticated decrypted data that have been written to the out buffer.
Returns
status

This function performs the initialization for a multi part encryption/decryption operation. The algorithm to be used will be determined based on the mode that is provided.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
keyKey to be used to encrypt the data.
modeCipher mode that should be used during the encryption/decryption operation.
[in]pIvPointer to the buffer that contains the IV, if needed for the chosen mode, otherwise ignored.
ivLengthNumber of bytes of data in the pIv buffer.
Returns
status

This function performs the processing of (a part of) a data stream for an encryption/decryption operation. The algorithm and key to be used will be determined based on the context that is provided. Data is processed in full blocks only. Remaining data is stored in the context to be handled in later process or finish calls.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that needs to be processed.
inLengthNumber of bytes of data in the pIn buffer.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the pOut buffer.
Returns
status

This function performs the finalization of an encryption or decryption operation. The algorithm and key to be used will be determined based on the context that is provided. No new data is accepted but remaining data in the context is processed.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the pOut buffer.
Returns
status
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.
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.

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.

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.

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.
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

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

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

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]pSessionHandle 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
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

This function allows to generate custom key types according to the passed algoId.

Parameters
[out]customTypeHandle for the custom key type.
[in]algoIdAlgorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_PUBLIC_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_PRIVATE_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_KEY_PAIR
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_PUBLIC_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_PRIVATE_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_KEY_PAIR All other values will trigger an error.
[in]sizeAlgorithm based key size.
[in]pCustomParamsPointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM, a pointer to an mcuxClEcc_Weier_BasicDomainParams_t struct specifying custom ECC Weierstrass domain parameters
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM, a pointer to an mcuxClEcc_Weier_DomainParams_t struct specifying optimized custom ECC Weierstrass domain parameters In all other cases, the pointer shall be set to NULL
Returns
status
Return values
MCUXCLECC_STATUS_OKif custom key type is generated successfully;
MCUXCLECC_STATUS_INVALID_PARAMSif Parameters are invalid.
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.

This is the first stage of AEAD encryption/decryption. This generates the initial context out of the IV pIV and the key (pKey or keyIdx).

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pIVPointer to memory area that contains the IV
[in]ivLengthSize of pIV in bytes, with padding
[out]pAeadCtxPointer to the memory area that receives the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the second stage of AEAD encryption/decryption. This updates the internal authentication tag with the AAD.

#mcuxClEls_Aead_Init_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pAadMemory area that contains the AAD
[in]aadLengthLength of the pAad in bytes with padding
[in,out]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the third stage of AEAD encryption/decryption. This processes the given plaintext (in case of encryption) or ciphertext (in case of decryption) and outputs the ciphertext (in case of encryption) or plaintext (in case of decryption).

#mcuxClEls_Aead_Init_Async, #mcuxClEls_Aead_UpdateAad_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pInputPointer to the memory location of the data to be processed
[in]inputLengthSize of pInput in bytes with padding
[out]pOutputPointer to the processed data memory location
[in,out]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field has to be set to the size of the last data block (plain/cipher text) in bytes, without padding. In case the last block is a full block, this field has to be set to 0.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the fourth stage of AEAD encryption/decryption. This updates the authentication tag with the final data length block and outputs the tag at the desired location.

#mcuxClEls_Aead_Init_Async, #mcuxClEls_Aead_UpdateAad_Async and #mcuxClEls_Aead_UpdateData_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]aadLengthLength of the complete Additional Authenticated Data (AAD) in bytes, without padding.
[in]dataLengthLength of the complete plaintext/ciphertext in bytes, without padding.
[out]pTagPointer where the resulting tag will be stored
[in]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request
Parameters
[out]resultPointer which will be filled with the ELS status information
Returns
An error code that is always MCUXCLELS_STATUS_OK

Call #mcuxClEls_WaitForOperation to complete the operation.

Returns
An error code that is always MCUXCLELS_STATUS_OK_WAIT

This means that:

  • any running ELS command will be stopped,
  • all errors will be cleared,
  • all keys will be deleted,
  • any RNG entropy will be discarded,
  • the glitch detector will be reset and
  • the run-time fingerprint will be restored to its default value.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsA value indicating whether any running ELS operations shall be canceled
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the reset
MCUXCLELS_STATUS_OK_WAITon successful request

This is useful as a power saving mechanism.

Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[out]resultPointer which is filled with the configuration of the interrupts enable register.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK

If an ELS operation is active, this function waits for completion of that operation. For this, the busy flag of ELS is polled. Additionally, this function checks and returns any applicable error indication. If no operation is active, the function returns immediately.

Parameters
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful, or no operation was active
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

If an ELS operation is active, this function waits for completion of that operation until a counter expires. For this, the busy flag of ELS is polled. The counting mechanism behaves like a simple for-loop from counterLimit to one. This counter does not have a well-defined relationship to real-world time. Additionally, this function checks and returns any applicable error indication. If no operation is active, the function returns immediately.

Parameters
[in]counterLimitThe limit of the wait counter.
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful, or no operation was active
MCUXCLELS_STATUS_SW_COUNTER_EXPIREDif the counter expired while waiting for the operation to complete
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful or no operation was active
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Parameters
[in]errorHandlingDefine if error flags shall be cleared.
[out]errorLevelPointer to the location that will receive the value of the error level.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful or no operation was active
#MCUXCLELS_STATUS_if the last operation resulted in an error
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async

Parameters
[in]delayDefine the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023).
Return values
MCUXCLELS_STATUS_OKif the operation was successful
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Parameters
[out]delayPointer to store random start delay configuration.
Return values
MCUXCLELS_STATUS_OKif the operation was successful
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Parameters
[out]commandCrcThe command CRC value.
Returns
An error code
Return values
MCUXCLELS_STATUS_OKOperation successful
MCUXCLELS_STATUS_SW_INVALID_PARAMParameter commandCRC points to NULL
Parameters
[in]refCrcThe reference CRC value.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

This can be used to verify against the ELS command CRC.

Parameters
[in]commandThe ELS command ID.
[in]optionsThe command options for the given ELS command.
[in,out]refCrcThe current reference CRC value to update.
Returns
An error code
Return values
MCUXCLELS_STATUS_OKOperation successful
MCUXCLELS_STATUS_SW_INVALID_PARAMParameter crc points to NULL

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation. The public key must be stored in the standard ANSI X9.62 byte order (big-endian).

Parameters
[in]privateKeyIdxThe private key index.
[in]pPublicKeyPointer to the public key of a third party.
[in]sharedSecretIdxThe index in the ELS keystore that receives the shared secret that is generated by the ECDH operation.
[in]sharedSecretPropertiesThe desired key properties of the shared secret.
Parameter properties
pPublicKey
The public key consists of the 256-bit X coordinate and the 256-bit Y coordinate. The point must lie on the NIST P-256 curve, be encoded in X9.62 format and aligned on a 4-byte boundary.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The curve is NIST P-256. The message hash, must be stored in the standard ANSI X9.62 format. If the message is provided in plain, no prior conversion is necessary. The signature will be stored in the standard ANSI X9.62 byte order (big-endian).

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_HIGH. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_EccSignOption_t.
[in]keyIdxThe private key index.
[in]pInputHashThe hash of the message to sign in X9.62 format.
[in]pInputMessageThe message to sign.
[in]inputMessageLengthSize of pInputMessage in bytes.
[out]pOutputPointer to the memory area which receives the generated signature in X9.62 format. (64 bytes)
Parameter properties
options.echashchl == MCUXCLELS_ECC_HASHED
pInputHash is used, and it must be aligned on a 4-byte boundary. pInputMessage is ignored.
options.echashchl == MCUXCLELS_ECC_NOT_HASHED
pInputHash is ignored. pInputMessage and inputMessageLength are used.
pOptput must be aligned on a 4-byte boundary.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The curve is NIST P-256. The message hash, must be stored in the standard ANSI X9.62 format. If the message is provided in plain, no prior conversion is necessary. The signature and public key must be stored in the standard ANSI X9.62 byte order (big-endian).

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_EccVerifyOption_t.
[in]pInputHashThe hash of the signed message in X9.62 format.
[in]pInputMessageThe message to sign.
[in]inputMessageLengthSize of pInputMessage in bytes.
[in]pSignatureAndPubKeyPointer to the memory area which contains the concatenation of the signature and the public key.
[out]pOutputPointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification.
Parameter properties
options.echashchl == MCUXCLELS_ECC_HASHED
pInputHash is used, and it must be aligned on a 4-byte boundary. pInputMessage is ignored.
options.echashchl == MCUXCLELS_ECC_NOT_HASHED
pInputHash is ignored. pInputMessage and inputMessageLength are used.
pSignatureAndPubKey
It must be aligned on a 4-byte boundary. The signature to be verified consists of the 256-bit R component and the 256-bit S component. The public key is the one for verification. (Uncompressed, X and Y components) The signature and the public key are in X9.62 format.
pOutput
It must be aligned on a 4-byte boundary. The output shall be compared to the first 32 bytes stored at pSignatureAndPublicKey.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]derivationKeyIdxKey index used for derivation. Must be a 256-bit key with HKDF property bit set to 1.
[out]pTagetKeyMemory area to store the derived key. Will be a 256-bit key, the user must ensure there is enough space in the keystore to hold the derived key.
[in]pDerivationDataThe algorithm-specific derivation data
[in]derivationDataLengthLength of the derivation data
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]derivationKeyIdxKey index used for derivation
[in]targetKeyIdxKey bank number of the derived key
[in]targetKeyPropertiesRequested properties for the derived key. Only set usage bits.
[in]pDerivationDataThe algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]pDerivationDataThe TLS derivation data, consisting of Label, Client Random and Server Random from the TLS 1.2 specification. Note: The order is different from #mcuxClEls_TlsGenerateSessionKeysFromMasterKey_Async.
[in]keyPropertiesDesired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored.
[in]keyIdxThe index of the TLS pre-master key, which is overwritten with the master key
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:

  1. Client Encryption Key
  2. Client Message Authentication Key
  3. Server Encryption Key
  4. Server Message Authentication Key

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]pDerivationDataThe TLS derivation data, consisting of Label, Server Random and Client Random from the TLS 1.2 specification. Note: The order is different from #mcuxClEls_TlsGenerateMasterKeyFromPreMasterKey_Async.
[in]keyPropertiesDesired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored.
[in]keyIdxThe index of the TLS master key, which is overwritten with one of the session keys. There must be three further consecutive unoccupied key indices following this index.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsOne of MCUXCLELS_KEYIMPORT_KFMT_
[in]pImportKeyPointer to the RFC3394 container of the key to be imported
[in]importKeyLengthLength of the RFC3394 container of the key to be imported
[in]wrappingKeyIdxIndex of the key wrapping key, if importing RFC3394 format
[in]targetKeyIdxThe desired key index of the imported key
Parameter properties
options.kfmt != MCUXCLELS_KEYIMPORT_KFMT_RFC3394
  • pImportKey is ignored.
  • importKeyLength is ignored.
  • wrappingKeyIdx is ignored.
  • targetKeyIdx is ignored. The unpacked key is automatically stored in key slots 0, 1.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]wrappingKeyIdxThe key used for key wrapping
[in]exportKeyIdxThe key to export
[out]pOutputThe memory address of the exported key
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]keyIdxRequest key properties of the index defined here
[out]pKeyPropKey properties of the index provided
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OKon successful request

This function is a support function for FIPS CAVP testing. This function turns the ELS internal DRBG in test mode by loading known entropy from system memory. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pEntropyPointer to the input entropy data
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function mimics the behavior of #mcuxClEls_Rng_DrbgRequest_Async and fills a buffer with random data when DRBG is in test mode. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Attention
#mcuxClEls_Rng_DrbgTestInstantiate_Async must be called prior to this function.
Parameters
[out]pOutputPointer to the output random number
[in]outputLengthLength of the random number
Parameter properties
outputLength
supported values are MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MIN_SIZE bytes up to MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MAX_SIZE bytes. The size must be a multiple of 4.
Returns
An error code (see MCUXCLELS_STATUS_)
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function performs an AES-ECB encryption on system data to evaluate the encryption engine of the DRBG. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pDataKeyPointer to the data and key
[out]pOutputPointer to the encrypted output
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function performs an AES-CTR encryption on system data to evaluate the encryption engine of the DRBG in test mode. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pDataPointer to the data to be encrypted
[in]dataLengthLength of the data to be encrypted
[in]pIvKeyPointer to the IV and key
[out]pOutputPointer to the encrypted output
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function overwrites the default DTRNG configuration in order to optimize or fine tune the DTRNG entropy gathering process. Call #mcuxClEls_WaitForOperation to complete the operation. Note that the TRNG configuration set by this function is non-persistent and any reset of the ELS (e.g. a power-cycle or calling #mcuxClEls_Reset_Async) will resets the DTRNG configuration to its default value.

Parameters
[in]pInputThe pointer to DTRNG initialization data
Parameter properties
pInput
The size is MCUXCLELS_RNG_DTRNG_CONFIG_SIZE bytes.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function evaluates a DTRNG configuration for device specific characterization. The configuration used for characterization has to be placed in system memory. Call #mcuxClEls_WaitForOperation to complete the operation.

Attention
If this function is called once, all other ELS commands except #mcuxClEls_Rng_Dtrng_ConfigEvaluate_Async are blocked until any reset of the ELS (e.g. a power-cycle or calling #mcuxClEls_Reset_Async) is triggered.
Parameters
[in]pInputThe pointer to DTRNG initialization data
[out]pOutputThe pointer to the evaluation result
Parameter properties
pInput
The size is MCUXCLELS_RNG_DTRNG_EVAL_CONFIG_SIZE bytes.
pOutput
The size is MCUXCLELS_RNG_DTRNG_EVAL_RESULT_SIZE bytes.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function returns one low-quality random CPU word gathered from the PRNG.

Attention
PRNG has to be initialized prior to the first time calling this function.
Parameters
[out]pWordThe pointer to the random word
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_OKon successful request
MCUXCLELS_STATUS_HW_PRNGin case of insufficient entropy

This function fills a buffer with low-quality random values gathered from the PRNG.

Attention
PRNG has to be initialized prior to the first time calling this function.
Parameters
[out]pOutputPointer to the beginning of the memory area to fill with random data from PRNG
[in]outputLengthSize of pOutput in bytes
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_OKon successful request
MCUXCLELS_STATUS_HW_PRNGin case of insufficient entropy

This function performs the initialization for a multi-part hash operation.

Parameters
[in/out]session Handle for the current CL session.
[out]pContextHash context which is used to maintain the state and store other relevant information about the operation.
[in]algorithmHash algorithm that should be used during the computation operation.
Returns
status
Return values
MCUXCLHASH_STATUS_OKInitialization successful
MCUXCLHASH_FAILUREError occurred during initialization function

This function performs the processing of (a part of) a data stream for a Hash operation. The algorithm to be used will be determined based on the context that is provided.

Parameters
[in/out]session Handle for the current CL session.
[in/out]pContext Hash context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that needs to be processed.
[in]inSizeNumber of bytes of data in the pIn buffer.
Returns
status
Return values
MCUXCLHASH_STATUS_OKHash operation successful
MCUXCLHASH_FAILUREError occurred during Hash operation
MCUXCLHASH_STATUS_INVALID_PARAMSThe provided function parameters do not fulfill requirements
MCUXCLHASH_STATUS_FAULT_ATTACKA fault attack was detected

This function performs the finalization of a Hash computation operation. The algorithm to be used will be determined based on the context that is provided

Parameters
[in/out]session Handle for the current CL session.
[in/out]pContext Hash context which is used to maintain the state and store other relevant information about the operation.
[out]pOutPointer to the output buffer where the computed hash value needs to be written.
[out]pOutSizeWill be incremented by the number of bytes of data that have been written to the pOut buffer.
Returns
status
Return values
MCUXCLHASH_STATUS_OKHash operation successful
MCUXCLHASH_FAILUREError occurred during Hash operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in,out]privKeyKey handle of private key
[in,out]pubKeyKey handle of public key
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in,out]keyKey handle that will be configured
[in]protectionDefine the protection and flush mechanism that shall be used with this key
[in]pAuxDataProvide pointer to additional data the protection function may use
[in]parentKeyProvide parent key information in case it exists. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to load the key
[out]dstSlotProvide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to load the key
[out]dstDataProvide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to flush the key
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in,out]keykey handle that provides information to flush the key
[in]key_propertiesPointer to the requested key properties of the destination key. Will be set in key->container.pAuxData
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation

This function performs the initialization of a context for a multipart MAC computation. The algorithm to be used will be determined based on the key that is provided.

This function should only be called once, as the first step for a multipart computation.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • AES128 key
  • CMAC mode

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

Parameters
[in]sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[in]keyKey to be used to MAC the data.
[in]modeMode that should be used during the MAC operation.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function performs the data processing for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided.

This function can be called multiple times, after the multipart context initialization.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • Input data

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also
mcuxClMac_init
Parameters
sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that need to be processed.
[in]inLengthNumber of bytes of data in the in buffer.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function performs the final MAC generation step for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided.

This function should only be called once, as the last step for a multipart computation.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • Output data buffer, at least the size of a single AES block

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also
mcuxClMac_init
mcuxClMac_process
Parameters
[in]sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[out]pMacPointer to the output buffer where the MAC needs to be written.
[out]pMacLengthWill be incremented by the number of bytes of data that have been written to the pMac buffer.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function calculates modular exponentiation in a secure manner. It randomizes the computation by Euclidean splitting: exponent = b * q + r, where b is a 64-bit odd random number (with both MSbit and LSbit set), and r = exponent % b. The exponentiation is calculated by two steps: (1) m0 = m^q mod n; and (2) result = m0^b * m^r mod n. In addition, base operands are re-randomized, by adding random multiples of the modulus to them before performing modular multiplications.

Parameters
[in]pSessionhandle for the current CL session.
[in]pExppointer to exponent
[in]pExpTemppointer to temporary buffer
[in]expByteLengthbyte length of exponent
[in]iT3_iX_iT2_iT1indices of PKC operands
[in]iN_iTE_iT0_iRindices of PKC operands
[in]secOptionoption to disable the operand re-randomization
Parameter properties
session:
The session pointed to by pSession has to be initialized prior to a call to this function.
pExp
the exponent is a big-endian octet string and shall be non-zero.
pExpTemp
the temporary buffer can be in either CPU or PKC workarea.
It shall be CPU word aligned, and its length shall be a multiple of CPU word and greater than expByteLength.
It can share the space with exponent (i.e., pExpTemp = pExp), but the exponent will be overwritten.
iT3_iX_iT2_iT1
iT1 (bits 0~7): index of temp1 (PKC operand).
Its size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iT2 (bits 8~15): index of temp2 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iX (bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE).
It will be overwritten.
iT3 (bits 24~31): index of temp3 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iN_iTE_iT0_iR
iR (bits 0~7): index of result (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iT0 (bits 8~15): index of temp0 (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iTE (bits 16~23): index of temp4 (PKC operand).
The size shall be at least (6 * MCUXCLPKC_WORDSIZE).
iN (bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN).
The upper 32 bits of N shall be null, which can be obtained for instance by applying 32-bit modulus blinding, or by artificially increasing PS1 lengths and all buffer sizes by 1 PKC word.
NDash of modulus shall be stored in the PKC word before modulus.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize = MCUXCLPKC_ROUNDUP_SIZE(lenN), where lenN is the length of modulus n. As the upper 32 bits of N should be null, operandSize >= lenN + 4 bytes.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
#mcuxClPkc_WaitForReady will be called before returning to caller. The PKC calculation might be still on-going, call #mcuxClPkc_WaitForFinish before CPU accesses to the result.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMATH_ERRORCODE_OKfunction executed successfully
MCUXCLMATH_ERRORCODE_ERRORerror occurred during operation
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function randomly permutes offsets stored in UPTR table, together with operands stored in each buffer in PKC workarea. It randomizes the buffer allocation (physical address in PKC workarea) and moves operands stored accordingly. When calling this function, there shall be no on-going and pending PKC calculations using the specified UPTR table elements.

Parameters
[in]pSessionhandle for the current CL session.
[in,out]pUPTRTpointer to the first element to be randomized in UPTR table.
[in]bufferLengthbyte length of each buffer in PKC workarea.
[in]noOfBuffernumber of elements to be randomized.
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pUPTRT
this pointer shall be 2-byte aligned.
All offsets (pUPTRT[0~(noOfBuffer-1)]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
bufferLength
this length shall be a multiple of MCUXCLPKC_WORDSIZE.
Attention
This function uses PRNG. Caller needs to check if PRNG is ready.
Returns
A flow-protected status code (see Flow Protection API).
Return values
MCUXCLPKC_STATUS_OKif UPTR table is randomized successfully.
MCUXCLPKC_STATUS_NOKif the operation failed.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function performs the reseeding of a random data generator. This operation fetches a fresh seed from a TRNG and updates the state in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function generates random data based on the information contained in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
[out]pOutBuffer in which the generated random data must be written.
[in]outLengthNumber of random data bytes that must be written in the pOut buffer.
Returns
status

This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function performs a series of selft-tests on the random data generator. These tests are performed on the random data generator defined by Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function reports whether the the random data generator can provide the requested security strength.

Parameters
[in]pSessionHandle for the current CL session.
[in]securityStrengthRequested security strength in bits.
Returns
status

This function performs the initialization of the non-cryptographic random number generator.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
[out]pOutBuffer in which the generated random data must be written.
[in]outLengthNumber of random data bytes that must be written in the pOut buffer.
Returns
status
Parameters
testMode[in]Pointer to TEST_MODE descriptor
pEntropyInput[in]Pointer to memory buffer containing entropy input for DRBG (re)seeding
Returns
  • MCUXCLRANDOM_STATUS_OK if the TEST_MODE descriptor generation was successful

This function performs an RSA signature verification according to RSAVP1, RSASSA-PSS-VERIFY or RSASSA-PKCS1-v1_5-VERIFY of PKCS #1 v2.2. Based on the selection of the padding mode, it is determined, whether to perform no padding verification, or whether to perform one of the supported padding verifications based on one of the supported hash functions. The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8. The public exponent is limited to 2 <= e < N.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]pKeyPointer to key structure of type mcuxClRsa_Key
[in]pMessageOrDigestPointer to buffer, which contains the input to the verify operation
[in]messageLengthByte-length of MessageOrDigest
[in]pSignaturePointer to buffer, which contains the signature
[in]pVerifyModePointer to verification mode of type mcuxClRsa_SignVerifyMode_t
[in]saltLengthByte-length of salt
[in]optionsOptions field
[out]pOutputPointer to output buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pKey:
The key entries must meet the following conditions:
  • Entry keytype must be set to MCUXCLRSA_KEY_PUBLIC. In case of passing another key type, the function returns MCUXCLRSA_STATUS_INVALID_INPUT. The functions checks, internally, whether the required key entries are not set to NULL. If so, the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
  • The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8;
  • It is required that e is greater or equal to 2 and smaller than n.
pMessageOrDigest:
The input must meet the following conditions:
  • It must be provided in big-endian byte order;
  • In case of mode RSAVP1, please set to NULL.
messageLength:
This value is only regarded in case of option MCUXCLRSA_OPTION_MESSAGE_PLAIN. In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST, or mode RSAVP1, please set to zero.
pSignature:
The signature must meet the following conditions:
  • It must be given in big-endian byte order;
  • The signature length is determined by the modulus length (bytelength(n));
  • The signature value must be smaller than n. If it is bigger the function returns MCUXCLRSA_STATUS_INVALID_INPUT.
pVerifyMode:
The mode specifies the targeted padding verification and hashing algorithms. Please set to one of mcuxClRsa_Verify_Modes.
saltLength:
This value is only regarded in case of performing a RSASSA-PSS-VERIFY operation. Otherwise, please set to zero.
options:
This field is used to select options of the sign operation:
pOutput:
In case of mode RSAVP1 this pointer points to the buffer, where the result will be stored in big-endian byte order. This buffer must have the same byte-length as the modulus. In case of modes RSASSA-PSS-VERIFY and RSASSA-PKCS1-v1_5-VERIFY please set to NULL.
Returns
Status of the mcuxClRsa_verify operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_VERIFY_OKVerify operation executed successfully.
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OKVerification primitive operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_VERIFY_FAILEDThe signature verification failed.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function for given public exponent and key size generates an RSA private key in CRT representation (p, q, dp, dq, qInv) and computes the modulus n.

Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key.
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private CRT key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill be set by the number of bytes of data that have been written to the pPubData buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.
type:
Type of the key. It contains information about the input parameters:
  • type.size - length of the generated key
  • type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t* (i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).
protection :
Protection and flush mechanism that must be applied to the generated key.
privKey:
Key handle for the generated private key.
pPrivData:
Pointer to the buffer where the generated private CRT key (p, q, qInv, dp, dq) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: p, q, qInv, dp, dq. Buffer is allocated by the caller.
pPrivDataLength:
Number of bytes of data that have been written to the pPrivData buffer.
pubKey:
Key handle for the generated public key.
pPubData:
Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.
pPubDataLength:
Number of bytes of data that have been written to the pPubData buffer.
Returns
Status of the mcuxClRsa_KeyGeneration_Crt operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_KEYGENERATION_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses DRBG and PRNG which have to be initialized prior to calling the function.

This function for given public exponent and key size generates RSA private key in in plain from (d, n).

Private exponent d is computed with the requirements specified in the FIPS 186-4, Appendix B.3.1. Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private plain key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill be set by the number of bytes of data that have been written to the pPubData buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.
type:
Type of the key. It contains information about the input parameters:
  • type.size - length of the generated key
  • type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t*(i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).
protection :
Protection and flush mechanism that must be applied to the generated key.
privKey:
Key handle for the generated private key.
pPrivData:
Pointer to the buffer where the generated private plain key (n, d) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, d. Buffer is allocated by the caller.
pPrivDataLength:
Number of bytes of data that have been written to the pPrivData buffer.
pubKey:
Key handle for the generated public key.
pPubData:
Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.
pPubDataLength:
Number of bytes of data that have been written to the pPubData buffer.
Returns
Status of the mcuxClRsa_KeyGeneration_Plain operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_KEYGENERATION_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses DRBG and PRNG which have to be initialized prior to calling the function.
Parameters
pSessionSession to be initialized.
pRtfbuffer to store the rtf result.
RtfOptionsOptions to define RTF processing.
Returns
status

This function will (securely) cleanup the session, which will still be usable afterwards.

Parameters
pSessionSession to be cleaned.
Returns
status

This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.

Parameters
pSessionSession to be destroyed.
Returns
status

Deprecated type for mcuxClEcc component return codes.

Multi-part encryption/decryption finalization function.

Multi-part encryption/decryption processing function.

Multi-part encryption/decryption initialization function.

This function performs an encryption/decryption operation in one shot. The algorithm to be used will be determined based on the mode that is provided.

For example, to perform an AES encryption/decryption operation with a 128-bit key in CBC mode on padded data, the following needs to be provided:

  • AES128 key
  • CBC mode for encryption, without padding
  • IV, same size as the AES block size
  • Plain input data, size must be a multiple of the AES block size
  • Output data buffer, with the same size as the input data
  • Output size buffer, to store the amount of written bytes
Parameters
sessionHandle for the current CL session.
keyKey to be used to encrypt the data.
modeCipher mode that should be used during the encryption/decryption operation.
[in]pIvPointer to the buffer that contains the IV, if needed for the chosen mode, otherwise ignored.
ivLengthNumber of bytes of data in the pIv buffer.
[in]pInPointer to the input buffer that contains the plain data that needs to be encrypted.
inLengthNumber of bytes of plain data in the pIn buffer.
[out]pOutPointer to the output buffer where the encrypted data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of encrypted data that have been written to the pOut buffer.
Returns
status

This function performs the initialization for a multi part encryption/decryption operation. The algorithm to be used will be determined based on the mode that is provided.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
keyKey to be used to encrypt the data.
modeCipher mode that should be used during the encryption/decryption operation.
[in]pIvPointer to the buffer that contains the IV, if needed for the chosen mode, otherwise ignored.
ivLengthNumber of bytes of data in the pIv buffer.
Returns
status

This function performs the processing of (a part of) a data stream for an encryption/decryption operation. The algorithm and key to be used will be determined based on the context that is provided. Data is processed in full blocks only. Remaining data is stored in the context to be handled in later process or finish calls.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that needs to be processed.
inLengthNumber of bytes of data in the pIn buffer.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the pOut buffer.
Returns
status

This function performs the finalization of an encryption or decryption operation. The algorithm and key to be used will be determined based on the context that is provided. No new data is accepted but remaining data in the context is processed.

Parameters
sessionHandle for the current CL session.
pContextCipher context which is used to maintain the state and store other relevant information about the operation.
[out]pOutPointer to the output buffer where the processed data needs to be written.
[out]pOutLengthWill be incremented by the number of bytes of processed data that have been written to the pOut buffer.
Returns
status

Deprecated type for mcuxClEcc component return codes.

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

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).

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).

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).

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

implements ECC key agreement according to rfc7748.

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

implements ECC point multiplication.

implements ECDSA signature verification.

implements ECDSA signature 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.
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.
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.

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.

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.

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.
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

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

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

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]pSessionHandle 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
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

Deprecated type for mcuxClEcc component return codes.

Key type constructor.

Given pointers and lengths specifying domain parameters of a custom (short) Weierstrass curve with cofactor 1, this function generates a corresponding optimized custom domain parameter struct.

Parameters
pSessionHandle for the current CL session.
[out]pEccWeierDomainParamsPointer to memory area in which the optimized domain parameters shall be stored.
[in]pEccWeierBasicDomainParamsPointer to struct containing pointers and lengths specifying the custom domain parameters.
[in]optionsParameter specifying whether or not the pre-computed point (2 ^ (byteLenN * 4)) * G corresponding to the base point G shall be calculated or not, If set to
  • MCUXCLECC_OPTION_GENERATEPRECPOINT_YES, the pre-computed point will be calculated
  • MCUXCLECC_OPTION_GENERATEPRECPOINT_NO, the pre-computed point will not be calculated
Attention
the generated optimized domain parameter cannot be copied or moved, but shall be used in the original memory address where it is generated.
Returns
A code-flow protected error code (see MCUXCLECC_STATUS_)
Return values
MCUXCLECC_STATUS_OKif optimized domain parameters are generated successfully;
MCUXCLECC_STATUS_INVALID_PARAMSif parameters are invalid;
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.

This function allows to generate custom key types according to the passed algoId.

Parameters
[out]customTypeHandle for the custom key type.
[in]algoIdAlgorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_PUBLIC_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_PRIVATE_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM | MCUXCLKEY_ALGO_ID_KEY_PAIR
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_PUBLIC_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_PRIVATE_KEY
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM | MCUXCLKEY_ALGO_ID_KEY_PAIR All other values will trigger an error.
[in]sizeAlgorithm based key size.
[in]pCustomParamsPointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_EPHEMERAL_CUSTOM, a pointer to an mcuxClEcc_Weier_BasicDomainParams_t struct specifying custom ECC Weierstrass domain parameters
  • MCUXCLKEY_ALGO_ID_ECC_SHWS_GFP_STATIC_CUSTOM, a pointer to an mcuxClEcc_Weier_DomainParams_t struct specifying optimized custom ECC Weierstrass domain parameters In all other cases, the pointer shall be set to NULL
Returns
status
Return values
MCUXCLECC_STATUS_OKif custom key type is generated successfully;
MCUXCLECC_STATUS_INVALID_PARAMSif Parameters are invalid.
MCUXCLECC_STATUS_FAULT_ATTACKif fault attack (unexpected behavior) is detected.

Deprecated type for mcuxClEcc component return codes.

AES-GCM final encryption/decryption.

AES-GCM update of the encrypted data.

AES-GCM update of the Additional Authenticated Data (AAD)

AES-GCM partial initialization.

This is the first stage of AEAD encryption/decryption. This generates the initial context out of the IV pIV and the key (pKey or keyIdx).

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pIVPointer to memory area that contains the IV
[in]ivLengthSize of pIV in bytes, with padding
[out]pAeadCtxPointer to the memory area that receives the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the first stage of AEAD encryption/decryption. This generates the initial context out of the IV pIV and the key (pKey or keyIdx).

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pIVPointer to memory area that contains the IV
[in]ivLengthSize of pIV in bytes, with padding
[out]pAeadCtxPointer to the memory area that receives the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the second stage of AEAD encryption/decryption. This updates the internal authentication tag with the AAD.

#mcuxClEls_Aead_Init_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pAadMemory area that contains the AAD
[in]aadLengthLength of the pAad in bytes with padding
[in,out]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the third stage of AEAD encryption/decryption. This processes the given plaintext (in case of encryption) or ciphertext (in case of decryption) and outputs the ciphertext (in case of encryption) or plaintext (in case of decryption).

#mcuxClEls_Aead_Init_Async, #mcuxClEls_Aead_UpdateAad_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]pInputPointer to the memory location of the data to be processed
[in]inputLengthSize of pInput in bytes with padding
[out]pOutputPointer to the processed data memory location
[in,out]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field has to be set to the size of the last data block (plain/cipher text) in bytes, without padding. In case the last block is a full block, this field has to be set to 0.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This is the fourth stage of AEAD encryption/decryption. This updates the authentication tag with the final data length block and outputs the tag at the desired location.

#mcuxClEls_Aead_Init_Async, #mcuxClEls_Aead_UpdateAad_Async and #mcuxClEls_Aead_UpdateData_Async must have been called before calling this function.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe AEAD command options. For more information, see mcuxClEls_AeadOption_t.
[in]keyIdxIndex of the key inside the ELS keystore
[in]pKeyPointer to the key
[in]keyLengthSize of pKey in bytes
[in]aadLengthLength of the complete Additional Authenticated Data (AAD) in bytes, without padding.
[in]dataLengthLength of the complete plaintext/ciphertext in bytes, without padding.
[out]pTagPointer where the resulting tag will be stored
[in]pAeadCtxPointer to the AEAD context structure. Must be at least MCUXCLELS_AEAD_CONTEXT_SIZE bytes long.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_AEAD_EXTERN_KEY

keyIdx is ignored.

pKey must be a valid AES key and keyLength a valid AES key size (see MCUXCLELS_CIPHER_KEY_SIZE_AES_).

options.extkey == MCUXCLELS_AEAD_INTERN_KEY

keyIdx must be a valid key index with the correct usage rights.

pKey and keyLength are ignored.

options.msgendw
This field is ignored
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Performs an AES encryption/decryption. Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsEncryption/decryption command options. For detailed information, see mcuxClEls_CipherOption_t.
[in]keyIdxIndex of the key inside the ELS keystore. See parameter properties section in function description.
[in]pKeyMemory area that contains the key. See parameter properties section in function description.
[in]keyLengthSize of pKey in bytes. Must be a valid key size of MCUXCLELS_CIPHER_KEY_SIZE_AES_. See parameter properties section in function description.
[in]pInputPointer to the input data to be encrypted/decrypted. Padding must be already applied.
[in]inputLengthSize of pInput in bytes, must be a multiple of the block size.
[in,out]pIVA pointer to the memory location which contains/receives the IV/state of cipher. See parameter properties section in function description.
[out]pOutputPointer to the output buffer to store encrypted/decrypted data.

The properties of some parameters change with respect to selected options.

Parameter properties
options.cphmde == MCUXCLELS_CIPHERPARAM_ALGORITHM_AES_ECB

pIV is ignored.

options.cphmde == MCUXCLELS_CIPHERPARAM_ALGORITHM_AES_CBC

pIV must be set to the IV (when encrypting the first block) or to the last block of the ciphertext of the previous operation. ELS will always read and write to this location.

options.cphsie is ignored.

     @p options.cphsoe is ignored.</dd>

 <dt>@p options.cphmde == #MCUXCLELS_CIPHERPARAM_ALGORITHM_AES_CTR</dt>
     <dd>@p pIV must be set to the IV (when encrypting the first block) or to the state output of the previous
     encryption/decryption operation. ELS will write to this location if @p options.cphsoe == #MCUXCLELS_CIPHER_STATE_OUT_ENABLE.</dd>

 <dt>@p options.extkey == #MCUXCLELS_CIPHER_EXTERNAL_KEY</dt>
     <dd>@p keyIdx is ignored.</dd>

 <dt>@p options.extkey == #MCUXCLELS_CIPHER_INTERNAL_KEY</dt>
     <dd>@p pKey is ignored.

     @p keyLength is ignored.</dd>

Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_CmacOption_t.
[in]keyIdxThe CMAC key index
[in]pKeyPointer to the padded CMAC key
[in]keyLengthSize of pKey in bytes. Must be a valid CMAC key size. See the parameter properties section in the function description.
[in]pInputPointer to a memory location which contains the data, padded via SP 800-38b standard, to be authenticated
[in]inputLengthSize of pInput in bytes before padding
[in,out]pMacPointer to the CMAC command state input/output. See the parameter properties section in the function description.

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_CMAC_EXTERNAL_KEY_ENABLE

keyIdx is ignored.

options.extkey == MCUXCLELS_CMAC_EXTERNAL_KEY_DISABLE

pKey is ignored.

keyLength is ignored.

(options.finalize == MCUXCLELS_CMAC_FINALIZE_DISABLE)

The intermediate state is written to pMac.

options.finalize == MCUXCLELS_CMAC_FINALIZE_ENABLE

The resulting MAC is written to pMac.

options.soe is ignored.

Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif an invalid parameter was specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Get the random start delay for AES based operations.

Set the random start delay for AES based operations.

Get the last ELS error code and level and optionally clear the error status.

Get the last ELS error code and optionally clear the error status.

Resets all error flags that have been set by a previous operation.

Await the completion of an ELS operation for a limited amount of time and optionally clear the error status.

Wait for an ELS operation and optionally clear the error status.

Set the interrupt status register, for debug and testing purposes.

Clear the interrupt status register.

Get interrupt enable flags.

Set interrupt enable flags.

Disable the ELS.

Perform a synchronous reset of the ELS.

Enables the ELS.

Determines the current state of the ELS.

Attention
This header was delivered as part of a CLNS release which is compatible with a specific ELS hardware IP version, which is defined by the macro MCUXCLELS_HW_VERSION.
Parameters
[out]resultPointer which will be filled with the ELS hardware version
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[out]resultPointer which will be filled with the ELS status information
Returns
An error code that is always MCUXCLELS_STATUS_OK

Call #mcuxClEls_WaitForOperation to complete the operation.

Returns
An error code that is always MCUXCLELS_STATUS_OK_WAIT

This means that:

  • any running ELS command will be stopped,
  • all errors will be cleared,
  • all keys will be deleted,
  • any RNG entropy will be discarded,
  • the glitch detector will be reset and
  • the run-time fingerprint will be restored to its default value.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsA value indicating whether any running ELS operations shall be canceled
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the reset
MCUXCLELS_STATUS_OK_WAITon successful request

This is useful as a power saving mechanism.

Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[out]resultPointer which is filled with the configuration of the interrupts enable register.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]optionsThe command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK

If an ELS operation is active, this function waits for completion of that operation. For this, the busy flag of ELS is polled. Additionally, this function checks and returns any applicable error indication. If no operation is active, the function returns immediately.

Parameters
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful, or no operation was active
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

If an ELS operation is active, this function waits for completion of that operation until a counter expires. For this, the busy flag of ELS is polled. The counting mechanism behaves like a simple for-loop from counterLimit to one. This counter does not have a well-defined relationship to real-world time. Additionally, this function checks and returns any applicable error indication. If no operation is active, the function returns immediately.

Parameters
[in]counterLimitThe limit of the wait counter.
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful, or no operation was active
MCUXCLELS_STATUS_SW_COUNTER_EXPIREDif the counter expired while waiting for the operation to complete
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[in]errorHandlingDefine if error flags shall be cleared.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful or no operation was active
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Parameters
[in]errorHandlingDefine if error flags shall be cleared.
[out]errorLevelPointer to the location that will receive the value of the error level.
Return values
MCUXCLELS_STATUS_OKif the last operation was successful or no operation was active
#MCUXCLELS_STATUS_if the last operation resulted in an error
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async

Parameters
[in]delayDefine the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023).
Return values
MCUXCLELS_STATUS_OKif the operation was successful
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Parameters
[out]delayPointer to store random start delay configuration.
Return values
MCUXCLELS_STATUS_OKif the operation was successful
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

Deprecated type for mcuxClEcc component return codes.

Updates a reference CRC with the parameters of an ELS command.

Verifies a reference CRC against the computed ELS command CRC.

Get the current command CRC value.

Parameters
[in]optionsThe command CRC options. For more information, see mcuxClEls_CommandCrcConfig_t.
Returns
An error code that is always MCUXCLELS_STATUS_OK
Parameters
[out]commandCrcThe command CRC value.
Returns
An error code
Return values
MCUXCLELS_STATUS_OKOperation successful
MCUXCLELS_STATUS_SW_INVALID_PARAMParameter commandCRC points to NULL
Parameters
[in]refCrcThe reference CRC value.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information

This can be used to verify against the ELS command CRC.

Parameters
[in]commandThe ELS command ID.
[in]optionsThe command options for the given ELS command.
[in,out]refCrcThe current reference CRC value to update.
Returns
An error code
Return values
MCUXCLELS_STATUS_OKOperation successful
MCUXCLELS_STATUS_SW_INVALID_PARAMParameter crc points to NULL

Deprecated type for mcuxClEcc component return codes.

Verifies an ECDSA signature of a given message.

Generates an ECDSA signature of a given message.

Performs a Diffie-Hellman key exchange with an internal ECC private key and an external ECC public key.

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_HIGH. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation. The public key will be stored in the standard ANSI X9.62 byte order (big-endian).

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_EccKeyGenOption_t.
[in]signingKeyIdxThe index of the key to sign the generated public key.
[in]privateKeyIdxOutput key index.
[in]generatedKeyPropertiesThe desired key properties of the generated key.
[in]pRandomDataRandom data provided by the user.
[out]pPublicKeyPointer to the memory area which receives the public key and optionally the key signature.
Parameter properties
options.kgsign == MCUXCLELS_ECC_PUBLICKEY_SIGN_DISABLE
signingKeyIdx is ignored.
options.kgsrc == MCUXCLELS_ECC_OUTPUTKEY_DETERMINISTIC
privateKeyIdx also defines the key index of the source key material. The source key material will be overwritten by the output public key.
options.kgsign_rnd == MCUXCLELS_ECC_NO_RANDOM_DATA
pRandomData is ignored.
pPublicKey must be aligned on a 4-byte boundary.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation. The public key must be stored in the standard ANSI X9.62 byte order (big-endian).

Parameters
[in]privateKeyIdxThe private key index.
[in]pPublicKeyPointer to the public key of a third party.
[in]sharedSecretIdxThe index in the ELS keystore that receives the shared secret that is generated by the ECDH operation.
[in]sharedSecretPropertiesThe desired key properties of the shared secret.
Parameter properties
pPublicKey
The public key consists of the 256-bit X coordinate and the 256-bit Y coordinate. The point must lie on the NIST P-256 curve, be encoded in X9.62 format and aligned on a 4-byte boundary.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The curve is NIST P-256. The message hash, must be stored in the standard ANSI X9.62 format. If the message is provided in plain, no prior conversion is necessary. The signature will be stored in the standard ANSI X9.62 byte order (big-endian).

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_HIGH. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_EccSignOption_t.
[in]keyIdxThe private key index.
[in]pInputHashThe hash of the message to sign in X9.62 format.
[in]pInputMessageThe message to sign.
[in]inputMessageLengthSize of pInputMessage in bytes.
[out]pOutputPointer to the memory area which receives the generated signature in X9.62 format. (64 bytes)
Parameter properties
options.echashchl == MCUXCLELS_ECC_HASHED
pInputHash is used, and it must be aligned on a 4-byte boundary. pInputMessage is ignored.
options.echashchl == MCUXCLELS_ECC_NOT_HASHED
pInputHash is ignored. pInputMessage and inputMessageLength are used.
pOptput must be aligned on a 4-byte boundary.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The curve is NIST P-256. The message hash, must be stored in the standard ANSI X9.62 format. If the message is provided in plain, no prior conversion is necessary. The signature and public key must be stored in the standard ANSI X9.62 byte order (big-endian).

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_EccVerifyOption_t.
[in]pInputHashThe hash of the signed message in X9.62 format.
[in]pInputMessageThe message to sign.
[in]inputMessageLengthSize of pInputMessage in bytes.
[in]pSignatureAndPubKeyPointer to the memory area which contains the concatenation of the signature and the public key.
[out]pOutputPointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification.
Parameter properties
options.echashchl == MCUXCLELS_ECC_HASHED
pInputHash is used, and it must be aligned on a 4-byte boundary. pInputMessage is ignored.
options.echashchl == MCUXCLELS_ECC_NOT_HASHED
pInputHash is ignored. pInputMessage and inputMessageLength are used.
pSignatureAndPubKey
It must be aligned on a 4-byte boundary. The signature to be verified consists of the 256-bit R component and the 256-bit S component. The public key is the one for verification. (Uncompressed, X and Y components) The signature and the public key are in X9.62 format.
pOutput
It must be aligned on a 4-byte boundary. The output shall be compared to the first 32 bytes stored at pSignatureAndPublicKey.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_HashOption_t.
[in]pInputPadded input data to be hashed
[in]inputLengthSize of pInput in bytes. Since the input is padded, the length must be a multiple of the block size, see MCUXCLELS_HASH_BLOCK_SIZE_.
[in,out]pDigestPointer to the memory area that contains/receives the (intermediate) hash digest, allocated by the caller, see MCUXCLELS_HASH_STATE_SIZE_.

The properties of some parameters change with respect to selected options.

Parameter properties
options.hashini == MCUXCLELS_HASH_INIT_ENABLE

options.hashld has no effect and shall be MCUXCLELS_HASH_LOAD_DISABLE. No data is read from pDigest.

options.hashld == MCUXCLELS_HASH_LOAD_DISABLE

pDigest is not expected to contain an initial state. No data is read from pDigest.

options.rtfoe == MCUXCLELS_HASH_RTF_UPDATE_ENABLE

When this option is used the current runtime fingerprint (RTF) value will be appended to the output pDigest; an additional MCUXCLELS_HASH_RTF_OUTPUT_SIZE bytes has to be allocated for pDigest.

options.hashoe == MCUXCLELS_HASH_OUTPUT_ENABLE

The hash state is written to pDigest. The size varies depending on the choice of options.hashmd, for more information see MCUXCLELS_HASH_STATE_SIZE_ . In cases where the state size and output size differ - see MCUXCLELS_HASH_OUTPUT_SIZE_ -, the state must be truncated by the caller to obtain the final hash value.

Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_HmacOption_t.
[in]keyIdxThe HMAC key index, if an internal key shall be used
[in]pPaddedKeyPointer to a memory location containing the padded HMAC key
[in]pInputPointer to a memory location which contains the data to be authenticated
[in]inputLengthSize of pInput in bytes
[out]pOutputThe output message authentication code

The properties of some parameters change with respect to selected options.

Parameter properties
options.extkey == MCUXCLELS_HMAC_EXTERNAL_KEY_ENABLE

keyIdx is ignored.

pPaddedKey must contain the padded HMAC key, which can mean one of two things depending on the length of the original HMAC key, LkHMAC:

options.extkey == MCUXCLELS_HMAC_EXTERNAL_KEY_DISABLE

keyIdx must be a valid key index with the correct usage rights for HMAC.

pPaddedKey is ignored.

Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif an invalid parameter was specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Generates TLS session keys based on a master key and derivation data, according to the TLS 1.2 specification.

Generates a TLS master key based on a pre-master key and derivation data, according to the TLS 1.2 specification.

Derives a key using the NIST SP 800-108 CMAC-based Extract-and-Expand Key Derivation Function.

Derives a key using the HKDF (HMAC-based key derivation function) according to SP800-56C one-step approach with Sha2-256.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsThe command options. For more information, see mcuxClEls_HkdfOption_t.
[in]derivationKeyIdxKey index used for derivation. Must be a 256-bit key with HKDF property bit set to 1.
[in]targetKeyIdxKey bank number of the derived key. Will be a 256-bit key, the user must ensure there is enough space in the keystore to hold the derived key.
[in]targetKeyPropertiesRequested properties for the derived key. The ksize field will be ignored.
[in]pDerivationDataThe algorithm-specific derivation data, the length is MCUXCLELS_HKDF_RFC5869_DERIVATIONDATA_SIZE bytes
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]derivationKeyIdxKey index used for derivation. Must be a 256-bit key with HKDF property bit set to 1.
[out]pTagetKeyMemory area to store the derived key. Will be a 256-bit key, the user must ensure there is enough space in the keystore to hold the derived key.
[in]pDerivationDataThe algorithm-specific derivation data
[in]derivationDataLengthLength of the derivation data
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]derivationKeyIdxKey index used for derivation
[in]targetKeyIdxKey bank number of the derived key
[in]targetKeyPropertiesRequested properties for the derived key. Only set usage bits.
[in]pDerivationDataThe algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]pDerivationDataThe TLS derivation data, consisting of Label, Client Random and Server Random from the TLS 1.2 specification. Note: The order is different from #mcuxClEls_TlsGenerateSessionKeysFromMasterKey_Async.
[in]keyPropertiesDesired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored.
[in]keyIdxThe index of the TLS pre-master key, which is overwritten with the master key
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:

  1. Client Encryption Key
  2. Client Message Authentication Key
  3. Server Encryption Key
  4. Server Message Authentication Key

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]pDerivationDataThe TLS derivation data, consisting of Label, Server Random and Client Random from the TLS 1.2 specification. Note: The order is different from #mcuxClEls_TlsGenerateMasterKeyFromPreMasterKey_Async.
[in]keyPropertiesDesired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored.
[in]keyIdxThe index of the TLS master key, which is overwritten with one of the session keys. There must be three further consecutive unoccupied key indices following this index.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Deprecated type for mcuxClEcc component return codes.

Exports the properties of the keys stored in the ELS internal keystore.

Exports a key from an internal key register to external storage, using a wrapping key.

Imports a key from external storage to an internal key register.

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_LOW. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]keyIdxThe index of the key to be deleted
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]optionsOne of MCUXCLELS_KEYIMPORT_KFMT_
[in]pImportKeyPointer to the RFC3394 container of the key to be imported
[in]importKeyLengthLength of the RFC3394 container of the key to be imported
[in]wrappingKeyIdxIndex of the key wrapping key, if importing RFC3394 format
[in]targetKeyIdxThe desired key index of the imported key
Parameter properties
options.kfmt != MCUXCLELS_KEYIMPORT_KFMT_RFC3394
  • pImportKey is ignored.
  • importKeyLength is ignored.
  • wrappingKeyIdx is ignored.
  • targetKeyIdx is ignored. The unpacked key is automatically stored in key slots 0, 1.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]wrappingKeyIdxThe key used for key wrapping
[in]exportKeyIdxThe key to export
[out]pOutputThe memory address of the exported key
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[in]keyIdxRequest key properties of the index defined here
[out]pKeyPropKey properties of the index provided
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OKon successful request

Deprecated type for mcuxClEcc component return codes.

Writes random data from the ELS PRNG to the given buffer.

Returns one random word from the ELS PRNG.

Performs characterization of the ELS DTRNG.

Loads a configuration of the ELS DTRNG.

Encrypts data using the AES-CTR engine of the DRBG.

Encrypts data using the AES-ECB engine of the DRBG.

Performs a DRBG extraction.

Instantiates the DRBG in test mode.

This function fills a buffer with random values from the DRBG. The DRBG provides 128 bits of security strength.

Before execution, ELS will wait until mcuxClEls_HwState_t.drbgentlvl == MCUXCLELS_STATUS_DRBGENTLVL_HIGH. This can lead to a delay if the DRBG is in a state with less security strength at the time of the call.

If the random values from the DRBG are later used as a cryptographic key, the security strength of the cryptographic operation using the generated key should not exceed that of the DRBG.

To name a few examples, this means (as per NIST SP 800-57 Part 1 Rev. 5):

  • AES-192 or AES-256 keys generated with this function will provide only 128 bits of security strength
  • RSA keys longer than 3072 bits will provide only 128 bits of security strength
  • ECC keys longer than 383 bits will provide only 128 bits of security strength

Call #mcuxClEls_WaitForOperation to complete the operation.

Parameters
[out]pOutputPointer to the beginning of the memory area to fill with random data
[in]outputLengthNumber of requested random bytes
Parameter properties
outputLength
supported values are MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MIN_SIZE bytes up to MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MAX_SIZE bytes. The size must be a multiple of 4.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function turns the ELS internal DRBG in test mode by loading known entropy from system memory. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pEntropyPointer to the input entropy data
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function mimics the behavior of #mcuxClEls_Rng_DrbgRequest_Async and fills a buffer with random data when DRBG is in test mode. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Attention
#mcuxClEls_Rng_DrbgTestInstantiate_Async must be called prior to this function.
Parameters
[out]pOutputPointer to the output random number
[in]outputLengthLength of the random number
Parameter properties
outputLength
supported values are MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MIN_SIZE bytes up to MCUXCLELS_RNG_DRBG_TEST_EXTRACT_OUTPUT_MAX_SIZE bytes. The size must be a multiple of 4.
Returns
An error code (see MCUXCLELS_STATUS_)
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function performs an AES-ECB encryption on system data to evaluate the encryption engine of the DRBG. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pDataKeyPointer to the data and key
[out]pOutputPointer to the encrypted output
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function is a support function for FIPS CAVP testing. This function performs an AES-CTR encryption on system data to evaluate the encryption engine of the DRBG in test mode. Call #mcuxClEls_WaitForOperation to complete the operation. Note that this function will alter the ELS internal entropy state which needs to be updated by the TRNG to use the DRBG in normal mode. The update process is majorly impacted by the time the TRNG needs to provide fresh entropy.

Parameters
[in]pDataPointer to the data to be encrypted
[in]dataLengthLength of the data to be encrypted
[in]pIvKeyPointer to the IV and key
[out]pOutputPointer to the encrypted output
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function overwrites the default DTRNG configuration in order to optimize or fine tune the DTRNG entropy gathering process. Call #mcuxClEls_WaitForOperation to complete the operation. Note that the TRNG configuration set by this function is non-persistent and any reset of the ELS (e.g. a power-cycle or calling #mcuxClEls_Reset_Async) will resets the DTRNG configuration to its default value.

Parameters
[in]pInputThe pointer to DTRNG initialization data
Parameter properties
pInput
The size is MCUXCLELS_RNG_DTRNG_CONFIG_SIZE bytes.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function evaluates a DTRNG configuration for device specific characterization. The configuration used for characterization has to be placed in system memory. Call #mcuxClEls_WaitForOperation to complete the operation.

Attention
If this function is called once, all other ELS commands except #mcuxClEls_Rng_Dtrng_ConfigEvaluate_Async are blocked until any reset of the ELS (e.g. a power-cycle or calling #mcuxClEls_Reset_Async) is triggered.
Parameters
[in]pInputThe pointer to DTRNG initialization data
[out]pOutputThe pointer to the evaluation result
Parameter properties
pInput
The size is MCUXCLELS_RNG_DTRNG_EVAL_CONFIG_SIZE bytes.
pOutput
The size is MCUXCLELS_RNG_DTRNG_EVAL_RESULT_SIZE bytes.
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_SW_INVALID_PARAMif invalid parameters were specified
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPTif a running operation prevented the request
MCUXCLELS_STATUS_OK_WAITon successful request

This function returns one low-quality random CPU word gathered from the PRNG.

Attention
PRNG has to be initialized prior to the first time calling this function.
Parameters
[out]pWordThe pointer to the random word
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_OKon successful request
MCUXCLELS_STATUS_HW_PRNGin case of insufficient entropy

This function fills a buffer with low-quality random values gathered from the PRNG.

Attention
PRNG has to be initialized prior to the first time calling this function.
Parameters
[out]pOutputPointer to the beginning of the memory area to fill with random data from PRNG
[in]outputLengthSize of pOutput in bytes
Returns
An error code that can be any error code in MCUXCLELS_STATUS_, see individual documentation for more information
Return values
MCUXCLELS_STATUS_OKon successful request
MCUXCLELS_STATUS_HW_PRNGin case of insufficient entropy

Deprecated type for mcuxClEcc component return codes.

Multi-part Hash computation finalization function.

Multi-part Hash processing function.

Multi-part Hash initialization function.

This function performs a hash computation over the input message pIn, using the hash function provided by the algorithm input parameter, in one shot. Up to 2^32 bytes of data can be hashed with this function.

For example, to perform a SHA256 computation, the following needs to be provided:

  • SHA256 algorithm
  • Input data
  • Output hash buffer

The input parameter session has to be initialized by the function mcuxClSession_init prior to calling this function. (MCUXCL_FEATURE_SESSION_HAS_RTF)

Parameters
[in/out]session Handle for the current CL session.
[in]algorithmHash algorithm that should be used during the computation.
[in]pInPointer to the input buffer that contains the data that needs to be hashed.
[in]inSizeNumber of bytes of data in the pIn buffer.
[out]pOutPointer to the output buffer where the computed hash value is written.
[in/out]pOutSize Will be incremented by the number of bytes of data that have been written to the pOut buffer.
Returns
status
Return values
MCUXCLHASH_STATUS_OKHash operation successful
MCUXCLHASH_FAILUREError occured during Hash operation
MCUXCLHASH_STATUS_INVALID_PARAMSThe provided function parameters do not fulfill requirements
MCUXCLHASH_STATUS_FAULT_ATTACKA fault attack was detected

This function performs the initialization for a multi-part hash operation.

Parameters
[in/out]session Handle for the current CL session.
[out]pContextHash context which is used to maintain the state and store other relevant information about the operation.
[in]algorithmHash algorithm that should be used during the computation operation.
Returns
status
Return values
MCUXCLHASH_STATUS_OKInitialization successful
MCUXCLHASH_FAILUREError occurred during initialization function

This function performs the processing of (a part of) a data stream for a Hash operation. The algorithm to be used will be determined based on the context that is provided.

Parameters
[in/out]session Handle for the current CL session.
[in/out]pContext Hash context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that needs to be processed.
[in]inSizeNumber of bytes of data in the pIn buffer.
Returns
status
Return values
MCUXCLHASH_STATUS_OKHash operation successful
MCUXCLHASH_FAILUREError occurred during Hash operation
MCUXCLHASH_STATUS_INVALID_PARAMSThe provided function parameters do not fulfill requirements
MCUXCLHASH_STATUS_FAULT_ATTACKA fault attack was detected

This function performs the finalization of a Hash computation operation. The algorithm to be used will be determined based on the context that is provided

Parameters
[in/out]session Handle for the current CL session.
[in/out]pContext Hash context which is used to maintain the state and store other relevant information about the operation.
[out]pOutPointer to the output buffer where the computed hash value needs to be written.
[out]pOutSizeWill be incremented by the number of bytes of data that have been written to the pOut buffer.
Returns
status
Return values
MCUXCLHASH_STATUS_OKHash operation successful
MCUXCLHASH_FAILUREError occurred during Hash operation

Deprecated type for mcuxClEcc component return codes.

Set the requested key properties of the destination key.

Flush key from destination which can be a key slot of coprocessor or memory buffer.

Load key into destination memory buffer.

Load key into destination key slot of a coprocessor.

Configures they protection mechanism for to the given key handle.

Establishes a key pair link between a private and public key handle.

Initializes a key handle with default protection values.

Parameters
[in]pSessionSession handle to provide session dependent information
[in,out]keyKey handle that will be initialized
[in]typeDefine which key type shall be initialized
[in]pKeyDataProvide pointer to source data of the key. This can be a pointer to a plain key buffer, a share, or a key blob. The protection function defines the purpose of this parameter
[in]keyDataLengthLength of the provided key data pKeyData
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in,out]privKeyKey handle of private key
[in,out]pubKeyKey handle of public key
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in,out]keyKey handle that will be configured
[in]protectionDefine the protection and flush mechanism that shall be used with this key
[in]pAuxDataProvide pointer to additional data the protection function may use
[in]parentKeyProvide parent key information in case it exists. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to load the key
[out]dstSlotProvide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to load the key
[out]dstDataProvide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in]pSessionSession handle to provide session dependent information
[in]keyKey handle that provides information to flush the key
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation
Parameters
[in,out]keykey handle that provides information to flush the key
[in]key_propertiesPointer to the requested key properties of the destination key. Will be set in key->container.pAuxData
Returns
An error code that can be any error code in MCUXCLKEY_STATUS_, see individual documentation for more information
Return values
MCUXCLKEY_STATUS_ERRORon unsuccessful operation
MCUXCLKEY_STATUS_OKon successful operation

Deprecated type for mcuxClEcc component return codes.

Finalize a MAC generation for a multipart MAC computation.

Data processing for a multipart MAC computation.

Initialization for a multipart MAC computation.

This function performs a MAC computation in one shot. The algorithm to be used will be determined based on the key that is provided.

For example, to perform an AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided:

  • AES128 key
  • CMAC mode
  • Input data
  • Output data buffer, at least the size of a single AES block
Attention
In some cases restrictions may apply, e.g. the input buffer must be prepared for padding. Please refer to mcuxClMac_Modes.h to find further details and restrictions for each specific mode.
Parameters
[in]sessionHandle for the current CL session.
[in]keyKey to be used to authenticate the data.
[in]modeMode that should be used during the MAC operation.
[in]pInPointer to the input buffer that contains the data that needs to be authenticated.
[in]inLengthNumber of bytes of data in the pIn buffer.
[out]pMacPointer to the output buffer where the MAC needs to be written.
[out]pMacLengthWill be incremented by the number of bytes of data that have been written to the pMac buffer.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function performs the initialization of a context for a multipart MAC computation. The algorithm to be used will be determined based on the key that is provided.

This function should only be called once, as the first step for a multipart computation.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • AES128 key
  • CMAC mode

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

Parameters
[in]sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[in]keyKey to be used to MAC the data.
[in]modeMode that should be used during the MAC operation.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function performs the data processing for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided.

This function can be called multiple times, after the multipart context initialization.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • Input data

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also
mcuxClMac_init
Parameters
sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[in]pInPointer to the input buffer that contains the data that need to be processed.
[in]inLengthNumber of bytes of data in the in buffer.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

This function performs the final MAC generation step for a multipart MAC computation. The algorithm and key to be used will be determined based on the context that is provided.

This function should only be called once, as the last step for a multipart computation.

For example, to perform a multipart AES MAC computation with a 128-bit key in CMAC mode on padded data, the following needs to be provided in this step:

  • Output data buffer, at least the size of a single AES block

The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).

See also
mcuxClMac_init
mcuxClMac_process
Parameters
[in]sessionHandle for the current CL session.
[in]pContextMAC context which is used to maintain the state and store other relevant information about the operation.
[out]pMacPointer to the output buffer where the MAC needs to be written.
[out]pMacLengthWill be incremented by the number of bytes of data that have been written to the pMac buffer.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMAC_STATUS_OKMac operation successful
MCUXCLMAC_STATUS_ERRORError occurred during Mac operation
MCUXCLMAC_STATUS_INVALID_PARAMAn invalid parameter was given to the function
MCUXCLMAC_STATUS_FAULT_ATTACKFault attack detected

Deprecated type for mcuxClEcc component return codes.

Securely calculates modular exponentiation.

This function counts the number of trailing zero bits of a PKC operand at offset UPTRT[iX] and of size PS1 OPLEN.

Parameters
[in]iXindex of PKC operand
Parameter properties
iX
index of X (PKC operand), size = operandSize.
The offset (UPTRT[iX]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PKC properties
PS1 lengths
PS1 OPLEN defines operandSize and shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
PS2 lengths
Unused.
ACTIV/GOANY
This function will not use PKC, and assumes PKC will not modify the operand iX simultaneously.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
#numTrailingZeroesNumber of trailing zeroes

This function calculates modular exponentiation in a secure manner. It randomizes the computation by Euclidean splitting: exponent = b * q + r, where b is a 64-bit odd random number (with both MSbit and LSbit set), and r = exponent % b. The exponentiation is calculated by two steps: (1) m0 = m^q mod n; and (2) result = m0^b * m^r mod n. In addition, base operands are re-randomized, by adding random multiples of the modulus to them before performing modular multiplications.

Parameters
[in]pSessionhandle for the current CL session.
[in]pExppointer to exponent
[in]pExpTemppointer to temporary buffer
[in]expByteLengthbyte length of exponent
[in]iT3_iX_iT2_iT1indices of PKC operands
[in]iN_iTE_iT0_iRindices of PKC operands
[in]secOptionoption to disable the operand re-randomization
Parameter properties
session:
The session pointed to by pSession has to be initialized prior to a call to this function.
pExp
the exponent is a big-endian octet string and shall be non-zero.
pExpTemp
the temporary buffer can be in either CPU or PKC workarea.
It shall be CPU word aligned, and its length shall be a multiple of CPU word and greater than expByteLength.
It can share the space with exponent (i.e., pExpTemp = pExp), but the exponent will be overwritten.
iT3_iX_iT2_iT1
iT1 (bits 0~7): index of temp1 (PKC operand).
Its size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iT2 (bits 8~15): index of temp2 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iX (bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE).
It will be overwritten.
iT3 (bits 24~31): index of temp3 (PKC operand).
Its size shall be at least max(lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE).
iN_iTE_iT0_iR
iR (bits 0~7): index of result (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iT0 (bits 8~15): index of temp0 (PKC operand).
The size shall be at least max(MCUXCLPKC_ROUNDUP_SIZE(expByteLength + 1), lenN + MCUXCLPKC_WORDSIZE).
iTE (bits 16~23): index of temp4 (PKC operand).
The size shall be at least (6 * MCUXCLPKC_WORDSIZE).
iN (bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN).
The upper 32 bits of N shall be null, which can be obtained for instance by applying 32-bit modulus blinding, or by artificially increasing PS1 lengths and all buffer sizes by 1 PKC word.
NDash of modulus shall be stored in the PKC word before modulus.
PKC properties
PS1 lengths
PS1 OPLEN = MCLEN defines operandSize = MCUXCLPKC_ROUNDUP_SIZE(lenN), where lenN is the length of modulus n. As the upper 32 bits of N should be null, operandSize >= lenN + 4 bytes.
PS2 lengths
PS2 OPLEN and MCLEN will be modified, and original values will not be restored.
ACTIV/GOANY
#mcuxClPkc_WaitForReady will be called before returning to caller. The PKC calculation might be still on-going, call #mcuxClPkc_WaitForFinish before CPU accesses to the result.
Returns
A code-flow protected error code (see Flow Protection API)
Return values
MCUXCLMATH_ERRORCODE_OKfunction executed successfully
MCUXCLMATH_ERRORCODE_ERRORerror occurred during operation
Attention
This function uses PRNG which has to be initialized prior to calling the function.

Deprecated type for mcuxClEcc component return codes.

Randomize UPTR table and operands in PKC workarea.

This function randomly permutes offsets stored in UPTR table. It randomizes the buffer allocation (physical address in PKC workarea). When calling this function, there shall be no on-going and pending PKC calculations using the specified UPTR table elements.

Parameters
[in]pSessionhandle for the current CL session.
[in,out]pUPTRTpointer to the first element to be randomized in UPTR table.
[in]noOfBuffernumber of elements to be randomized.
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pUPTRT
this pointer shall be 2-byte aligned.
Attention
Only the buffer allocation will be randomized, existing operands stored in each buffer will not be moved accordingly.
This function uses PRNG. Caller needs to check if PRNG is ready.
Returns
A flow-protected status code (see Flow Protection API).
Return values
MCUXCLPKC_STATUS_OKif UPTR table is randomized successfully.
MCUXCLPKC_STATUS_NOKif the operation failed.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function randomly permutes offsets stored in UPTR table, together with operands stored in each buffer in PKC workarea. It randomizes the buffer allocation (physical address in PKC workarea) and moves operands stored accordingly. When calling this function, there shall be no on-going and pending PKC calculations using the specified UPTR table elements.

Parameters
[in]pSessionhandle for the current CL session.
[in,out]pUPTRTpointer to the first element to be randomized in UPTR table.
[in]bufferLengthbyte length of each buffer in PKC workarea.
[in]noOfBuffernumber of elements to be randomized.
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pUPTRT
this pointer shall be 2-byte aligned.
All offsets (pUPTRT[0~(noOfBuffer-1)]) shall be exactly a multiple of MCUXCLPKC_WORDSIZE.
bufferLength
this length shall be a multiple of MCUXCLPKC_WORDSIZE.
Attention
This function uses PRNG. Caller needs to check if PRNG is ready.
Returns
A flow-protected status code (see Flow Protection API).
Return values
MCUXCLPKC_STATUS_OKif UPTR table is randomized successfully.
MCUXCLPKC_STATUS_NOKif the operation failed.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

Deprecated type for mcuxClEcc component return codes.

Non-cryptographic PRNG data generation function.

Non-cryptographic PRNG initialization function.

Random data generator security strength check.

Random data generator self-test function.

Random data generator uninitialization function.

Random data generation function.

Random data generator reseed function.

This function performs the initialization of a random data generator. This operation initializes the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
[in]pContextPointer to a Random data context buffer large enough to hold the context for the selected mode
[in]modeMode of operation for random data generator.
Returns
status

This function performs the reseeding of a random data generator. This operation fetches a fresh seed from a TRNG and updates the state in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function generates random data based on the information contained in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
[out]pOutBuffer in which the generated random data must be written.
[in]outLengthNumber of random data bytes that must be written in the pOut buffer.
Returns
status

This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function performs a series of selft-tests on the random data generator. These tests are performed on the random data generator defined by Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function reports whether the the random data generator can provide the requested security strength.

Parameters
[in]pSessionHandle for the current CL session.
[in]securityStrengthRequested security strength in bits.
Returns
status

This function performs the initialization of the non-cryptographic random number generator.

Parameters
[in]pSessionHandle for the current CL session.
Returns
status

This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.

Parameters
[in]pSessionHandle for the current CL session.
[out]pOutBuffer in which the generated random data must be written.
[in]outLengthNumber of random data bytes that must be written in the pOut buffer.
Returns
status

Deprecated type for mcuxClEcc component return codes.

The function expects as input a custom function to be used inside the CL functions for random number generation as well as a pointer to a context buffer which can be used by the custom generate function. The custom generate function may also use all CPU workarea allocated for the mcuxClRandom_generate function. The function shall be called prior to an mcuxClRandom_init call.

Parameters
patchMode[out]Pointer to PATCH_MODE descriptor to be initialized
customGenerateAlgorithm[in]Pointer to the custom generate function
pEntropyInput[in]Pointer to a custom context which shall be used by the passed custom generate function
securityStrength[in]Security level for which the patch DRBG shall be used
Returns
status

Deprecated type for mcuxClEcc component return codes.

This function updates the entropy input pointer in a TEST_MODE descriptor.

The function expects as input a pointer to a buffer to which the user of the CL shall write entropy input to be used for (re)seeding the DRBG. The function shall be called prior to an mcuxClRandom_init call.

Parameters
testMode[out]Pointer to TEST_MODE descriptor to be initialized
normalMode[in]Pointer to NORMAL_MODE descriptor to be used as basis for the initialization
pEntropyInput[in]Pointer to memory buffer containing entropy input for DRBG (re)seeding
Returns
status
Parameters
testMode[in]Pointer to TEST_MODE descriptor
pEntropyInput[in]Pointer to memory buffer containing entropy input for DRBG (re)seeding
Returns
  • MCUXCLRANDOM_STATUS_OK if the TEST_MODE descriptor generation was successful

Deprecated type for mcuxClEcc component return codes.

RSA key generation of private plain key operation.

Generates an RSA key in CRT format.

RSA verify operation.

This function performs an RSA signature generation according to RSASP1, RSASSA-PSS-SIGN or RSASSA-PKCS1-v1_5-SIGN of PKCS #1 v2.2. Based on the passed key type, it is selected, whether to perform this operation using a private plain, a private CRT key, or whether to use a private CRT key and protect the operation against perturbation attacks. Based on the selection of the padding mode, it is determined, whether to perform no padding, or whether to perform one of the supported paddings based on one of the supported hash functions. The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8. The private exponent is limited to d < n.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]pKeyPointer to key structure of type mcuxClRsa_Key
[in]pMessageOrDigestPointer to buffer, which contains the input to the sign operation
[in]messageLengthByte-length of MessageOrDigest
[in]pPaddingModePointer to signing mode of type mcuxClRsa_SignVerifyMode_t
[in]saltLengthByte-length of salt
[in]optionsOptions field
[out]pSignaturePointer to buffer, which contains the result (signature)
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pKey:
The key entries must meet the following conditions:
pMessageOrDigest:
The input must meet the following conditions:
messageLength:
This value is only regarded in case of option MCUXCLRSA_OPTION_MESSAGE_PLAIN. In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST, or mode RSASP1, please set to zero.
pPaddingMode:
The mode specifies the targeted padding and hashing algorithms. Please set to one of mcuxClRsa_Sign_Modes.
saltLength:
This value is only regarded in case of performing a RSASSA-PSS-SIGN operation. Otherwise, please set to zero.
options:
This field is used to select options of the sign operation:
pSignature:
The output is returned in in big-endian byte order.
Returns
Status of the mcuxClRsa_sign operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_SIGN_OKSign operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function performs an RSA signature verification according to RSAVP1, RSASSA-PSS-VERIFY or RSASSA-PKCS1-v1_5-VERIFY of PKCS #1 v2.2. Based on the selection of the padding mode, it is determined, whether to perform no padding verification, or whether to perform one of the supported padding verifications based on one of the supported hash functions. The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8. The public exponent is limited to 2 <= e < N.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]pKeyPointer to key structure of type mcuxClRsa_Key
[in]pMessageOrDigestPointer to buffer, which contains the input to the verify operation
[in]messageLengthByte-length of MessageOrDigest
[in]pSignaturePointer to buffer, which contains the signature
[in]pVerifyModePointer to verification mode of type mcuxClRsa_SignVerifyMode_t
[in]saltLengthByte-length of salt
[in]optionsOptions field
[out]pOutputPointer to output buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function.
pKey:
The key entries must meet the following conditions:
  • Entry keytype must be set to MCUXCLRSA_KEY_PUBLIC. In case of passing another key type, the function returns MCUXCLRSA_STATUS_INVALID_INPUT. The functions checks, internally, whether the required key entries are not set to NULL. If so, the function returns MCUXCLRSA_STATUS_INVALID_INPUT;
  • The supported bit-lengths of the modulus range from 512 to 4096 in multiples of 8;
  • It is required that e is greater or equal to 2 and smaller than n.
pMessageOrDigest:
The input must meet the following conditions:
  • It must be provided in big-endian byte order;
  • In case of mode RSAVP1, please set to NULL.
messageLength:
This value is only regarded in case of option MCUXCLRSA_OPTION_MESSAGE_PLAIN. In case of option MCUXCLRSA_OPTION_MESSAGE_DIGEST, or mode RSAVP1, please set to zero.
pSignature:
The signature must meet the following conditions:
  • It must be given in big-endian byte order;
  • The signature length is determined by the modulus length (bytelength(n));
  • The signature value must be smaller than n. If it is bigger the function returns MCUXCLRSA_STATUS_INVALID_INPUT.
pVerifyMode:
The mode specifies the targeted padding verification and hashing algorithms. Please set to one of mcuxClRsa_Verify_Modes.
saltLength:
This value is only regarded in case of performing a RSASSA-PSS-VERIFY operation. Otherwise, please set to zero.
options:
This field is used to select options of the sign operation:
pOutput:
In case of mode RSAVP1 this pointer points to the buffer, where the result will be stored in big-endian byte order. This buffer must have the same byte-length as the modulus. In case of modes RSASSA-PSS-VERIFY and RSASSA-PKCS1-v1_5-VERIFY please set to NULL.
Returns
Status of the mcuxClRsa_verify operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_VERIFY_OKVerify operation executed successfully.
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OKVerification primitive operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_VERIFY_FAILEDThe signature verification failed.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses PRNG which has to be initialized prior to calling the function.

This function for given public exponent and key size generates an RSA private key in CRT representation (p, q, dp, dq, qInv) and computes the modulus n.

Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key.
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private CRT key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill be set by the number of bytes of data that have been written to the pPubData buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.
type:
Type of the key. It contains information about the input parameters:
  • type.size - length of the generated key
  • type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t* (i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).
protection :
Protection and flush mechanism that must be applied to the generated key.
privKey:
Key handle for the generated private key.
pPrivData:
Pointer to the buffer where the generated private CRT key (p, q, qInv, dp, dq) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: p, q, qInv, dp, dq. Buffer is allocated by the caller.
pPrivDataLength:
Number of bytes of data that have been written to the pPrivData buffer.
pubKey:
Key handle for the generated public key.
pPubData:
Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.
pPubDataLength:
Number of bytes of data that have been written to the pPubData buffer.
Returns
Status of the mcuxClRsa_KeyGeneration_Crt operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_KEYGENERATION_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses DRBG and PRNG which have to be initialized prior to calling the function.

This function for given public exponent and key size generates RSA private key in in plain from (d, n).

Private exponent d is computed with the requirements specified in the FIPS 186-4, Appendix B.3.1. Primes p and q are generated based on the method specified in the FIPS 186-4, Appendix B.3.3 using probabilistic primality test with the probability of not being prime less than 2^(-125). The public exponent is restricted to (FIPS compliant) odd values in the range 2^16 < e < 2^256 (i.e. including 0x10001). The bit-length of the key size is limited to 2048, 3072 and 4096. The keys generated by this function are FIPS 186-4 compliant provided their length is either 2048 or 3072 bits and the exponent value is an odd integer between 2^16 and 2^256.

Parameters
[in]pSessionPointer to mcuxClSession_Descriptor
[in]typeType of the key
[in]protectionProtection and flush mechanism that must be applied to the generated key
[out]privKeyKey handle for the generated private key
[out]pPrivDataPointer to the buffer where the generated private plain key data needs to be written
[out]pPrivDataLengthWill be set by the number of bytes of data that have been written to the pPrivData buffer
[out]pubKeyKey handle for the generated public key
[out]pPubDataPointer to the buffer where the generated public key data needs to be written
[out]pPubDataLengthWill be set by the number of bytes of data that have been written to the pPubData buffer
Parameter properties
pSession:
The session pointed to by pSession has to be initialized prior to a call to this function. The RNG shall be initialized with the entropy level (security strength) in accordance with the value of type.size, as specified in SP 800-57, Part 1.
type:
Type of the key. It contains information about the input parameters:
  • type.size - length of the generated key
  • type.info - pointer to key entry i.e. public exponent. It points to data type mcuxClRsa_KeyEntry_t*(i.e. pointer to buffer containing the public exponent data and byte-length of the public exponent).
protection :
Protection and flush mechanism that must be applied to the generated key.
privKey:
Key handle for the generated private key.
pPrivData:
Pointer to the buffer where the generated private plain key (n, d) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, d. Buffer is allocated by the caller.
pPrivDataLength:
Number of bytes of data that have been written to the pPrivData buffer.
pubKey:
Key handle for the generated public key.
pPubData:
Pointer to the buffer where the generated public key (n, e) data needs to be written. This buffer contains key type and key entries (mcuxClRsa_Key data type) followed by the key data, i.e.: n, e. Buffer is allocated by the caller.
pPubDataLength:
Number of bytes of data that have been written to the pPubData buffer.
Returns
Status of the mcuxClRsa_KeyGeneration_Plain operation (see MCUX_CSSL_FP_PROTECTED_TYPE(mcuxClRsa_Status_t))
Return values
MCUXCLRSA_STATUS_KEYGENERATION_OKRSA key generation operation executed successfully.
MCUXCLRSA_STATUS_INVALID_INPUTThe input parameters are not valid.
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDEDRSA key generation exceeds the limit of iterations to generate a prime.
MCUXCLRSA_STATUS_ERRORAn error occurred during the execution. In that case, expectations for the flow protection are not balanced.
Attention
This function uses DRBG and PRNG which have to be initialized prior to calling the function.

Deprecated type for mcuxClEcc component return codes.

Destroy a Crypto Library session.

Clean up a Crypto Library session.

Set the RTF option in a Crypto Library session.

Parameters
pSessionSession to be initialized.
pCpuWaBufferPointer to buffer to be used as workarea for CPU operations. This pointer shall be CPU-word aligned.
cpuWaLengthSize (in bytes) of the workarea for CPU operations. The size shall be a multiple of CPU wordsize.
pPkcWaBufferPointer to buffer to be used as workarea for PKC operations. This pointer shall be PKC-word aligned.
pkcWaLengthSize (in bytes) of the workarea for PKC operations. The size shall be a multiple of CPU wordsize.
Returns
status
Return values
MCUXCLSESSION_STATUS_OKSession has been initialized successfully
MCUXCLSESSION_STATUS_ERRORError occurred during session initializing.
Parameters
pSessionSession to be initialized.
pRtfbuffer to store the rtf result.
RtfOptionsOptions to define RTF processing.
Returns
status

This function will (securely) cleanup the session, which will still be usable afterwards.

Parameters
pSessionSession to be cleaned.
Returns
status

This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.

Parameters
pSessionSession to be destroyed.
Returns
status

Deprecated type for mcuxClEcc component return codes.

The implementation is secure in the following aspects: Parameter integrity protection: the function returns immediately in case of an incorrect parameter checksum. Code flow protection: the function call is protected. Buffer overflow protection: no data is written to pDst beyond dstLength bytes.

Parameters
[in]chkThe parameter checksum, generated with mcuxCsslParamIntegrity_Protect.
[in]pDstThe destination pointer to buffer to be cleared. Must not be NULL.
[in]dstLengthThe size of the destination data buffer in bytes.
[in]lengthThe number of bytes to clear. Must be different from zero.
Returns
A status code encapsulated in a flow-protection type.
Return values
MCUXCSSLMEMORY_STATUS_OKIf the contents in buffer at pDst is cleared.
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETERIf one of the parameters is invalid.
MCUXCSSLMEMORY_STATUS_FAULTIf a fault was detected, included invalid checksum chk.

Deprecated type for mcuxClEcc component return codes.

The implementation is secure in the following aspects:

  • Constant execution time: The execution sequence of the code is always identical for equal length parameters, i.e. no branches are performed based on the data in pLhs or pRhs.
  • Parameter integrity protection: An incorrect parameter checksum makes the function return immediately.
  • Code flow protection: The function call is protected. Additionally, the result depends on all steps of the calculation.
Parameters
chkThe parameter checksum, generated with mcuxCsslParamIntegrity_Protect.
pLhsThe left-hand side data to compare. Must not be NULL.
pRhsThe right-hand side data to compare. Must not be NULL.
lengthThe number of bytes to compare. Must be different from zero.
Returns
A status code encapsulated in a flow-protection type.
Return values
MCUXCSSLMEMORY_STATUS_EQUALIf the contents of lhs and rhs are equal.
MCUXCSSLMEMORY_STATUS_NOT_EQUALIf the contents of lhs and rhs are not equal.
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETERIf one of the parameters was invalid (i.e. lhs or rhs was NULL or length was zero).
MCUXCSSLMEMORY_STATUS_FAULTIf a fault was detected.

Deprecated type for mcuxClEcc component return codes.

The implementation is secure in the following aspects:

  • Constant execution time: If pSrc and pDst have the same offset to the nearest 16-byte boundary, and if length is the same, the execution sequence of the code is always identical.
  • Parameter integrity protection: An incorrect parameter checksum makes the function return immediately.
  • Code flow protection: The function call is protected. Additionally, the result depends on all steps of the calculation.
  • Buffer overflow protection: No data is written to pDst beyond dstLength bytes.
Parameters
[in]chkThe parameter checksum, generated with mcuxCsslParamIntegrity_Protect.
[in]pSrcThe data to be copied. Must not be NULL. Must not overlap with pDst.
[out]pDstThe destination pointer. Must not be NULL. Must not overlap with pSrc.
[in]dstLengthThe size of the destination data buffer in bytes.
[in]lengthThe number of bytes to copy. Must be different from zero.
Returns
A status code encapsulated in a flow-protection type.
Return values
MCUXCSSLMEMORY_STATUS_OKIf the contents of src and dst are equal.
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETERIf one of the parameters was invalid (i.e. pSrc or pDst was NULL or length was zero).
MCUXCSSLMEMORY_STATUS_FAULTIf a fault was detected.

Deprecated type for mcuxClEcc component return codes.

The implementation is secure in the following aspects: Parameter integrity protection: the function returns immediately in case of an incorrect parameter checksum. Code flow protection: the function call is protected. Buffer overflow protection: no data is written to pDst beyond bufLength bytes.

Parameters
[in]chkThe parameter checksum, generated with mcuxCsslParamIntegrity_Protect.
[in]pDstThe destination pointer to buffer to be set. Must not be NULL.
[in]valThe byte value to be set.
[in]lengthThe size in bytes to set. Must be different from zero.
[in]bufLengthThe buffer size (if bufLength < length, only bufLength bytes are set).
Returns
A status code encapsulated in a flow-protection type.
Return values
MCUXCSSLMEMORY_STATUS_OKIf val set length times at pDst.
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETERIf one of the parameters is invalid.
MCUXCSSLMEMORY_STATUS_FAULTIf a fault was detected, included invalid checksum chk.

Deprecated type for mcuxClEcc component return codes.

Parameters
chkThe parameter checksum.
nargsThe number of parameters to be protected.
...The parameters that were used to calculate the parameter checksum. Note that parameters bigger than a single machine word are not supported.
Returns
A status code encapsulated in a flow-protection type.
Return values
MCUXCSSLPARAMINTEGRITY_CHECK_VALIDThe parameter checksum was correct.
MCUXCSSLPARAMINTEGRITY_CHECK_INVALIDThe parameter checksum was incorrect.