Interfaces to perform AEAD operations in one shot. More...
Modules | |
Multi-part AEAD interfaces | |
Interfaces to perform AEAD operations in multiple parts. | |
Functions | |
MCUX_CSSL_FP_PROTECTED_TYPE (mcuxClAead_Status_t) mcuxClAead_crypt(mcuxClSession_Handle_t session | |
One-shot authenticated encryption/decryption function. More... | |
Interfaces to perform AEAD operations in one shot.
MCUX_CSSL_FP_PROTECTED_TYPE | ( | mcuxClAead_Status_t | ) |
One-shot authenticated encryption/decryption function.
Deprecated type for mcuxClSession protected status codes.
Deprecated type for RSA protected status codes.
Deprecated type for error codes used by code-flow protected PKC component functions.
Deprecated type for error codes used by code-flow protected mcuxClMemory component functions.
Deprecated type for error codes used by code-flow protected Math component functions.
Deprecated type for Key component error codes, returned by functions with code-flow protection.
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.
This function updates the entropy input pointer in a TEST_MODE descriptor.
Non-cryptographic PRNG data generation function.
Non-cryptographic PRNG initialization function.
Random data generator security strength check.
Random data generator self-test function.
Random data generator uninitialization function.
Random data generation function.
Random data generator reseed function.
Randomize UPTR table and operands in PKC workarea.
Securely calculates modular exponentiation.
Finalize a MAC generation for a multipart MAC computation.
Data processing for a multipart MAC computation.
Initialization for a multipart MAC computation.
Set the requested key properties of the destination key.
Flush key from destination which can be a key slot of coprocessor or memory buffer.
Load key into destination memory buffer.
Load key into destination key slot of a coprocessor.
Configures they protection mechanism for to the given key handle.
Establishes a key pair link between a private and public key handle.
Multi-part Hash computation finalization function.
Multi-part Hash processing function.
Multi-part Hash initialization function.
Writes random data from the ELS PRNG to the given buffer.
Returns one random word from the ELS PRNG.
Performs characterization of the ELS DTRNG.
Loads a configuration of the ELS DTRNG.
Encrypts data using the AES-CTR engine of the DRBG.
Encrypts data using the AES-ECB engine of the DRBG.
Performs a DRBG extraction.
Instantiates the DRBG in test mode.
Exports the properties of the keys stored in the ELS internal keystore.
Exports a key from an internal key register to external storage, using a wrapping key.
Imports a key from external storage to an internal key register.
Generates TLS session keys based on a master key and derivation data, according to the TLS 1.2 specification.
Generates a TLS master key based on a pre-master key and derivation data, according to the TLS 1.2 specification.
Derives a key using the NIST SP 800-108 CMAC-based Extract-and-Expand Key Derivation Function.
Derives a key using the HKDF (HMAC-based key derivation function) according to SP800-56C one-step approach with Sha2-256.
Resets the glitch detector's event counter.
Reads the glitch detector's event counter.
Calculates optimal ELS glitch detector configuration and writes it to system memory.
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.
[out] | Pointer | to the memory area which receives the glitch detector trim value. The size is fixed at MCUXCLELS_GLITCHDETECTOR_TRIM_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 |
This function converts the event counter from Gray code to an unsigned number.
[in] | Pointer | to the word where the counter value will be stored. |
MCUXCLELS_STATUS_OK | on successful request |
MCUXCLELS_STATUS_OK | 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. |
testMode[in] | Pointer to TEST_MODE descriptor |
pEntropyInput[in] | Pointer to memory buffer containing entropy input for DRBG (re)seeding |
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. |