MCUX CLNS MCUX Crypto Library Normal Secure |

Security Guidance Manual

The CLNS implements security features which are meant to protect against fault injection attacks. Nonetheless, a few security-related topics require your explicit attention.

## Checking the correctness of return values

In general, the return values of all CLNS API functions must be checked. These checks should ideally be written in such a way that, on an assembly code level, the code for the error condition is executed by default. This means that skipping all branch instructions must lead to an error condition, which helps avoid fault injection vulnerabilities. The compiler may generate branch instructions to reach the code for the success condition. We encourage that you check this manually.

## Code-flow protection

Almost all CLNS API functions monitor the code path taken internally and calculate a protection value that must be verified by the caller of the library. This can be done with e.g. the following code snippet:

#include <nxpCsslFlowProtection.h>
#include <nxpClCss.h>
int main(void)
{
nxpClCss_Status_Protected_t status;
status = nxpClCss_Enable_Async();
if(NXP_CSSL_FP_FUNCTION_CALLED(nxpClCss_Enable_Async) != NXP_CSSL_FP_PROTECTION_TOKEN(status))
{
/* An attack was detected. Wipe all affected assets and abort. */
return -1;
}
if(NXPCLCSS_STATUS_OK_WAIT != NXP_CSSL_FP_RESULT(status))
{
/* Handle the error. */
}
/* Don't forget to do the same for nxpClCss_WaitForOperation()! */
return 0;
}

## Parameter integrity protection

Some CLNS API functions use parameter integrity protection, which provides additional assurance against fault injection attacks. The first parameter of such functions has the type `nxpCsslParamIntegrity_Checksum_t`. In order to call these functions correctly, you must first calculate the parameter checksum. See the example below:

#include <stdint.h>
#include <nxpCsslMemory.h>
#include <nxpCsslFlowProtection.h>
#include <nxpCsslParamIntegrity.h>
int main(void) {
uint8_t arr1[33U] = {0xe4u, 0xf9u, 0x26u, 0x4cu, 0x65u, 0xe2u, 0x13u, 0xa3u, 0x9au, 0x40u, 0xd7u, 0x87u, 0xccu, 0x0bu, 0x31u, 0x18u, 0xacu, 0x55u, 0xb5u, 0x7du, 0x06u, 0x7fu, 0xceu, 0xe4u, 0xb2u, 0x7eu, 0xd5u, 0xaau, 0x90u, 0x9au, 0x42u, 0x56u, 0x76u};
/* Compare arr1 with itself. Compute the parameter checksum and pass it to the function. */
nxpCsslParamIntegrity_Checksum_t checksum = nxpCsslParamIntegrity_Protect(3u, arr1, arr1, 33U);
uint64_t result = nxpCsslMemory_Compare(checksum, arr1, arr1, 33U);
/* Ensure the protection token is correct */
if(NXP_CSSL_FP_FUNCTION_CALLED(nxpCsslMemory_Compare) != NXP_CSSL_FP_PROTECTION_TOKEN(result))
{
/* An attack was detected. Wipe all affected assets and abort. */
return -1;
}
/* Ensure the parameter integrity value was correct */
if(NXPCSSLMEMORY_COMPARE_FAULT == NXP_CSSL_FP_RESULT(result))
{
/* An attack was detected. Wipe all affected assets and abort. */
return -1;
}
/* Check the return value */
if(NXPCSSLMEMORY_COMPARE_EQUAL != NXP_CSSL_FP_RESULT(result))
{
/* Handle the error. */
}
return 0;
}

## Alignment of sensitive data

All sensitive data (such as private keys), including sensitive CLNS API function parameters, should be aligned on a 4-byte boundary to harden the software against side-channel analysis.