Defines all types of mcuxClEls_Types. More...
Data Structures | |
union | mcuxClEls_KeyProp_t |
Type for ELS key store key properties. More... | |
Macros | |
#define | utlpsms |
Deprecated name for mcuxClEls_KeyProp_t.utlspms. More... | |
Typedefs | |
typedef uint32_t | mcuxClEls_Status_t |
Type for ELS driver status codes. More... | |
typedef uint32_t | mcuxClEls_KeyIndex_t |
Type for ELS keystore indices. More... | |
typedef mcuxClEls_Status_t(* | mcuxClEls_TransferToRegisterFunction_t) (uint32_t volatile *pDestRegister, uint8_t const *pSource, size_t sourceLength, void *pCallerData) |
Function type for transfer of data to a memory-mapped register. More... | |
Functions | |
typedef | MCUX_CSSL_FP_PROTECTED_TYPE (mcuxClEls_Status_t) mcuxClEls_Status_Protected_t |
Deprecated type for ELS driver protected status codes. More... | |
Defines all types of mcuxClEls_Types.
#define utlpsms |
Deprecated name for mcuxClEls_KeyProp_t.utlspms.
typedef uint32_t mcuxClEls_Status_t |
Type for ELS driver status codes.
typedef uint32_t mcuxClEls_KeyIndex_t |
Type for ELS keystore indices.
typedef mcuxClEls_Status_t(* mcuxClEls_TransferToRegisterFunction_t) (uint32_t volatile *pDestRegister, uint8_t const *pSource, size_t sourceLength, void *pCallerData) |
Function type for transfer of data to a memory-mapped register.
This function type is used as a callback for handling data transfer from memory to a memory-mapped register. Such a function shall read data from the uint8_t
array source, and write data via a sequence of writes to destRegister
. Further specification of this function's behavior can be found in the documentation of the function that accepts this function as a callback parameter.
[out] | pDestRegister | Memory-mapped register that the output data shall be written to |
[in] | pSource | Array containing the input data |
[in] | sourceLength | Size of source in bytes |
[in,out] | pCallerData | Custom pointer that is provided by the caller and forwarded to the callback function by the operation |
typedef MCUX_CSSL_FP_PROTECTED_TYPE | ( | uint32_t | ) |
Deprecated type for ELS driver protected status codes.
Deprecated type for ELS driver protected status 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.
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.
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:
session | Handle for the current CL session. | |
key | Key to be used to encrypt the data. | |
mode | AEAD mode that should be used during the encryption operation. | |
[in] | pNonce | Pointer to the buffer that contains the nonce. |
nonceLength | Number of bytes of nonce data in the nonce buffer. | |
[in] | pIn | Pointer to the input buffer that contains the plain data that need to be authenticated and encrypted. |
inLength | Number of bytes of plain data in the in buffer. | |
[in] | pAdata | Associated data for the authenticated encryption operation. Data format depends on the chosen mode . |
adataLength | Number of bytes of associated data in the adata buffer. | |
[out] | pOut | Pointer to the output buffer where the authenticated encrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of authenticated encrypted data that have been written to the out buffer. |
[out] | pTag | Pointer to the output buffer where the tag needs to be written. |
tagLength | Number of bytes of tag data that will be written to the tag buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | AEAD mode that should be used during the encryption/decryption operation. | |
[in] | pNonce | Pointer to the buffer that contains the nonce. |
nonceLength | Number of bytes of nonce data in the nonce buffer. | |
inLength | Number of bytes of plain data that will be processed. | |
adataLength | Number of bytes of associated data that will be processed. | |
tagLength | Number of bytes to be used for the authentication tag. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the in buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the out buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pAdata | Associated data that needs to be proccessed. |
adataLength | Number of bytes of associated data in the adata buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the out buffer. |
[out] | pTag | Pointer to the output buffer where the tag needs to be written. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pTag | Pointer to the buffer that contains the tag. |
[out] | pOut | Pointer to the output buffer where the authenticated decrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of authenticated decrypted data that have been written to the out buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
MCUXCLECC_STATUS_OK | if signature is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if ECDSA Signature is valid; |
MCUXCLECC_STATUS_INVALID_SIGNATURE | if ECDSA Signature is invalid; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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).
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | pParam | pointer to ECC point multiplication parameter structure. |
MCUXCLECC_STATUS_OK | if point multiplication is calculated successfully, and the result is not the neutral point; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_NEUTRAL_POINT | if result is the neutral point; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | mcuxClSession_Descriptor structure |
[in] | type | type structure specifying requested key type to be generated. Also contains domain parameters |
[in] | protection | #mcuxClKey_Protection structure |
[out] | privKey | private key handling structure |
[out] | pPrivData | buffer for private key of the MCUXCLECC_MONT_CURVE25519/448_SIZE_PRIVATEKEY length |
[out] | pPrivDataLength | private key length |
[out] | pubKey | public key handling structure |
[out] | pPubData | buffer for public key x-coordinate of MCUXCLECC_MONT_CURVE25519/448_SIZE_PUBLICKEY length |
[out] | pPubDataLength | public key x-coordinate length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | key | private key handling structure |
[in] | otherKey | public key handling structure |
[out] | pOut | buffer for shared secret of length MCUXCLECC_MONT_CURVE25519/448_SIZE_SHAREDSECRET |
[out] | pOutLength | shared secret length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUP | if calculated public key lies in small subgroup. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
[in] | pSession | Handle 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] | pPrivKey | Pointer to private key input |
MCUXCLECC_STATUS_OK | EdDSA mode descriptor has been initialized successfully |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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
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.
[in] | pSession | Handle for the current CL session |
[in] | mode | Mode descriptor specifying the EdDSA GenerateKeyPair variant |
[in/out] | privKey Key handle for the private key. | |
[in/out] | pubKey Key handle for the public key. |
MCUXCLECC_STATUS_OK | private key data and public key have been generated successfully |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key 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] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[out] | pSignature | Pointer to buffer where the signature (Renc,S) will be stored |
[out] | pSignatureSize | Will be set to the number of bytes of data that have been written to the pSignature buffer |
MCUXCLECC_STATUS_OK | signature generation was successful |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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:
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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key handle for public key Qenc |
[in] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[in] | pSignature | Pointer to buffer containing the signature (Renc,S) |
[in] | signatureSize | Number of bytes of data in the pSignature buffer |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_INVALID_SIGNATURE | EdDSA signature is invalid |
MCUXCLECC_STATUS_INVALID_PARAMS | input parameters are invalid |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
[in] | pSession | pointer to mcuxClSession_Descriptor |
[in] | pDomainParams | Pointer to domain parameters of the used curve |
[in] | pProtocolDescriptor | Protocol descriptor specifying the EdDSA variant |
[in] | phflag | Option whether pre-hashing is enabled |
[in] | pContext | User input context for the hash prefix |
[in] | contextLen | Length of the context |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
This function allows to generate custom key types according to the passed algoId
.
[out] | customType | Handle for the custom key type. |
[in] | algoId | Algorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
|
[in] | size | Algorithm based key size. |
[in] | pCustomParams | Pointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
|
MCUXCLECC_STATUS_OK | if custom key type is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if Parameters are invalid. |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pAad | Memory area that contains the AAD |
[in] | aadLength | Length of the pAad in bytes with padding |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pInput | Pointer to the memory location of the data to be processed |
[in] | inputLength | Size of pInput in bytes with padding |
[out] | pOutput | Pointer to the processed data memory location |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | aadLength | Length of the complete Additional Authenticated Data (AAD) in bytes, without padding. |
[in] | dataLength | Length of the complete plaintext/ciphertext in bytes, without padding. |
[out] | pTag | Pointer where the resulting tag will be stored |
[in] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
[out] | result | Pointer which will be filled with the ELS status information |
Call #mcuxClEls_WaitForOperation to complete the operation.
This means that:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | A value indicating whether any running ELS operations shall be canceled |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the reset |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This is useful as a power saving mechanism.
[in] | options | The command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t. |
[out] | result | Pointer which is filled with the configuration of the interrupts enable register. |
[in] | options | The command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t. |
[in] | options | The command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t. |
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.
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
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.
[in] | counterLimit | The limit of the wait counter. |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
MCUXCLELS_STATUS_SW_COUNTER_EXPIRED | if the counter expired while waiting for the operation to complete |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
[in] | errorHandling | Define if error flags shall be cleared. |
[out] | errorLevel | Pointer to the location that will receive the value of the error level. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
#MCUXCLELS_STATUS_ | if the last operation resulted in an error |
This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async
[in] | delay | Define the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023). |
MCUXCLELS_STATUS_OK | if the operation was successful |
[out] | delay | Pointer to store random start delay configuration. |
MCUXCLELS_STATUS_OK | if the operation was successful |
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).
[in] | privateKeyIdx | The private key index. |
[in] | pPublicKey | Pointer to the public key of a third party. |
[in] | sharedSecretIdx | The index in the ELS keystore that receives the shared secret that is generated by the ECDH operation. |
[in] | sharedSecretProperties | The desired key properties of the shared secret. |
pPublicKey
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccSignOption_t. |
[in] | keyIdx | The private key index. |
[in] | pInputHash | The hash of the message to sign in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[out] | pOutput | Pointer to the memory area which receives the generated signature in X9.62 format. (64 bytes) |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccVerifyOption_t. |
[in] | pInputHash | The hash of the signed message in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[in] | pSignatureAndPubKey | Pointer to the memory area which contains the concatenation of the signature and the public key. |
[out] | pOutput | Pointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification. |
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
pOutput
pSignatureAndPublicKey
. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[out] | pTagetKey | Memory 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] | pDerivationData | The algorithm-specific derivation data |
[in] | derivationDataLength | Length of the derivation data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation |
[in] | targetKeyIdx | Key bank number of the derived key |
[in] | targetKeyProperties | Requested properties for the derived key. Only set usage bits. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The index of the TLS pre-master key, which is overwritten with the master key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The 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. |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | One of MCUXCLELS_KEYIMPORT_KFMT_ |
[in] | pImportKey | Pointer to the RFC3394 container of the key to be imported |
[in] | importKeyLength | Length of the RFC3394 container of the key to be imported |
[in] | wrappingKeyIdx | Index of the key wrapping key, if importing RFC3394 format |
[in] | targetKeyIdx | The desired key index of the imported key |
options.kfmt
!= MCUXCLELS_KEYIMPORT_KFMT_RFC3394pImportKey
is ignored. importKeyLength
is ignored. wrappingKeyIdx
is ignored. targetKeyIdx
is ignored. The unpacked key is automatically stored in key slots 0, 1. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | wrappingKeyIdx | The key used for key wrapping |
[in] | exportKeyIdx | The key to export |
[out] | pOutput | The memory address of the exported key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | keyIdx | Request key properties of the index defined here |
[out] | pKeyProp | Key properties of the index provided |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK | on 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.
[in] | pEntropy | Pointer to the input entropy data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[out] | pOutput | Pointer to the output random number |
[in] | outputLength | Length of the random number |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pDataKey | Pointer to the data and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pData | Pointer to the data to be encrypted |
[in] | dataLength | Length of the data to be encrypted |
[in] | pIvKey | Pointer to the IV and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
pInput
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
[out] | pOutput | The pointer to the evaluation result |
pInput
pOutput
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This function returns one low-quality random CPU word gathered from the PRNG.
[out] | pWord | The pointer to the random word |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function fills a buffer with low-quality random values gathered from the PRNG.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data from PRNG |
[in] | outputLength | Size of pOutput in bytes |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function performs the initialization for a multi-part hash operation.
[in/out] | session Handle for the current CL session. | |
[out] | pContext | Hash context which is used to maintain the state and store other relevant information about the operation. |
[in] | algorithm | Hash algorithm that should be used during the computation operation. |
MCUXCLHASH_STATUS_OK | Initialization successful |
MCUXCLHASH_FAILURE | Error 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.
[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] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A 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
[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] | pOut | Pointer to the output buffer where the computed hash value needs to be written. |
[out] | pOutSize | Will be incremented by the number of bytes of data that have been written to the pOut buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | privKey | Key handle of private key |
[in,out] | pubKey | Key handle of public key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be configured |
[in] | protection | Define the protection and flush mechanism that shall be used with this key |
[in] | pAuxData | Provide pointer to additional data the protection function may use |
[in] | parentKey | Provide parent key information in case it exists. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstSlot | Provide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstData | Provide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to flush the key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in,out] | key | key handle that provides information to flush the key |
[in] | key_properties | Pointer to the requested key properties of the destination key. Will be set in key->container.pAuxData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | key | Key to be used to MAC the data. |
[in] | mode | Mode that should be used during the MAC operation. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
session | Handle for the current CL session. | |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | pIn | Pointer to the input buffer that contains the data that need to be processed. |
[in] | inLength | Number of bytes of data in the in buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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.
[in] | pSession | handle for the current CL session. |
[in] | pExp | pointer to exponent |
[in] | pExpTemp | pointer to temporary buffer |
[in] | expByteLength | byte length of exponent |
[in] | iT3_iX_iT2_iT1 | indices of PKC operands |
[in] | iN_iTE_iT0_iR | indices of PKC operands |
[in] | secOption | option to disable the operand re-randomization |
session:
pExp
pExpTemp
expByteLength
. iT3_iX_iT2_iT1
iT1
(bits 0~7): index of temp1 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE). iT2
(bits 8~15): index of temp2 (PKC operand). iX
(bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE). iT3
(bits 24~31): index of temp3 (PKC operand). iN_iTE_iT0_iR
iR
(bits 0~7): index of result (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iT0
(bits 8~15): index of temp0 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iTE
(bits 16~23): index of temp4 (PKC operand). iN
(bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN). MCUXCLMATH_ERRORCODE_OK | function executed successfully |
MCUXCLMATH_ERRORCODE_ERROR | error occurred during operation |
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | bufferLength | byte length of each buffer in PKC workarea. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
bufferLength
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
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.
[in] | pSession | Handle for the current CL session. |
This function generates random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
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.
[in] | pSession | Handle for the current CL session. |
This function reports whether the the random data generator can provide the requested security strength.
[in] | pSession | Handle for the current CL session. |
[in] | securityStrength | Requested security strength in bits. |
This function performs the initialization of the non-cryptographic random number generator.
[in] | pSession | Handle for the current CL session. |
This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the verify operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pSignature | Pointer to buffer, which contains the signature |
[in] | pVerifyMode | Pointer to verification mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pOutput | Pointer to output buffer |
MCUXCLRSA_STATUS_VERIFY_OK | Verify operation executed successfully. |
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OK | Verification primitive operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_VERIFY_FAILED | The signature verification failed. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key. |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private CRT key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private plain key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
pSession | Session to be initialized. |
pRtf | buffer to store the rtf result. |
RtfOptions | Options to define RTF processing. |
This function will (securely) cleanup the session, which will still be usable afterwards.
pSession | Session to be cleaned. |
This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.
pSession | Session to be destroyed. |
Deprecated type for ELS driver protected status codes.
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:
session | Handle for the current CL session. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. | |
[in] | pIn | Pointer to the input buffer that contains the plain data that needs to be encrypted. |
inLength | Number of bytes of plain data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the encrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of encrypted data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
Deprecated type for ELS driver protected status codes.
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.
MCUXCLECC_STATUS_OK | if private key and public key are generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if signature is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if ECDSA Signature is valid; |
MCUXCLECC_STATUS_INVALID_SIGNATURE | if ECDSA Signature is invalid; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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).
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | pParam | pointer to ECC point multiplication parameter structure. |
MCUXCLECC_STATUS_OK | if point multiplication is calculated successfully, and the result is not the neutral point; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_NEUTRAL_POINT | if result is the neutral point; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | mcuxClSession_Descriptor structure |
[in] | type | type structure specifying requested key type to be generated. Also contains domain parameters |
[in] | protection | #mcuxClKey_Protection structure |
[out] | privKey | private key handling structure |
[out] | pPrivData | buffer for private key of the MCUXCLECC_MONT_CURVE25519/448_SIZE_PRIVATEKEY length |
[out] | pPrivDataLength | private key length |
[out] | pubKey | public key handling structure |
[out] | pPubData | buffer for public key x-coordinate of MCUXCLECC_MONT_CURVE25519/448_SIZE_PUBLICKEY length |
[out] | pPubDataLength | public key x-coordinate length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | key | private key handling structure |
[in] | otherKey | public key handling structure |
[out] | pOut | buffer for shared secret of length MCUXCLECC_MONT_CURVE25519/448_SIZE_SHAREDSECRET |
[out] | pOutLength | shared secret length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUP | if calculated public key lies in small subgroup. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
[in] | pSession | Handle 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] | pPrivKey | Pointer to private key input |
MCUXCLECC_STATUS_OK | EdDSA mode descriptor has been initialized successfully |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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
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.
[in] | pSession | Handle for the current CL session |
[in] | mode | Mode descriptor specifying the EdDSA GenerateKeyPair variant |
[in/out] | privKey Key handle for the private key. | |
[in/out] | pubKey Key handle for the public key. |
MCUXCLECC_STATUS_OK | private key data and public key have been generated successfully |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key 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] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[out] | pSignature | Pointer to buffer where the signature (Renc,S) will be stored |
[out] | pSignatureSize | Will be set to the number of bytes of data that have been written to the pSignature buffer |
MCUXCLECC_STATUS_OK | signature generation was successful |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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:
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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key handle for public key Qenc |
[in] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[in] | pSignature | Pointer to buffer containing the signature (Renc,S) |
[in] | signatureSize | Number of bytes of data in the pSignature buffer |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_INVALID_SIGNATURE | EdDSA signature is invalid |
MCUXCLECC_STATUS_INVALID_PARAMS | input parameters are invalid |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
[in] | pSession | pointer to mcuxClSession_Descriptor |
[in] | pDomainParams | Pointer to domain parameters of the used curve |
[in] | pProtocolDescriptor | Protocol descriptor specifying the EdDSA variant |
[in] | phflag | Option whether pre-hashing is enabled |
[in] | pContext | User input context for the hash prefix |
[in] | contextLen | Length of the context |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
Deprecated type for ELS driver protected status codes.
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.
pSession | Handle for the current CL session. | |
[out] | pEccWeierDomainParams | Pointer to memory area in which the optimized domain parameters shall be stored. |
[in] | pEccWeierBasicDomainParams | Pointer to struct containing pointers and lengths specifying the custom domain parameters. |
[in] | options | Parameter 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_STATUS_OK | if optimized domain parameters are generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
This function allows to generate custom key types according to the passed algoId
.
[out] | customType | Handle for the custom key type. |
[in] | algoId | Algorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
|
[in] | size | Algorithm based key size. |
[in] | pCustomParams | Pointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
|
MCUXCLECC_STATUS_OK | if custom key type is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if Parameters are invalid. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
Deprecated type for ELS driver protected status codes.
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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pAad | Memory area that contains the AAD |
[in] | aadLength | Length of the pAad in bytes with padding |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pInput | Pointer to the memory location of the data to be processed |
[in] | inputLength | Size of pInput in bytes with padding |
[out] | pOutput | Pointer to the processed data memory location |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | aadLength | Length of the complete Additional Authenticated Data (AAD) in bytes, without padding. |
[in] | dataLength | Length of the complete plaintext/ciphertext in bytes, without padding. |
[out] | pTag | Pointer where the resulting tag will be stored |
[in] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
Performs an AES encryption/decryption. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | Encryption/decryption command options. For detailed information, see mcuxClEls_CipherOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore. See parameter properties section in function description. |
[in] | pKey | Memory area that contains the key. See parameter properties section in function description. |
[in] | keyLength | Size of pKey in bytes. Must be a valid key size of MCUXCLELS_CIPHER_KEY_SIZE_AES_. See parameter properties section in function description. |
[in] | pInput | Pointer to the input data to be encrypted/decrypted. Padding must be already applied. |
[in] | inputLength | Size of pInput in bytes, must be a multiple of the block size. |
[in,out] | pIV | A pointer to the memory location which contains/receives the IV/state of cipher. See parameter properties section in function description. |
[out] | pOutput | Pointer to the output buffer to store encrypted/decrypted data. |
The properties of some parameters change with respect to selected options.
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>
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_CmacOption_t. |
[in] | keyIdx | The CMAC key index |
[in] | pKey | Pointer to the padded CMAC key |
[in] | keyLength | Size of pKey in bytes. Must be a valid CMAC key size. See the parameter properties section in the function description. |
[in] | pInput | Pointer to a memory location which contains the data, padded via SP 800-38b standard, to be authenticated |
[in] | inputLength | Size of pInput in bytes before padding |
[in,out] | pMac | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if an invalid parameter was specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
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.
[out] | result | Pointer which will be filled with the ELS hardware version |
[out] | result | Pointer which will be filled with the ELS status information |
Call #mcuxClEls_WaitForOperation to complete the operation.
This means that:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | A value indicating whether any running ELS operations shall be canceled |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the reset |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This is useful as a power saving mechanism.
[in] | options | The command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t. |
[out] | result | Pointer which is filled with the configuration of the interrupts enable register. |
[in] | options | The command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t. |
[in] | options | The command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t. |
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.
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
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.
[in] | counterLimit | The limit of the wait counter. |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
MCUXCLELS_STATUS_SW_COUNTER_EXPIRED | if the counter expired while waiting for the operation to complete |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
[in] | errorHandling | Define if error flags shall be cleared. |
[out] | errorLevel | Pointer to the location that will receive the value of the error level. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
#MCUXCLELS_STATUS_ | if the last operation resulted in an error |
This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async
[in] | delay | Define the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023). |
MCUXCLELS_STATUS_OK | if the operation was successful |
[out] | delay | Pointer to store random start delay configuration. |
MCUXCLELS_STATUS_OK | if the operation was successful |
Deprecated type for ELS driver protected status codes.
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).
[in] | options | The command options. For more information, see mcuxClEls_EccKeyGenOption_t. |
[in] | signingKeyIdx | The index of the key to sign the generated public key. |
[in] | privateKeyIdx | Output key index. |
[in] | generatedKeyProperties | The desired key properties of the generated key. |
[in] | pRandomData | Random data provided by the user. |
[out] | pPublicKey | Pointer to the memory area which receives the public key and optionally the key signature. |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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).
[in] | privateKeyIdx | The private key index. |
[in] | pPublicKey | Pointer to the public key of a third party. |
[in] | sharedSecretIdx | The index in the ELS keystore that receives the shared secret that is generated by the ECDH operation. |
[in] | sharedSecretProperties | The desired key properties of the shared secret. |
pPublicKey
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccSignOption_t. |
[in] | keyIdx | The private key index. |
[in] | pInputHash | The hash of the message to sign in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[out] | pOutput | Pointer to the memory area which receives the generated signature in X9.62 format. (64 bytes) |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccVerifyOption_t. |
[in] | pInputHash | The hash of the signed message in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[in] | pSignatureAndPubKey | Pointer to the memory area which contains the concatenation of the signature and the public key. |
[out] | pOutput | Pointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification. |
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
pOutput
pSignatureAndPublicKey
. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_HashOption_t. |
[in] | pInput | Padded input data to be hashed |
[in] | inputLength | Size 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] | pDigest | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_HmacOption_t. |
[in] | keyIdx | The HMAC key index, if an internal key shall be used |
[in] | pPaddedKey | Pointer to a memory location containing the padded HMAC key |
[in] | pInput | Pointer to a memory location which contains the data to be authenticated |
[in] | inputLength | Size of pInput in bytes |
[out] | pOutput | The output message authentication code |
The properties of some parameters change with respect to selected options.
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:
If LkHMAC ≤ MCUXCLELS_HMAC_PADDED_KEY_SIZE, pPaddedKey
must be the HMAC key padded with zero-bytes to fill the required length of MCUXCLELS_HMAC_PADDED_KEY_SIZE bytes.
pPaddedKey
must contain the SHA-256 hash of the HMAC key, padded with zero-bytes to fill the required length of MCUXCLELS_HMAC_PADDED_KEY_SIZE bytes.options.extkey
== MCUXCLELS_HMAC_EXTERNAL_KEY_DISABLE keyIdx
must be a valid key index with the correct usage rights for HMAC.
pPaddedKey
is ignored.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if an invalid parameter was specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
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.
[in] | options | The command options. For more information, see mcuxClEls_HkdfOption_t. |
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[in] | targetKeyIdx | Key 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] | targetKeyProperties | Requested properties for the derived key. The ksize field will be ignored. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_HKDF_RFC5869_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[out] | pTagetKey | Memory 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] | pDerivationData | The algorithm-specific derivation data |
[in] | derivationDataLength | Length of the derivation data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation |
[in] | targetKeyIdx | Key bank number of the derived key |
[in] | targetKeyProperties | Requested properties for the derived key. Only set usage bits. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The index of the TLS pre-master key, which is overwritten with the master key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The 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. |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for ELS driver protected status codes.
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.
[in] | keyIdx | The index of the key to be deleted |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | One of MCUXCLELS_KEYIMPORT_KFMT_ |
[in] | pImportKey | Pointer to the RFC3394 container of the key to be imported |
[in] | importKeyLength | Length of the RFC3394 container of the key to be imported |
[in] | wrappingKeyIdx | Index of the key wrapping key, if importing RFC3394 format |
[in] | targetKeyIdx | The desired key index of the imported key |
options.kfmt
!= MCUXCLELS_KEYIMPORT_KFMT_RFC3394pImportKey
is ignored. importKeyLength
is ignored. wrappingKeyIdx
is ignored. targetKeyIdx
is ignored. The unpacked key is automatically stored in key slots 0, 1. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | wrappingKeyIdx | The key used for key wrapping |
[in] | exportKeyIdx | The key to export |
[out] | pOutput | The memory address of the exported key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | keyIdx | Request key properties of the index defined here |
[out] | pKeyProp | Key properties of the index provided |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK | on successful request |
Deprecated type for ELS driver protected status codes.
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):
Call #mcuxClEls_WaitForOperation to complete the operation.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data |
[in] | outputLength | Number of requested random bytes |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pEntropy | Pointer to the input entropy data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[out] | pOutput | Pointer to the output random number |
[in] | outputLength | Length of the random number |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pDataKey | Pointer to the data and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pData | Pointer to the data to be encrypted |
[in] | dataLength | Length of the data to be encrypted |
[in] | pIvKey | Pointer to the IV and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
pInput
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
[out] | pOutput | The pointer to the evaluation result |
pInput
pOutput
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This function returns one low-quality random CPU word gathered from the PRNG.
[out] | pWord | The pointer to the random word |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function fills a buffer with low-quality random values gathered from the PRNG.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data from PRNG |
[in] | outputLength | Size of pOutput in bytes |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
Deprecated type for ELS driver protected status codes.
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:
The input parameter session
has to be initialized by the function mcuxClSession_init prior to calling this function. (MCUXCL_FEATURE_SESSION_HAS_RTF)
[in/out] | session Handle for the current CL session. | |
[in] | algorithm | Hash algorithm that should be used during the computation. |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be hashed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
[out] | pOut | Pointer 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. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occured during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A fault attack was detected |
This function performs the initialization for a multi-part hash operation.
[in/out] | session Handle for the current CL session. | |
[out] | pContext | Hash context which is used to maintain the state and store other relevant information about the operation. |
[in] | algorithm | Hash algorithm that should be used during the computation operation. |
MCUXCLHASH_STATUS_OK | Initialization successful |
MCUXCLHASH_FAILURE | Error 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.
[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] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A 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
[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] | pOut | Pointer to the output buffer where the computed hash value needs to be written. |
[out] | pOutSize | Will be incremented by the number of bytes of data that have been written to the pOut buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
Deprecated type for ELS driver protected status codes.
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.
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be initialized |
[in] | type | Define which key type shall be initialized |
[in] | pKeyData | Provide 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] | keyDataLength | Length of the provided key data pKeyData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | privKey | Key handle of private key |
[in,out] | pubKey | Key handle of public key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be configured |
[in] | protection | Define the protection and flush mechanism that shall be used with this key |
[in] | pAuxData | Provide pointer to additional data the protection function may use |
[in] | parentKey | Provide parent key information in case it exists. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstSlot | Provide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstData | Provide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to flush the key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in,out] | key | key handle that provides information to flush the key |
[in] | key_properties | Pointer to the requested key properties of the destination key. Will be set in key->container.pAuxData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
Deprecated type for ELS driver protected status codes.
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:
[in] | session | Handle for the current CL session. |
[in] | key | Key to be used to authenticate the data. |
[in] | mode | Mode that should be used during the MAC operation. |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be authenticated. |
[in] | inLength | Number of bytes of data in the pIn buffer. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | key | Key to be used to MAC the data. |
[in] | mode | Mode that should be used during the MAC operation. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
session | Handle for the current CL session. | |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | pIn | Pointer to the input buffer that contains the data that need to be processed. |
[in] | inLength | Number of bytes of data in the in buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault attack detected |
Deprecated type for ELS driver protected status codes.
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.
[in] | iX | index of PKC operand |
iX
#numTrailingZeroes | Number 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.
[in] | pSession | handle for the current CL session. |
[in] | pExp | pointer to exponent |
[in] | pExpTemp | pointer to temporary buffer |
[in] | expByteLength | byte length of exponent |
[in] | iT3_iX_iT2_iT1 | indices of PKC operands |
[in] | iN_iTE_iT0_iR | indices of PKC operands |
[in] | secOption | option to disable the operand re-randomization |
session:
pExp
pExpTemp
expByteLength
. iT3_iX_iT2_iT1
iT1
(bits 0~7): index of temp1 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE). iT2
(bits 8~15): index of temp2 (PKC operand). iX
(bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE). iT3
(bits 24~31): index of temp3 (PKC operand). iN_iTE_iT0_iR
iR
(bits 0~7): index of result (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iT0
(bits 8~15): index of temp0 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iTE
(bits 16~23): index of temp4 (PKC operand). iN
(bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN). MCUXCLMATH_ERRORCODE_OK | function executed successfully |
MCUXCLMATH_ERRORCODE_ERROR | error occurred during operation |
Deprecated type for ELS driver protected status codes.
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | bufferLength | byte length of each buffer in PKC workarea. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
bufferLength
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
Deprecated type for ELS driver protected status codes.
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.
[in] | pSession | Handle for the current CL session. |
[in] | pContext | Pointer to a Random data context buffer large enough to hold the context for the selected mode |
[in] | mode | Mode of operation for random data generator. |
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.
[in] | pSession | Handle for the current CL session. |
This function generates random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
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.
[in] | pSession | Handle for the current CL session. |
This function reports whether the the random data generator can provide the requested security strength.
[in] | pSession | Handle for the current CL session. |
[in] | securityStrength | Requested security strength in bits. |
This function performs the initialization of the non-cryptographic random number generator.
[in] | pSession | Handle for the current CL session. |
This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
Deprecated type for ELS driver protected status codes.
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.
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 |
Deprecated type for ELS driver protected status codes.
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the sign operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pPaddingMode | Pointer to signing mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pSignature | Pointer to buffer, which contains the result (signature) |
MCUXCLRSA_STATUS_SIGN_OK | Sign operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the verify operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pSignature | Pointer to buffer, which contains the signature |
[in] | pVerifyMode | Pointer to verification mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pOutput | Pointer to output buffer |
MCUXCLRSA_STATUS_VERIFY_OK | Verify operation executed successfully. |
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OK | Verification primitive operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_VERIFY_FAILED | The signature verification failed. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key. |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private CRT key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private plain key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
Deprecated type for ELS driver protected status 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.
pSession | Session to be initialized. |
pCpuWaBuffer | Pointer to buffer to be used as workarea for CPU operations. This pointer shall be CPU-word aligned. |
cpuWaLength | Size (in bytes) of the workarea for CPU operations. The size shall be a multiple of CPU wordsize. |
pPkcWaBuffer | Pointer to buffer to be used as workarea for PKC operations. This pointer shall be PKC-word aligned. |
pkcWaLength | Size (in bytes) of the workarea for PKC operations. The size shall be a multiple of CPU wordsize. |
MCUXCLSESSION_STATUS_OK | Session has been initialized successfully |
MCUXCLSESSION_STATUS_ERROR | Error occurred during session initializing. |
pSession | Session to be initialized. |
pRtf | buffer to store the rtf result. |
RtfOptions | Options to define RTF processing. |
This function will (securely) cleanup the session, which will still be usable afterwards.
pSession | Session to be cleaned. |
This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.
pSession | Session to be destroyed. |
Deprecated type for ELS driver protected status codes.
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.
[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pDst | The destination pointer to buffer to be cleared. Must not be NULL. |
[in] | dstLength | The size of the destination data buffer in bytes. |
[in] | length | The number of bytes to clear. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_OK | If the contents in buffer at pDst is cleared. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters is invalid. |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected, included invalid checksum chk . |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
The implementation is secure in the following aspects:
length
parameters, i.e. no branches are performed based on the data in pLhs
or pRhs
.chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
pLhs | The left-hand side data to compare. Must not be NULL. |
pRhs | The right-hand side data to compare. Must not be NULL. |
length | The number of bytes to compare. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_EQUAL | If the contents of lhs and rhs are equal. |
MCUXCSSLMEMORY_STATUS_NOT_EQUAL | If the contents of lhs and rhs are not equal. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters was invalid (i.e. lhs or rhs was NULL or length was zero). |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected. |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
The implementation is secure in the following aspects:
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.pDst
beyond dstLength
bytes.[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pSrc | The data to be copied. Must not be NULL. Must not overlap with pDst . |
[out] | pDst | The destination pointer. Must not be NULL. Must not overlap with pSrc . |
[in] | dstLength | The size of the destination data buffer in bytes. |
[in] | length | The number of bytes to copy. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_OK | If the contents of src and dst are equal. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters was invalid (i.e. pSrc or pDst was NULL or length was zero). |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected. |
Deprecated type for ELS driver protected status codes.
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.
[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pDst | The destination pointer to buffer to be set. Must not be NULL. |
[in] | val | The byte value to be set. |
[in] | length | The size in bytes to set. Must be different from zero. |
[in] | bufLength | The buffer size (if bufLength < length, only bufLength bytes are set). |
MCUXCSSLMEMORY_STATUS_OK | If val set length times at pDst . |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters is invalid. |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected, included invalid checksum chk . |
Deprecated type for ELS driver protected status codes.
Deprecated type for mcuxClEcc component return codes.
chk | The parameter checksum. |
nargs | The 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. |
MCUXCSSLPARAMINTEGRITY_CHECK_VALID | The parameter checksum was correct. |
MCUXCSSLPARAMINTEGRITY_CHECK_INVALID | The parameter checksum was incorrect. |
Deprecated type for ELS driver protected status 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.
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.
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:
session | Handle for the current CL session. | |
key | Key to be used to encrypt the data. | |
mode | AEAD mode that should be used during the encryption operation. | |
[in] | pNonce | Pointer to the buffer that contains the nonce. |
nonceLength | Number of bytes of nonce data in the nonce buffer. | |
[in] | pIn | Pointer to the input buffer that contains the plain data that need to be authenticated and encrypted. |
inLength | Number of bytes of plain data in the in buffer. | |
[in] | pAdata | Associated data for the authenticated encryption operation. Data format depends on the chosen mode . |
adataLength | Number of bytes of associated data in the adata buffer. | |
[out] | pOut | Pointer to the output buffer where the authenticated encrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of authenticated encrypted data that have been written to the out buffer. |
[out] | pTag | Pointer to the output buffer where the tag needs to be written. |
tagLength | Number of bytes of tag data that will be written to the tag buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | AEAD mode that should be used during the encryption/decryption operation. | |
[in] | pNonce | Pointer to the buffer that contains the nonce. |
nonceLength | Number of bytes of nonce data in the nonce buffer. | |
inLength | Number of bytes of plain data that will be processed. | |
adataLength | Number of bytes of associated data that will be processed. | |
tagLength | Number of bytes to be used for the authentication tag. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the in buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the out buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pAdata | Associated data that needs to be proccessed. |
adataLength | Number of bytes of associated data in the adata buffer. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the out buffer. |
[out] | pTag | Pointer to the output buffer where the tag needs to be written. |
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.
session | Handle for the current CL session. | |
pContext | AEAD context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pTag | Pointer to the buffer that contains the tag. |
[out] | pOut | Pointer to the output buffer where the authenticated decrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of authenticated decrypted data that have been written to the out buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
MCUXCLECC_STATUS_OK | if signature is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if ECDSA Signature is valid; |
MCUXCLECC_STATUS_INVALID_SIGNATURE | if ECDSA Signature is invalid; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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).
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | pParam | pointer to ECC point multiplication parameter structure. |
MCUXCLECC_STATUS_OK | if point multiplication is calculated successfully, and the result is not the neutral point; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_NEUTRAL_POINT | if result is the neutral point; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | mcuxClSession_Descriptor structure |
[in] | type | type structure specifying requested key type to be generated. Also contains domain parameters |
[in] | protection | #mcuxClKey_Protection structure |
[out] | privKey | private key handling structure |
[out] | pPrivData | buffer for private key of the MCUXCLECC_MONT_CURVE25519/448_SIZE_PRIVATEKEY length |
[out] | pPrivDataLength | private key length |
[out] | pubKey | public key handling structure |
[out] | pPubData | buffer for public key x-coordinate of MCUXCLECC_MONT_CURVE25519/448_SIZE_PUBLICKEY length |
[out] | pPubDataLength | public key x-coordinate length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | key | private key handling structure |
[in] | otherKey | public key handling structure |
[out] | pOut | buffer for shared secret of length MCUXCLECC_MONT_CURVE25519/448_SIZE_SHAREDSECRET |
[out] | pOutLength | shared secret length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUP | if calculated public key lies in small subgroup. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
[in] | pSession | Handle 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] | pPrivKey | Pointer to private key input |
MCUXCLECC_STATUS_OK | EdDSA mode descriptor has been initialized successfully |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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
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.
[in] | pSession | Handle for the current CL session |
[in] | mode | Mode descriptor specifying the EdDSA GenerateKeyPair variant |
[in/out] | privKey Key handle for the private key. | |
[in/out] | pubKey Key handle for the public key. |
MCUXCLECC_STATUS_OK | private key data and public key have been generated successfully |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key 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] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[out] | pSignature | Pointer to buffer where the signature (Renc,S) will be stored |
[out] | pSignatureSize | Will be set to the number of bytes of data that have been written to the pSignature buffer |
MCUXCLECC_STATUS_OK | signature generation was successful |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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:
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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key handle for public key Qenc |
[in] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[in] | pSignature | Pointer to buffer containing the signature (Renc,S) |
[in] | signatureSize | Number of bytes of data in the pSignature buffer |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_INVALID_SIGNATURE | EdDSA signature is invalid |
MCUXCLECC_STATUS_INVALID_PARAMS | input parameters are invalid |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
[in] | pSession | pointer to mcuxClSession_Descriptor |
[in] | pDomainParams | Pointer to domain parameters of the used curve |
[in] | pProtocolDescriptor | Protocol descriptor specifying the EdDSA variant |
[in] | phflag | Option whether pre-hashing is enabled |
[in] | pContext | User input context for the hash prefix |
[in] | contextLen | Length of the context |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
This function allows to generate custom key types according to the passed algoId
.
[out] | customType | Handle for the custom key type. |
[in] | algoId | Algorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
|
[in] | size | Algorithm based key size. |
[in] | pCustomParams | Pointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
|
MCUXCLECC_STATUS_OK | if custom key type is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if Parameters are invalid. |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pAad | Memory area that contains the AAD |
[in] | aadLength | Length of the pAad in bytes with padding |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pInput | Pointer to the memory location of the data to be processed |
[in] | inputLength | Size of pInput in bytes with padding |
[out] | pOutput | Pointer to the processed data memory location |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | aadLength | Length of the complete Additional Authenticated Data (AAD) in bytes, without padding. |
[in] | dataLength | Length of the complete plaintext/ciphertext in bytes, without padding. |
[out] | pTag | Pointer where the resulting tag will be stored |
[in] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
[out] | result | Pointer which will be filled with the ELS status information |
Call #mcuxClEls_WaitForOperation to complete the operation.
This means that:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | A value indicating whether any running ELS operations shall be canceled |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the reset |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This is useful as a power saving mechanism.
[in] | options | The command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t. |
[out] | result | Pointer which is filled with the configuration of the interrupts enable register. |
[in] | options | The command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t. |
[in] | options | The command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t. |
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.
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
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.
[in] | counterLimit | The limit of the wait counter. |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
MCUXCLELS_STATUS_SW_COUNTER_EXPIRED | if the counter expired while waiting for the operation to complete |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
[in] | errorHandling | Define if error flags shall be cleared. |
[out] | errorLevel | Pointer to the location that will receive the value of the error level. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
#MCUXCLELS_STATUS_ | if the last operation resulted in an error |
This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async
[in] | delay | Define the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023). |
MCUXCLELS_STATUS_OK | if the operation was successful |
[out] | delay | Pointer to store random start delay configuration. |
MCUXCLELS_STATUS_OK | if the operation was successful |
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).
[in] | privateKeyIdx | The private key index. |
[in] | pPublicKey | Pointer to the public key of a third party. |
[in] | sharedSecretIdx | The index in the ELS keystore that receives the shared secret that is generated by the ECDH operation. |
[in] | sharedSecretProperties | The desired key properties of the shared secret. |
pPublicKey
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccSignOption_t. |
[in] | keyIdx | The private key index. |
[in] | pInputHash | The hash of the message to sign in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[out] | pOutput | Pointer to the memory area which receives the generated signature in X9.62 format. (64 bytes) |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccVerifyOption_t. |
[in] | pInputHash | The hash of the signed message in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[in] | pSignatureAndPubKey | Pointer to the memory area which contains the concatenation of the signature and the public key. |
[out] | pOutput | Pointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification. |
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
pOutput
pSignatureAndPublicKey
. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[out] | pTagetKey | Memory 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] | pDerivationData | The algorithm-specific derivation data |
[in] | derivationDataLength | Length of the derivation data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation |
[in] | targetKeyIdx | Key bank number of the derived key |
[in] | targetKeyProperties | Requested properties for the derived key. Only set usage bits. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The index of the TLS pre-master key, which is overwritten with the master key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The 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. |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | One of MCUXCLELS_KEYIMPORT_KFMT_ |
[in] | pImportKey | Pointer to the RFC3394 container of the key to be imported |
[in] | importKeyLength | Length of the RFC3394 container of the key to be imported |
[in] | wrappingKeyIdx | Index of the key wrapping key, if importing RFC3394 format |
[in] | targetKeyIdx | The desired key index of the imported key |
options.kfmt
!= MCUXCLELS_KEYIMPORT_KFMT_RFC3394pImportKey
is ignored. importKeyLength
is ignored. wrappingKeyIdx
is ignored. targetKeyIdx
is ignored. The unpacked key is automatically stored in key slots 0, 1. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | wrappingKeyIdx | The key used for key wrapping |
[in] | exportKeyIdx | The key to export |
[out] | pOutput | The memory address of the exported key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | keyIdx | Request key properties of the index defined here |
[out] | pKeyProp | Key properties of the index provided |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK | on 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.
[in] | pEntropy | Pointer to the input entropy data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[out] | pOutput | Pointer to the output random number |
[in] | outputLength | Length of the random number |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pDataKey | Pointer to the data and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pData | Pointer to the data to be encrypted |
[in] | dataLength | Length of the data to be encrypted |
[in] | pIvKey | Pointer to the IV and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
pInput
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
[out] | pOutput | The pointer to the evaluation result |
pInput
pOutput
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This function returns one low-quality random CPU word gathered from the PRNG.
[out] | pWord | The pointer to the random word |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function fills a buffer with low-quality random values gathered from the PRNG.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data from PRNG |
[in] | outputLength | Size of pOutput in bytes |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function performs the initialization for a multi-part hash operation.
[in/out] | session Handle for the current CL session. | |
[out] | pContext | Hash context which is used to maintain the state and store other relevant information about the operation. |
[in] | algorithm | Hash algorithm that should be used during the computation operation. |
MCUXCLHASH_STATUS_OK | Initialization successful |
MCUXCLHASH_FAILURE | Error 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.
[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] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A 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
[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] | pOut | Pointer to the output buffer where the computed hash value needs to be written. |
[out] | pOutSize | Will be incremented by the number of bytes of data that have been written to the pOut buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | privKey | Key handle of private key |
[in,out] | pubKey | Key handle of public key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be configured |
[in] | protection | Define the protection and flush mechanism that shall be used with this key |
[in] | pAuxData | Provide pointer to additional data the protection function may use |
[in] | parentKey | Provide parent key information in case it exists. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstSlot | Provide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstData | Provide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to flush the key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in,out] | key | key handle that provides information to flush the key |
[in] | key_properties | Pointer to the requested key properties of the destination key. Will be set in key->container.pAuxData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | key | Key to be used to MAC the data. |
[in] | mode | Mode that should be used during the MAC operation. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
session | Handle for the current CL session. | |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | pIn | Pointer to the input buffer that contains the data that need to be processed. |
[in] | inLength | Number of bytes of data in the in buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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.
[in] | pSession | handle for the current CL session. |
[in] | pExp | pointer to exponent |
[in] | pExpTemp | pointer to temporary buffer |
[in] | expByteLength | byte length of exponent |
[in] | iT3_iX_iT2_iT1 | indices of PKC operands |
[in] | iN_iTE_iT0_iR | indices of PKC operands |
[in] | secOption | option to disable the operand re-randomization |
session:
pExp
pExpTemp
expByteLength
. iT3_iX_iT2_iT1
iT1
(bits 0~7): index of temp1 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE). iT2
(bits 8~15): index of temp2 (PKC operand). iX
(bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE). iT3
(bits 24~31): index of temp3 (PKC operand). iN_iTE_iT0_iR
iR
(bits 0~7): index of result (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iT0
(bits 8~15): index of temp0 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iTE
(bits 16~23): index of temp4 (PKC operand). iN
(bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN). MCUXCLMATH_ERRORCODE_OK | function executed successfully |
MCUXCLMATH_ERRORCODE_ERROR | error occurred during operation |
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | bufferLength | byte length of each buffer in PKC workarea. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
bufferLength
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
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.
[in] | pSession | Handle for the current CL session. |
This function generates random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
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.
[in] | pSession | Handle for the current CL session. |
This function reports whether the the random data generator can provide the requested security strength.
[in] | pSession | Handle for the current CL session. |
[in] | securityStrength | Requested security strength in bits. |
This function performs the initialization of the non-cryptographic random number generator.
[in] | pSession | Handle for the current CL session. |
This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the verify operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pSignature | Pointer to buffer, which contains the signature |
[in] | pVerifyMode | Pointer to verification mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pOutput | Pointer to output buffer |
MCUXCLRSA_STATUS_VERIFY_OK | Verify operation executed successfully. |
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OK | Verification primitive operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_VERIFY_FAILED | The signature verification failed. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key. |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private CRT key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private plain key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
pSession | Session to be initialized. |
pRtf | buffer to store the rtf result. |
RtfOptions | Options to define RTF processing. |
This function will (securely) cleanup the session, which will still be usable afterwards.
pSession | Session to be cleaned. |
This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.
pSession | Session to be destroyed. |
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:
session | Handle for the current CL session. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. | |
[in] | pIn | Pointer to the input buffer that contains the plain data that needs to be encrypted. |
inLength | Number of bytes of plain data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the encrypted data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of encrypted data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
key | Key to be used to encrypt the data. | |
mode | Cipher mode that should be used during the encryption/decryption operation. | |
[in] | pIv | Pointer to the buffer that contains the IV, if needed for the chosen mode , otherwise ignored. |
ivLength | Number of bytes of data in the pIv buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
inLength | Number of bytes of data in the pIn buffer. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
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.
session | Handle for the current CL session. | |
pContext | Cipher context which is used to maintain the state and store other relevant information about the operation. | |
[out] | pOut | Pointer to the output buffer where the processed data needs to be written. |
[out] | pOutLength | Will be incremented by the number of bytes of processed data that have been written to the pOut buffer. |
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.
MCUXCLECC_STATUS_OK | if private key and public key are generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if signature is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_RNG_ERROR | if random number (DRBG / PRNG) error (unexpected behavior); |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
MCUXCLECC_STATUS_OK | if ECDSA Signature is valid; |
MCUXCLECC_STATUS_INVALID_SIGNATURE | if ECDSA Signature is invalid; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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).
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | pParam | pointer to ECC point multiplication parameter structure. |
MCUXCLECC_STATUS_OK | if point multiplication is calculated successfully, and the result is not the neutral point; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_NEUTRAL_POINT | if result is the neutral point; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | mcuxClSession_Descriptor structure |
[in] | type | type structure specifying requested key type to be generated. Also contains domain parameters |
[in] | protection | #mcuxClKey_Protection structure |
[out] | privKey | private key handling structure |
[out] | pPrivData | buffer for private key of the MCUXCLECC_MONT_CURVE25519/448_SIZE_PRIVATEKEY length |
[out] | pPrivDataLength | private key length |
[out] | pubKey | public key handling structure |
[out] | pPubData | buffer for public key x-coordinate of MCUXCLECC_MONT_CURVE25519/448_SIZE_PUBLICKEY length |
[out] | pPubDataLength | public key x-coordinate length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
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.
[in] | pSession | pointer to mcuxClSession_Descriptor. |
[in] | key | private key handling structure |
[in] | otherKey | public key handling structure |
[out] | pOut | buffer for shared secret of length MCUXCLECC_MONT_CURVE25519/448_SIZE_SHAREDSECRET |
[out] | pOutLength | shared secret length |
MCUXCLECC_STATUS_OK | if key generation correctly calculate private and public keys, public key does not belong to the small subgroup. |
MCUXCLECC_STATUS_RNG_ERROR | if RNG return an error. |
MCUXCLECC_STATUS_ERROR_SMALL_SUBGROUP | if calculated public key lies in small subgroup. |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
[in] | pSession | Handle 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] | pPrivKey | Pointer to private key input |
MCUXCLECC_STATUS_OK | EdDSA mode descriptor has been initialized successfully |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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
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.
[in] | pSession | Handle for the current CL session |
[in] | mode | Mode descriptor specifying the EdDSA GenerateKeyPair variant |
[in/out] | privKey Key handle for the private key. | |
[in/out] | pubKey Key handle for the public key. |
MCUXCLECC_STATUS_OK | private key data and public key have been generated successfully |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key 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] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[out] | pSignature | Pointer to buffer where the signature (Renc,S) will be stored |
[out] | pSignatureSize | Will be set to the number of bytes of data that have been written to the pSignature buffer |
MCUXCLECC_STATUS_OK | signature generation was successful |
MCUXCLECC_STATUS_RNG_ERROR | random number generation (DRBG / PRNG) error (unexpected behavior) |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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:
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.
[in] | pSession | Handle for the current CL session |
[in] | key | Key handle for public key Qenc |
[in] | mode | Mode descriptor specifying the EdDSA variant |
[in] | pIn | Pointer to message digest m' |
[in] | inSize | Size of message digest m' |
[in] | pSignature | Pointer to buffer containing the signature (Renc,S) |
[in] | signatureSize | Number of bytes of data in the pSignature buffer |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_INVALID_SIGNATURE | EdDSA signature is invalid |
MCUXCLECC_STATUS_INVALID_PARAMS | input parameters are invalid |
MCUXCLECC_STATUS_FAULT_ATTACK | fault attack (unexpected behavior) is detected |
[in] | pSession | pointer to mcuxClSession_Descriptor |
[in] | pDomainParams | Pointer to domain parameters of the used curve |
[in] | pProtocolDescriptor | Protocol descriptor specifying the EdDSA variant |
[in] | phflag | Option whether pre-hashing is enabled |
[in] | pContext | User input context for the hash prefix |
[in] | contextLen | Length of the context |
MCUXCLECC_STATUS_OK | signature verification passed |
MCUXCLECC_STATUS_FAULT_ATTACK | fault 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.
pSession | Handle for the current CL session. | |
[out] | pEccWeierDomainParams | Pointer to memory area in which the optimized domain parameters shall be stored. |
[in] | pEccWeierBasicDomainParams | Pointer to struct containing pointers and lengths specifying the custom domain parameters. |
[in] | options | Parameter 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_STATUS_OK | if optimized domain parameters are generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if parameters are invalid; |
MCUXCLECC_STATUS_FAULT_ATTACK | if fault attack (unexpected behavior) is detected. |
This function allows to generate custom key types according to the passed algoId
.
[out] | customType | Handle for the custom key type. |
[in] | algoId | Algorithm identifier specifying the key type descriptor to be generated. The supported algoIds are
|
[in] | size | Algorithm based key size. |
[in] | pCustomParams | Pointer to algorithm based custom parameters. If algoId & MCUXCLKEY_ALGO_ID_ALGO_MASK equals
|
MCUXCLECC_STATUS_OK | if custom key type is generated successfully; |
MCUXCLECC_STATUS_INVALID_PARAMS | if Parameters are invalid. |
MCUXCLECC_STATUS_FAULT_ATTACK | if 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pIV | Pointer to memory area that contains the IV |
[in] | ivLength | Size of pIV in bytes, with padding |
[out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pAad | Memory area that contains the AAD |
[in] | aadLength | Length of the pAad in bytes with padding |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | pInput | Pointer to the memory location of the data to be processed |
[in] | inputLength | Size of pInput in bytes with padding |
[out] | pOutput | Pointer to the processed data memory location |
[in,out] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The AEAD command options. For more information, see mcuxClEls_AeadOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore |
[in] | pKey | Pointer to the key |
[in] | keyLength | Size of pKey in bytes |
[in] | aadLength | Length of the complete Additional Authenticated Data (AAD) in bytes, without padding. |
[in] | dataLength | Length of the complete plaintext/ciphertext in bytes, without padding. |
[out] | pTag | Pointer where the resulting tag will be stored |
[in] | pAeadCtx | Pointer 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.
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
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for mcuxClEcc component return codes.
Performs an AES encryption/decryption. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | Encryption/decryption command options. For detailed information, see mcuxClEls_CipherOption_t. |
[in] | keyIdx | Index of the key inside the ELS keystore. See parameter properties section in function description. |
[in] | pKey | Memory area that contains the key. See parameter properties section in function description. |
[in] | keyLength | Size of pKey in bytes. Must be a valid key size of MCUXCLELS_CIPHER_KEY_SIZE_AES_. See parameter properties section in function description. |
[in] | pInput | Pointer to the input data to be encrypted/decrypted. Padding must be already applied. |
[in] | inputLength | Size of pInput in bytes, must be a multiple of the block size. |
[in,out] | pIV | A pointer to the memory location which contains/receives the IV/state of cipher. See parameter properties section in function description. |
[out] | pOutput | Pointer to the output buffer to store encrypted/decrypted data. |
The properties of some parameters change with respect to selected options.
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>
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_CmacOption_t. |
[in] | keyIdx | The CMAC key index |
[in] | pKey | Pointer to the padded CMAC key |
[in] | keyLength | Size of pKey in bytes. Must be a valid CMAC key size. See the parameter properties section in the function description. |
[in] | pInput | Pointer to a memory location which contains the data, padded via SP 800-38b standard, to be authenticated |
[in] | inputLength | Size of pInput in bytes before padding |
[in,out] | pMac | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if an invalid parameter was specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[out] | result | Pointer which will be filled with the ELS hardware version |
[out] | result | Pointer which will be filled with the ELS status information |
Call #mcuxClEls_WaitForOperation to complete the operation.
This means that:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | A value indicating whether any running ELS operations shall be canceled |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the reset |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This is useful as a power saving mechanism.
[in] | options | The command options, determining which interrupts should be enabled or disabled. For more information, see mcuxClEls_InterruptOptionEn_t. |
[out] | result | Pointer which is filled with the configuration of the interrupts enable register. |
[in] | options | The command options, determining which interrupt status bits should be cleared. For more information, see mcuxClEls_InterruptOptionRst_t. |
[in] | options | The command options, determining which interrupt status bits should be set. For more information, see mcuxClEls_InterruptOptionSet_t. |
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.
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
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.
[in] | counterLimit | The limit of the wait counter. |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful, or no operation was active |
MCUXCLELS_STATUS_SW_COUNTER_EXPIRED | if the counter expired while waiting for the operation to complete |
[in] | errorHandling | Define if error flags shall be cleared. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
[in] | errorHandling | Define if error flags shall be cleared. |
[out] | errorLevel | Pointer to the location that will receive the value of the error level. |
MCUXCLELS_STATUS_OK | if the last operation was successful or no operation was active |
#MCUXCLELS_STATUS_ | if the last operation resulted in an error |
This impacts mcuxClEls_Aead_*, mcuxClEls_Cipher_*, mcuxClEls_Cmac_*, ncpClEls_Ckdf_*, mcuxClEls_KeyImport_Async, mcuxClEls_KeyExport_Async
[in] | delay | Define the max random start delay. Acceptable values are a power of 2 minus one, starting from 0 to 1023 (0, 1, 3, 7, ..., 1023). |
MCUXCLELS_STATUS_OK | if the operation was successful |
[out] | delay | Pointer to store random start delay configuration. |
MCUXCLELS_STATUS_OK | if the operation was successful |
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).
[in] | options | The command options. For more information, see mcuxClEls_EccKeyGenOption_t. |
[in] | signingKeyIdx | The index of the key to sign the generated public key. |
[in] | privateKeyIdx | Output key index. |
[in] | generatedKeyProperties | The desired key properties of the generated key. |
[in] | pRandomData | Random data provided by the user. |
[out] | pPublicKey | Pointer to the memory area which receives the public key and optionally the key signature. |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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).
[in] | privateKeyIdx | The private key index. |
[in] | pPublicKey | Pointer to the public key of a third party. |
[in] | sharedSecretIdx | The index in the ELS keystore that receives the shared secret that is generated by the ECDH operation. |
[in] | sharedSecretProperties | The desired key properties of the shared secret. |
pPublicKey
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccSignOption_t. |
[in] | keyIdx | The private key index. |
[in] | pInputHash | The hash of the message to sign in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[out] | pOutput | Pointer to the memory area which receives the generated signature in X9.62 format. (64 bytes) |
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. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_EccVerifyOption_t. |
[in] | pInputHash | The hash of the signed message in X9.62 format. |
[in] | pInputMessage | The message to sign. |
[in] | inputMessageLength | Size of pInputMessage in bytes. |
[in] | pSignatureAndPubKey | Pointer to the memory area which contains the concatenation of the signature and the public key. |
[out] | pOutput | Pointer to the memory area which will receive the recalculated value of the R component in case of a successful signature verification. |
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
pOutput
pSignatureAndPublicKey
. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_HashOption_t. |
[in] | pInput | Padded input data to be hashed |
[in] | inputLength | Size 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] | pDigest | Pointer 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.
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.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Deprecated type for mcuxClEcc component return codes.
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | The command options. For more information, see mcuxClEls_HmacOption_t. |
[in] | keyIdx | The HMAC key index, if an internal key shall be used |
[in] | pPaddedKey | Pointer to a memory location containing the padded HMAC key |
[in] | pInput | Pointer to a memory location which contains the data to be authenticated |
[in] | inputLength | Size of pInput in bytes |
[out] | pOutput | The output message authentication code |
The properties of some parameters change with respect to selected options.
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:
If LkHMAC ≤ MCUXCLELS_HMAC_PADDED_KEY_SIZE, pPaddedKey
must be the HMAC key padded with zero-bytes to fill the required length of MCUXCLELS_HMAC_PADDED_KEY_SIZE bytes.
pPaddedKey
must contain the SHA-256 hash of the HMAC key, padded with zero-bytes to fill the required length of MCUXCLELS_HMAC_PADDED_KEY_SIZE bytes.options.extkey
== MCUXCLELS_HMAC_EXTERNAL_KEY_DISABLE keyIdx
must be a valid key index with the correct usage rights for HMAC.
pPaddedKey
is ignored.
MCUXCLELS_STATUS_SW_INVALID_PARAM | if an invalid parameter was specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | options | The command options. For more information, see mcuxClEls_HkdfOption_t. |
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[in] | targetKeyIdx | Key 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] | targetKeyProperties | Requested properties for the derived key. The ksize field will be ignored. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_HKDF_RFC5869_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation. Must be a 256-bit key with HKDF property bit set to 1. |
[out] | pTagetKey | Memory 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] | pDerivationData | The algorithm-specific derivation data |
[in] | derivationDataLength | Length of the derivation data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | derivationKeyIdx | Key index used for derivation |
[in] | targetKeyIdx | Key bank number of the derived key |
[in] | targetKeyProperties | Requested properties for the derived key. Only set usage bits. |
[in] | pDerivationData | The algorithm-specific derivation data, the length is MCUXCLELS_CKDF_DERIVATIONDATA_SIZE bytes |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The pre-master key is overwritten in this operation. Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The index of the TLS pre-master key, which is overwritten with the master key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
The master key and the following five key indices are overwritten in this operation. The keys are written in the following order:
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | pDerivationData | The 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] | keyProperties | Desired key properties. Only mcuxClEls_KeyProp_t::upprot_priv and mcuxClEls_KeyProp_t::upprot_sec are used, the rest are ignored. |
[in] | keyIdx | The 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. |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | keyIdx | The index of the key to be deleted |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | options | One of MCUXCLELS_KEYIMPORT_KFMT_ |
[in] | pImportKey | Pointer to the RFC3394 container of the key to be imported |
[in] | importKeyLength | Length of the RFC3394 container of the key to be imported |
[in] | wrappingKeyIdx | Index of the key wrapping key, if importing RFC3394 format |
[in] | targetKeyIdx | The desired key index of the imported key |
options.kfmt
!= MCUXCLELS_KEYIMPORT_KFMT_RFC3394pImportKey
is ignored. importKeyLength
is ignored. wrappingKeyIdx
is ignored. targetKeyIdx
is ignored. The unpacked key is automatically stored in key slots 0, 1. MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | wrappingKeyIdx | The key used for key wrapping |
[in] | exportKeyIdx | The key to export |
[out] | pOutput | The memory address of the exported key |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
Call #mcuxClEls_WaitForOperation to complete the operation.
[in] | keyIdx | Request key properties of the index defined here |
[out] | pKeyProp | Key properties of the index provided |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK | on 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):
Call #mcuxClEls_WaitForOperation to complete the operation.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data |
[in] | outputLength | Number of requested random bytes |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pEntropy | Pointer to the input entropy data |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[out] | pOutput | Pointer to the output random number |
[in] | outputLength | Length of the random number |
outputLength
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pDataKey | Pointer to the data and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pData | Pointer to the data to be encrypted |
[in] | dataLength | Length of the data to be encrypted |
[in] | pIvKey | Pointer to the IV and key |
[out] | pOutput | Pointer to the encrypted output |
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
pInput
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on 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.
[in] | pInput | The pointer to DTRNG initialization data |
[out] | pOutput | The pointer to the evaluation result |
pInput
pOutput
MCUXCLELS_STATUS_SW_INVALID_PARAM | if invalid parameters were specified |
MCUXCLELS_STATUS_SW_CANNOT_INTERRUPT | if a running operation prevented the request |
MCUXCLELS_STATUS_OK_WAIT | on successful request |
This function returns one low-quality random CPU word gathered from the PRNG.
[out] | pWord | The pointer to the random word |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in case of insufficient entropy |
This function fills a buffer with low-quality random values gathered from the PRNG.
[out] | pOutput | Pointer to the beginning of the memory area to fill with random data from PRNG |
[in] | outputLength | Size of pOutput in bytes |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_HW_PRNG | in 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:
The input parameter session
has to be initialized by the function mcuxClSession_init prior to calling this function. (MCUXCL_FEATURE_SESSION_HAS_RTF)
[in/out] | session Handle for the current CL session. | |
[in] | algorithm | Hash algorithm that should be used during the computation. |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be hashed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
[out] | pOut | Pointer 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. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occured during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A fault attack was detected |
This function performs the initialization for a multi-part hash operation.
[in/out] | session Handle for the current CL session. | |
[out] | pContext | Hash context which is used to maintain the state and store other relevant information about the operation. |
[in] | algorithm | Hash algorithm that should be used during the computation operation. |
MCUXCLHASH_STATUS_OK | Initialization successful |
MCUXCLHASH_FAILURE | Error 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.
[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] | pIn | Pointer to the input buffer that contains the data that needs to be processed. |
[in] | inSize | Number of bytes of data in the pIn buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error occurred during Hash operation |
MCUXCLHASH_STATUS_INVALID_PARAMS | The provided function parameters do not fulfill requirements |
MCUXCLHASH_STATUS_FAULT_ATTACK | A 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
[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] | pOut | Pointer to the output buffer where the computed hash value needs to be written. |
[out] | pOutSize | Will be incremented by the number of bytes of data that have been written to the pOut buffer. |
MCUXCLHASH_STATUS_OK | Hash operation successful |
MCUXCLHASH_FAILURE | Error 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.
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be initialized |
[in] | type | Define which key type shall be initialized |
[in] | pKeyData | Provide 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] | keyDataLength | Length of the provided key data pKeyData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | privKey | Key handle of private key |
[in,out] | pubKey | Key handle of public key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in,out] | key | Key handle that will be configured |
[in] | protection | Define the protection and flush mechanism that shall be used with this key |
[in] | pAuxData | Provide pointer to additional data the protection function may use |
[in] | parentKey | Provide parent key information in case it exists. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstSlot | Provide destination key slot in case the key has to loaded to a key slot. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to load the key |
[out] | dstData | Provide pointer to destination key memory in case the key has to be loaded to memory. The protection function defines the purpose of this parameter |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in] | pSession | Session handle to provide session dependent information |
[in] | key | Key handle that provides information to flush the key |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on successful operation |
[in,out] | key | key handle that provides information to flush the key |
[in] | key_properties | Pointer to the requested key properties of the destination key. Will be set in key->container.pAuxData |
MCUXCLKEY_STATUS_ERROR | on unsuccessful operation |
MCUXCLKEY_STATUS_OK | on 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:
[in] | session | Handle for the current CL session. |
[in] | key | Key to be used to authenticate the data. |
[in] | mode | Mode that should be used during the MAC operation. |
[in] | pIn | Pointer to the input buffer that contains the data that needs to be authenticated. |
[in] | inLength | Number of bytes of data in the pIn buffer. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | key | Key to be used to MAC the data. |
[in] | mode | Mode that should be used during the MAC operation. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
session | Handle for the current CL session. | |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[in] | pIn | Pointer to the input buffer that contains the data that need to be processed. |
[in] | inLength | Number of bytes of data in the in buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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:
The size of the context depends on the mode used (see mcuxClMac_MemoryConsumption).
[in] | session | Handle for the current CL session. |
[in] | pContext | MAC context which is used to maintain the state and store other relevant information about the operation. |
[out] | pMac | Pointer to the output buffer where the MAC needs to be written. |
[out] | pMacLength | Will be incremented by the number of bytes of data that have been written to the pMac buffer. |
MCUXCLMAC_STATUS_OK | Mac operation successful |
MCUXCLMAC_STATUS_ERROR | Error occurred during Mac operation |
MCUXCLMAC_STATUS_INVALID_PARAM | An invalid parameter was given to the function |
MCUXCLMAC_STATUS_FAULT_ATTACK | Fault 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.
[in] | iX | index of PKC operand |
iX
#numTrailingZeroes | Number 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.
[in] | pSession | handle for the current CL session. |
[in] | pExp | pointer to exponent |
[in] | pExpTemp | pointer to temporary buffer |
[in] | expByteLength | byte length of exponent |
[in] | iT3_iX_iT2_iT1 | indices of PKC operands |
[in] | iN_iTE_iT0_iR | indices of PKC operands |
[in] | secOption | option to disable the operand re-randomization |
session:
pExp
pExpTemp
expByteLength
. iT3_iX_iT2_iT1
iT1
(bits 0~7): index of temp1 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE, 2 * MCUXCLPKC_WORDSIZE). iT2
(bits 8~15): index of temp2 (PKC operand). iX
(bits 16~23): index of base number (PKC operand), size = operandSize + MCUXCLPKC_WORDSIZE (= lenN + MCUXCLPKC_WORDSIZE). iT3
(bits 24~31): index of temp3 (PKC operand). iN_iTE_iT0_iR
iR
(bits 0~7): index of result (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iT0
(bits 8~15): index of temp0 (PKC operand). expByteLength
+ 1), lenN + MCUXCLPKC_WORDSIZE). iTE
(bits 16~23): index of temp4 (PKC operand). iN
(bits 24~31): index of modulus (PKC operand), size = operandSize (= lenN). MCUXCLMATH_ERRORCODE_OK | function executed successfully |
MCUXCLMATH_ERRORCODE_ERROR | error occurred during operation |
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
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.
[in] | pSession | handle for the current CL session. |
[in,out] | pUPTRT | pointer to the first element to be randomized in UPTR table. |
[in] | bufferLength | byte length of each buffer in PKC workarea. |
[in] | noOfBuffer | number of elements to be randomized. |
pUPTRT
bufferLength
MCUXCLPKC_STATUS_OK | if UPTR table is randomized successfully. |
MCUXCLPKC_STATUS_NOK | if the operation failed. |
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.
[in] | pSession | Handle for the current CL session. |
[in] | pContext | Pointer to a Random data context buffer large enough to hold the context for the selected mode |
[in] | mode | Mode of operation for random data generator. |
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.
[in] | pSession | Handle for the current CL session. |
This function generates random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
This function performs the cleanup of a random data generator. This operation cleans up the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
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.
[in] | pSession | Handle for the current CL session. |
This function reports whether the the random data generator can provide the requested security strength.
[in] | pSession | Handle for the current CL session. |
[in] | securityStrength | Requested security strength in bits. |
This function performs the initialization of the non-cryptographic random number generator.
[in] | pSession | Handle for the current CL session. |
This function generates non-cryptographic random data based on the information contained in the Random context referenced in the session handle.
[in] | pSession | Handle for the current CL session. |
[out] | pOut | Buffer in which the generated random data must be written. |
[in] | outLength | Number of random data bytes that must be written in the pOut buffer. |
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.
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 |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the sign operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pPaddingMode | Pointer to signing mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pSignature | Pointer to buffer, which contains the result (signature) |
MCUXCLRSA_STATUS_SIGN_OK | Sign operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | pKey | Pointer to key structure of type mcuxClRsa_Key |
[in] | pMessageOrDigest | Pointer to buffer, which contains the input to the verify operation |
[in] | messageLength | Byte-length of MessageOrDigest |
[in] | pSignature | Pointer to buffer, which contains the signature |
[in] | pVerifyMode | Pointer to verification mode of type mcuxClRsa_SignVerifyMode_t |
[in] | saltLength | Byte-length of salt |
[in] | options | Options field |
[out] | pOutput | Pointer to output buffer |
MCUXCLRSA_STATUS_VERIFY_OK | Verify operation executed successfully. |
MCUXCLRSA_STATUS_VERIFYPRIMITIVE_OK | Verification primitive operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_VERIFY_FAILED | The signature verification failed. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key. |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private CRT key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
[in] | pSession | Pointer to mcuxClSession_Descriptor |
[in] | type | Type of the key |
[in] | protection | Protection and flush mechanism that must be applied to the generated key |
[out] | privKey | Key handle for the generated private key |
[out] | pPrivData | Pointer to the buffer where the generated private plain key data needs to be written |
[out] | pPrivDataLength | Will be set by the number of bytes of data that have been written to the pPrivData buffer |
[out] | pubKey | Key handle for the generated public key |
[out] | pPubData | Pointer to the buffer where the generated public key data needs to be written |
[out] | pPubDataLength | Will be set by the number of bytes of data that have been written to the pPubData buffer |
pPrivData
buffer. pPubData
buffer. MCUXCLRSA_STATUS_KEYGENERATION_OK | RSA key generation operation executed successfully. |
MCUXCLRSA_STATUS_INVALID_INPUT | The input parameters are not valid. |
MCUXCLRSA_STATUS_KEYGENERATION_ITERATIONSEXCEEDED | RSA key generation exceeds the limit of iterations to generate a prime. |
MCUXCLRSA_STATUS_ERROR | An error occurred during the execution. In that case, expectations for the flow protection are not balanced. |
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.
pSession | Session to be initialized. |
pCpuWaBuffer | Pointer to buffer to be used as workarea for CPU operations. This pointer shall be CPU-word aligned. |
cpuWaLength | Size (in bytes) of the workarea for CPU operations. The size shall be a multiple of CPU wordsize. |
pPkcWaBuffer | Pointer to buffer to be used as workarea for PKC operations. This pointer shall be PKC-word aligned. |
pkcWaLength | Size (in bytes) of the workarea for PKC operations. The size shall be a multiple of CPU wordsize. |
MCUXCLSESSION_STATUS_OK | Session has been initialized successfully |
MCUXCLSESSION_STATUS_ERROR | Error occurred during session initializing. |
pSession | Session to be initialized. |
pRtf | buffer to store the rtf result. |
RtfOptions | Options to define RTF processing. |
This function will (securely) cleanup the session, which will still be usable afterwards.
pSession | Session to be cleaned. |
This function will (securely) cleanup the session, including uninitialization etc. The session will no longer be usable afterwards.
pSession | Session to be destroyed. |
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.
[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pDst | The destination pointer to buffer to be cleared. Must not be NULL. |
[in] | dstLength | The size of the destination data buffer in bytes. |
[in] | length | The number of bytes to clear. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_OK | If the contents in buffer at pDst is cleared. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters is invalid. |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected, included invalid checksum chk . |
Deprecated type for mcuxClEcc component return codes.
The implementation is secure in the following aspects:
length
parameters, i.e. no branches are performed based on the data in pLhs
or pRhs
.chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
pLhs | The left-hand side data to compare. Must not be NULL. |
pRhs | The right-hand side data to compare. Must not be NULL. |
length | The number of bytes to compare. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_EQUAL | If the contents of lhs and rhs are equal. |
MCUXCSSLMEMORY_STATUS_NOT_EQUAL | If the contents of lhs and rhs are not equal. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters was invalid (i.e. lhs or rhs was NULL or length was zero). |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected. |
Deprecated type for mcuxClEcc component return codes.
The implementation is secure in the following aspects:
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.pDst
beyond dstLength
bytes.[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pSrc | The data to be copied. Must not be NULL. Must not overlap with pDst . |
[out] | pDst | The destination pointer. Must not be NULL. Must not overlap with pSrc . |
[in] | dstLength | The size of the destination data buffer in bytes. |
[in] | length | The number of bytes to copy. Must be different from zero. |
MCUXCSSLMEMORY_STATUS_OK | If the contents of src and dst are equal. |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters was invalid (i.e. pSrc or pDst was NULL or length was zero). |
MCUXCSSLMEMORY_STATUS_FAULT | If 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.
[in] | chk | The parameter checksum, generated with mcuxCsslParamIntegrity_Protect. |
[in] | pDst | The destination pointer to buffer to be set. Must not be NULL. |
[in] | val | The byte value to be set. |
[in] | length | The size in bytes to set. Must be different from zero. |
[in] | bufLength | The buffer size (if bufLength < length, only bufLength bytes are set). |
MCUXCSSLMEMORY_STATUS_OK | If val set length times at pDst . |
MCUXCSSLMEMORY_STATUS_INVALID_PARAMETER | If one of the parameters is invalid. |
MCUXCSSLMEMORY_STATUS_FAULT | If a fault was detected, included invalid checksum chk . |
Deprecated type for mcuxClEcc component return codes.
chk | The parameter checksum. |
nargs | The 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. |
MCUXCSSLPARAMINTEGRITY_CHECK_VALID | The parameter checksum was correct. |
MCUXCSSLPARAMINTEGRITY_CHECK_INVALID | The parameter checksum was incorrect. |