Overview

The MCUXpresso SDK provides a peripheral driver for the AES module in MCUXpresso SDK devices.

The driver provides blocking synchronous APIs. The AES operations are complete (and results are made availabe for further usage) when a function returns. When called, these functions don't return until an AES 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.

AES Driver Initialization and Configuration

Clock to the AES module has to be enabled before using the driver API. The function AES_SetKey() has to be used to store encryption key into device registers prior to using other API.

Comments about API usage in RTOS

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

AES Driver Examples

Encrypt plaintext and decrypt it back by AES engine

status_t status;
uint8_t plain[16] = {0u};
uint8_t cipher[16];
uint8_t iv[AES_IV_SIZE] = {0u};
uint8_t key[16] = {0u};
memcpy(plain, "Hello World!", 12);
memcpy(iv, "initvectorinitve", 16);
memcpy(key, "__mykey1aa__^^..", 16);
status = AES_SetKey(AES0, key, 16);
if (status != kStatus_Success)
{
    /* fail */
    return;
}
status = AES_EncryptCbc(AES0, plain, cipher, 16, iv);
if (status != kStatus_Success)
{
    /* fail */
    return;
}
status = AES_DecryptCbc(AES0, cipher, plain, 16, iv);
if (status != kStatus_Success)
{
    /* fail */
    return;
}

Encrypts AES using CTR block mode.

status_t status;    
const uint8_t key[] = {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6,
                       0xab, 0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
const uint8_t counter[16] = {0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
                             0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff};
uint8_t plain[] = {0x6b, 0xc1, 0xbe, 0xe2, 0x2e, 0x40, 0x9f, 0x96,
                   0xe9, 0x3d, 0x7e, 0x11, 0x73, 0x93, 0x17, 0x2a};
uint8_t cipher[16];
uint8_t iv[16];
memset(cipher, 0, sizeof(cipher));
memcpy(iv, counter, 16);
status = AES_SetKey(AES0, key, sizeof(key));
if (status != kStatus_Success)
{
    /* fail */
    return;
}
status = AES_CryptCtr(AES0, plain, cipher, sizeof(plain), iv, NULL, NULL);
if (status != kStatus_Success)
{
    /* fail */
    return;
}
memcpy(iv, counter, 16);
status = AES_CryptCtr(AES0, cipher, plain, sizeof(cipher), iv, NULL, NULL);
if (status != kStatus_Success)
{
    /* fail */
    return;
}

Generation of GCM tag only

uint8_t key[16] = {0x0};
uint8_t iv[12] = {0x0};
uint8_t tag[16];
status_t status;
status = AES_SetKey(AES, key, sizeof(key));
if (status != kStatus_Success)
{
    /* fail */
    return;
}
status = AES_EncryptTagGcm(AES, NULL, NULL, 0U, iv, sizeof(iv), NULL, 0U, tag, sizeof(tag));
if (status != kStatus_Success)
{
    /* fail */
    return;
}

Files
file	fsl_aes.h

Driver version
#define	FSL_AES_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
	Defines LPC AES driver version 2.0.0. More...

AES Functional Operation
status_t	AES_SetKey (AES_Type base, const uint8_t key, size_t keySize)
	Sets AES key. More...

status_t	AES_EncryptEcb (AES_Type base, const uint8_t plaintext, uint8_t *ciphertext, size_t size)
	Encrypts AES using the ECB block mode. More...

status_t	AES_DecryptEcb (AES_Type base, const uint8_t ciphertext, uint8_t *plaintext, size_t size)
	Decrypts AES using the ECB block mode. More...

status_t	AES_EncryptCbc (AES_Type base, const uint8_t plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Encrypts AES using CBC block mode. More...

status_t	AES_DecryptCbc (AES_Type base, const uint8_t ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Decrypts AES using CBC block mode. More...

status_t	AES_EncryptCfb (AES_Type base, const uint8_t plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Encrypts AES using CFB block mode. More...

status_t	AES_DecryptCfb (AES_Type base, const uint8_t ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Decrypts AES using CFB block mode. More...

status_t	AES_EncryptOfb (AES_Type base, const uint8_t plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Encrypts AES using OFB block mode. More...

status_t	AES_DecryptOfb (AES_Type base, const uint8_t ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE])
	Decrypts AES using OFB block mode. More...

status_t	AES_CryptCtr (AES_Type base, const uint8_t input, uint8_t output, size_t size, uint8_t counter[AES_BLOCK_SIZE], uint8_t counterlast[AES_BLOCK_SIZE], size_t szLeft)
	Encrypts or decrypts AES using CTR block mode. More...

status_t	AES_EncryptTagGcm (AES_Type base, const uint8_t plaintext, uint8_t ciphertext, size_t size, const uint8_t iv, size_t ivSize, const uint8_t aad, size_t aadSize, uint8_t tag, size_t tagSize)
	Encrypts AES and tags using GCM block mode. More...

status_t	AES_DecryptTagGcm (AES_Type base, const uint8_t ciphertext, uint8_t plaintext, size_t size, const uint8_t iv, size_t ivSize, const uint8_t aad, size_t aadSize, const uint8_t tag, size_t tagSize)
	Decrypts AES and authenticates using GCM block mode. More...

void	AES_Init (AES_Type *base)
	AES block initialization. More...

void	AES_Deinit (AES_Type *base)
	AES block deinitialization. More...

#define	AES_BLOCK_SIZE 16
	AES block size in bytes.

#define	AES_IV_SIZE 16
	AES Input Vector size in bytes.

Macro Definition Documentation

#define FSL_AES_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))

Change log:

Version 2.0.0
- initial version

Function Documentation

status_t AES_SetKey	(	AES_Type *	base,
		const uint8_t *	key,
		size_t	keySize
	)

Sets AES key.

Parameters

base	AES peripheral base address
key	Input key to use for encryption or decryption
keySize	Size of the input key, in bytes. Must be 16, 24, or 32.

Returns: Status from Set Key operation

status_t AES_EncryptEcb	(	AES_Type *	base,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size
	)

Encrypts AES using the ECB block mode.

Parameters

	base	AES peripheral base address
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.

Returns: Status from encrypt operation

status_t AES_DecryptEcb	(	AES_Type *	base,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size
	)

Decrypts AES using the ECB block mode.

Parameters

	base	AES peripheral base address
	ciphertext	Input ciphertext to decrypt
[out]	plaintext	Output plain text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.

Returns: Status from decrypt operation

status_t AES_EncryptCbc	(	AES_Type *	base,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.
	iv	Input initial vector to combine with the first input block.

Returns: Status from encrypt operation

status_t AES_DecryptCbc	(	AES_Type *	base,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	ciphertext	Input cipher text to decrypt
[out]	plaintext	Output plain text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.
	iv	Input initial vector to combine with the first input block.

Returns: Status from decrypt operation

status_t AES_EncryptCfb	(	AES_Type *	base,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.
	iv	Input Initial vector to be used as the first input block.

Returns: Status from encrypt operation

status_t AES_DecryptCfb	(	AES_Type *	base,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	ciphertext	Input cipher text to decrypt
[out]	plaintext	Output plain text
	size	Size of input and output data in bytes. Must be multiple of 16 bytes.
	iv	Input Initial vector to be used as the first input block.

Returns: Status from decrypt operation

status_t AES_EncryptOfb	(	AES_Type *	base,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text
	size	Size of input and output data in bytes.
	iv	Input Initial vector to be used as the first input block.

Returns: Status from encrypt operation

status_t AES_DecryptOfb	(	AES_Type *	base,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t	iv[AES_IV_SIZE]
	)

Parameters

	base	AES peripheral base address
	ciphertext	Input cipher text to decrypt
[out]	plaintext	Output plain text
	size	Size of input and output data in bytes.
	iv	Input Initial vector to be used as the first input block.

Returns: Status from decrypt operation

status_t AES_CryptCtr	(	AES_Type *	base,
		const uint8_t *	input,
		uint8_t *	output,
		size_t	size,
		uint8_t	counter[AES_BLOCK_SIZE],
		uint8_t	counterlast[AES_BLOCK_SIZE],
		size_t *	szLeft
	)

Encrypts or decrypts AES using CTR block mode. AES CTR mode uses only forward AES cipher and same algorithm for encryption and decryption. The only difference between encryption and decryption is that, for encryption, the input argument is plain text and the output argument is cipher text. For decryption, the input argument is cipher text and the output argument is plain text.

Parameters

	base	AES peripheral base address
	input	Input data for CTR block mode
[out]	output	Output data for CTR block mode
	size	Size of input and output data in bytes
[in,out]	counter	Input counter (updates on return)
[out]	counterlast	Output cipher of last counter, for chained CTR calls. NULL can be passed if chained calls are not used.
[out]	szLeft	Output number of bytes in left unused in counterlast block. NULL can be passed if chained calls are not used.

Returns: Status from crypt operation

status_t AES_EncryptTagGcm	(	AES_Type *	base,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t *	iv,
		size_t	ivSize,
		const uint8_t *	aad,
		size_t	aadSize,
		uint8_t *	tag,
		size_t	tagSize
	)

Encrypts AES and optionally tags using GCM block mode. If plaintext is NULL, only the GHASH is calculated and output in the 'tag' field.

Parameters

	base	AES peripheral base address
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text.
	size	Size of input and output data in bytes
	iv	Input initial vector
	ivSize	Size of the IV
	aad	Input additional authentication data
	aadSize	Input size in bytes of AAD
[out]	tag	Output hash tag. Set to NULL to skip tag processing.
	tagSize	Input size of the tag to generate, in bytes. Must be 4,8,12,13,14,15 or 16.

Returns: Status from encrypt operation

status_t AES_DecryptTagGcm	(	AES_Type *	base,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t *	iv,
		size_t	ivSize,
		const uint8_t *	aad,
		size_t	aadSize,
		const uint8_t *	tag,
		size_t	tagSize
	)

Decrypts AES and optionally authenticates using GCM block mode. If ciphertext is NULL, only the GHASH is calculated and compared with the received GHASH in 'tag' field.

Parameters

	base	AES peripheral base address
	ciphertext	Input cipher text to decrypt
[out]	plaintext	Output plain text.
	size	Size of input and output data in bytes
	iv	Input initial vector
	ivSize	Size of the IV
	aad	Input additional authentication data
	aadSize	Input size in bytes of AAD
	tag	Input hash tag to compare. Set to NULL to skip tag processing.
	tagSize	Input size of the tag, in bytes. Must be 4, 8, 12, 13, 14, 15, or 16.

Returns: Status from decrypt operation

void AES_Init ( AES_Type * base )

Ungate AES block clock

Parameters

base	AES peripheral base address

void AES_Deinit ( AES_Type * base )

Gate AES block clock

Parameters

base	AES peripheral base address

Overview

AES Driver Initialization and Configuration

Comments about API usage in RTOS

AES Driver Examples

Files

Driver version

AES Functional Operation

Macro Definition Documentation

Function Documentation