Overview

The MCUXpresso SDK provides the Peripheral driver for the LP Trusted Cryptography (LTC) module of MCUXpresso SDK devices. LP Trusted Cryptography is a set of cryptograhpic hardware accelerator engines that share common registers. LTC architecture can support AES, DES, 3DES, MDHA (SHA), RSA and ECC. Actual list of implemented cryptograhpic hardware accelerator engines depends on specific microcontroller.

The driver comprises two sets of API functions.

In the first set, blocking synchronous APIs are provided, for all operations supported by LTC hardware. The LTC operations are complete (and results are made availabe for further usage) when a function returns. When called, these functions don't return until an LTC operation is complete. These functions use main CPU for simple polling loops to determine operation complete or error status and also for plaintext or ciphertext data movements. The driver functions are not re-entrant. These functions provide typical interface to upper layer or application software.

In the second set, DMA support for symmetric LTC processing is provided, for AES and DES engines. APIs in the second set use DMA for data movement to and from the LTC input and output FIFOs. By using these functions, main CPU is not used for plaintext or ciphertext data movements (DMA is used instead). Thus, CPU processing power can be used for other application tasks, at cost of decreased maximum data throughput (because of DMA module and transactions management overhead). These functions provide less typical interface, for applications that must offload main CPU while ciphertext or plaintext is being processed, at cost of longer cryptograhpic processing time.

LTC Driver Initialization and Configuration

LTC Driver is initialized by calling the LTC_Init() function, it enables the LTC module clock in the SIM module. If AES or DES engine is used and the LTC module implementation features the LTC DPA Mask Seed register, seed the DPA mask generator by using the seed from a random number generator. The LTC_SetDpaMaskSeed() function is provided to set the DPA mask seed.

Comments about API usage in RTOS

LTC operations provided by this driver are not re-entrant. Thus, application software shall ensure the LTC module operation is not requested from different tasks or interrupt service routines while an operation is in progress.

Comments about API usage in interrupt handler

All APIs can be used from interrupt handler although execution time shall be considered (interrupt latency of equal and lower priority interrupts increases).

LTC Driver Examples

Simple examples

Initialize LTC after Power On Reset or reset cycle

LTC_Init(LTC0);
/* optionally initialize DPA mask seed register */
LTC_SetDpaMaskSeed(randomNumber);

Encrypt plaintext by DES engine

char plain[16];
char cipher[16];
char iv[LTC_DES_IV_SIZE];
char key1[LTC_DES_KEY_SIZE];
char key2[LTC_DES_KEY_SIZE];
char key3[LTC_DES_KEY_SIZE];
memcpy(plain, "Hello World!", 12);
memcpy(iv, "initvect", LTC_DES_IV_SIZE);
memcpy(key1, "mykey1aa", LTC_DES_KEY_SIZE);
memcpy(key2, "mykey2bb", LTC_DES_KEY_SIZE);
memcpy(key3, "mykey3cc", LTC_DES_KEY_SIZE);
LTC_DES3_EncryptCbc(LTC0, plain, cipher, 16, iv, key1, key2, key3);

Encrypt plaintext by AES engine

char plain[16] = {0};
char cipher[16];
char iv[16] = {0};
char key[16] = {0};
memcpy(plain, "Hello World!", 12);
memcpy(iv, "initvectorinitve", 16);
memcpy(key, "__mykey1aa__^^..", 16);
LTC_AES_EncryptCbc(LTC0, plain, cipher, 16, iv, key, 16);

Compute keyed hash by AES engine (CMAC)

   char message[] = "Hello World!";
   char key[16] = {0};
   char output[16];
   uint32_t szOutput = 16u;
   memcpy(key, "__mykey1aa__^^..", 16);
LTC_HASH(LTC0, kLTC_Sha256, message, sizeof(message), NULL, 0, output, &szOutput);

Compute hash by MDHA engine (SHA-256)

char message[] = "Hello World!";
char output[32];
uint32_t szOutput = 32u;
LTC_HASH(LTC0, kLTC_Sha256, message, sizeof(message), NULL, output, &szOutput);

Compute modular integer exponentiation

status_t status;
const char bigA[] = "112233445566778899aabbccddeeff";
const char bigN[] = "aabbaabbaabb112233445566778899aabbccddeefe";
const char bigE[] = "065537";
char A[256], E[256], N[256], res[256];
uint16_t sizeA, sizeE, sizeN, sizeRes;
/* Note LTC PKHA integer format is least significant byte at lowest address.
 * The _read_string() function converts the input string to LTC PKHA integer format
 * and writes sizeof() the integer to the size variable (sizeA, sizeE, sizeN).
 */
_read_string(A, &sizeA, bigA);
_read_string(E, &sizeE, bigN);
_read_string(N, &sizeN, bigE);
status = LTC_PKHA_ModExp(base, A, sizeA, N, sizeN, E, sizeE, res, &sizeRes, kLTC_PKHA_IntegerArith,
                         kLTC_PKHA_NormalValue, kLTC_PKHA_TimingEqualized);

Compute elliptic curve point multiplication

status_t status;
ltc_pkha_ecc_point_t B0, res0;
uint8_t bx, by, resx, resy;
uint8_t E[256];
bool isPointOfInfinity;
uint16_t resultSize, sizeE;
/* Example carried out with 1-byte curve params and point coordinates. */
uint8_t size = 1;
uint8_t aCurveParam = 1;
uint8_t bCurveParam = 0;
bx = 9;
by = 5;
B0.X = &bx;
B0.Y = &by;
res0.X = &resx;
res0.Y = &resy;
/* Prime modulus of the field. */
N[0] = 23;
/* Note LTC PKHA integer has least significant byte at lowest address */
/* Scalar multiplier */
char ew[] = "0100"; /* 256 in decimal */
_read_string(E, &sizeE, ew);
status = LTC_PKHA_ECC_PointMul(LTC0, &B0, E, sizeE, N, NULL, &aCurveParam, &bCurveParam, size,
                               kLTC_PKHA_TimingEqualized, kLTC_PKHA_IntegerArith, &res0, &isPointOfInfinity);

Modules
	LTC Blocking APIs

	LTC Non-blocking eDMA APIs

Functions
void	LTC_Init (LTC_Type *base)
	Initializes the LTC driver. More...

void	LTC_Deinit (LTC_Type *base)
	Deinitializes the LTC driver. More...

Driver version
#define	FSL_LTC_DRIVER_VERSION (MAKE_VERSION(2, 0, 4))
	LTC driver version. More...

Macro Definition Documentation

#define FSL_LTC_DRIVER_VERSION (MAKE_VERSION(2, 0, 4))

Version 2.0.4.

Current version: 2.0.4

Change log:

Version 2.0.1
- fixed warning during g++ compilation
Version 2.0.2
- fixed [KPSDK-10932][LTC][SHA] LTC_HASH() blocks indefinitely when message size exceeds 4080 bytes
Version 2.0.3
- fixed LTC_PKHA_CompareBigNum() in case an integer argument is an array of all zeroes
Version 2.0.4
- constant LTC_PKHA_CompareBigNum() processing time

Function Documentation

void LTC_Init ( LTC_Type * base )

This function initializes the LTC driver.

Parameters

base	LTC peripheral base address

void LTC_Deinit ( LTC_Type * base )

This function deinitializes the LTC driver.