Overview

This section describes the programming interface of the LTC AES driver.

Macros
#define	LTC_AES_BLOCK_SIZE 16
	AES block size in bytes.

#define	LTC_AES_IV_SIZE 16
	AES IV size in bytes.

#define	FSL_LTC_FIFO_SZ_MAX_DOWN_ALGN (0xff0u)
	LTC module FIFO size in bytes aligned down to the AES block boundary.

#define	FSL_LTC_CCM_TAG_IDX 8
	For CCM encryption, the encrypted final MAC is written to the context word 8-11.

#define	FSL_LTC_GCM_TAG_IDX 0
	For GCM encryption, the encrypted final MAC is written to the context word 0-3.

#define	LTC_DRV_aes_decrypt_ctr(instance, input, inputSize, counter, key, keySize, output, counterlast, szLeft) LTC_DRV_aes_ctr(instance, input, inputSize, counter, key, keySize, output, counterlast, szLeft)
	AES CTR decrypt is mapped to the AES CTR generic operation.

#define	LTC_DRV_aes_encrypt_ctr(instance, input, inputSize, counter, key, keySize, output, counterlast, szLeft) LTC_DRV_aes_ctr(instance, input, inputSize, counter, key, keySize, output, counterlast, szLeft)
	AES CTR encrypt is mapped to the AES CTR generic operation.

Enumerations
enum	ltc_drv_aes_key_t { kLtcEncryptKey = 0U, kLtcDecryptKey = 1U }
	Type of AES key for ECB and CBC decrypt operations. More...

Functions
void	LTC_DRV_SetDPAMaskSeed (uint32_t instance, uint32_t mask)
	Sets the DPA Mask Seed register. More...

ltc_status_t	LTC_DRV_aes_generate_decrypt_key (uint32_t instance, const uint8_t encryptKey, uint8_t decryptKey, uint32_t keySize)
	Transforms an AES encrypt key (forward AES) into the decrypt key (inverse AES). More...

ltc_status_t	LTC_DRV_aes_encrypt_ecb (uint32_t instance, const uint8_t plaintext[16], const uint8_t *key, uint32_t keySize, uint8_t ciphertext[16])
	Encrypts AES using the ECB block mode. More...

ltc_status_t	LTC_DRV_aes_decrypt_ecb (uint32_t instance, const uint8_t ciphertext[16], const uint8_t *key, uint32_t keySize, ltc_drv_aes_key_t keyType, uint8_t plaintext[16])
	Decrypts AES using ECB block mode. More...

ltc_status_t	LTC_DRV_aes_encrypt_cbc (uint32_t instance, const uint8_t plaintext, uint32_t inputSize, uint8_t iv[LTC_AES_IV_SIZE], const uint8_t key, uint32_t keySize, uint8_t *ciphertext)
	Encrypts AES using CBC block mode. More...

ltc_status_t	LTC_DRV_aes_decrypt_cbc (uint32_t instance, const uint8_t ciphertext, uint32_t inputSize, uint8_t iv[LTC_AES_IV_SIZE], const uint8_t key, uint32_t keySize, ltc_drv_aes_key_t keyType, uint8_t *plaintext)
	Decrypts AES using CBC block mode. More...

ltc_status_t	LTC_DRV_aes_ctr (uint32_t instance, const uint8_t input, uint32_t inputSize, uint8_t counter[16], const uint8_t key, uint32_t keySize, uint8_t output, uint8_t counterlast[16], uint32_t szLeft)
	Encrypts or decrypts AES using CTR block mode. More...

ltc_status_t	LTC_DRV_aes_encrypt_tag_gcm (uint32_t instance, const uint8_t plaintext, uint32_t inputSize, const uint8_t iv, uint32_t ivSize, const uint8_t aad, uint32_t aadSize, const uint8_t key, uint32_t keySize, uint8_t ciphertext, uint8_t tag, uint32_t tagSize)
	Encrypts AES using GCM block mode. More...

ltc_status_t	LTC_DRV_aes_decrypt_tag_gcm (uint32_t instance, const uint8_t ciphertext, uint32_t inputSize, const uint8_t iv, uint32_t ivSize, const uint8_t aad, uint32_t aadSize, const uint8_t key, uint32_t keySize, uint8_t plaintext, const uint8_t tag, uint32_t tagSize)
	Decrypts AES using GCM block mode. More...

ltc_status_t	LTC_DRV_aes_encrypt_tag_ccm (uint32_t instance, const uint8_t plaintext, uint32_t inputSize, const uint8_t iv, uint32_t ivSize, const uint8_t aad, uint32_t aadSize, const uint8_t key, uint32_t keySize, uint8_t ciphertext, uint8_t tag, uint32_t tagSize)
	Encrypts AES using CCM block mode. More...

ltc_status_t	LTC_DRV_aes_decrypt_tag_ccm (uint32_t instance, const uint8_t ciphertext, uint32_t inputSize, const uint8_t iv, uint32_t ivSize, const uint8_t aad, uint32_t aadSize, const uint8_t key, uint32_t keySize, uint8_t plaintext, const uint8_t tag, uint32_t tagSize)
	Decrypts AES using CCM block mode. More...

Enumeration Type Documentation

enum ltc_drv_aes_key_t

Enumerator
kLtcEncryptKey	Input key is an encrypt key (the same key which has been used for encrypt operation)
kLtcDecryptKey	Input key is a decrypt key (the key has been obtained from LTC_DRV_aes_generate_decrypt_key()).

Function Documentation

void LTC_DRV_SetDPAMaskSeed	(	uint32_t	instance,
		uint32_t	mask
	)

The DPA Mask Seed register reseeds the mask that provides resistance against DPA attacks on AES keys.

Differential Power Analysis Mask (DPA) resistance uses a randomly changing mask that introduces "noise" into the power consumed by the AESA. This reduces the signal-to-noise ratio that differential power analysis attacks use to "guess" bits of the AES key. This randomly changing mask should be seeded at POR, and continues to provide DPA resistance from that point on. However, to provide even more DPA protection it is recommended that the DPA mask be reseeded after every 50,000 AESA blocks have been processed. At that time, software can opt to write a new seed (preferably obtained from an RNG) into the DPA Mask Seed register (DPAMS), or software can opt to provide the new seed earlier or later, or not at all. DPA resistance continues even if the DPA mask is never reseeded.

Parameters

instance	LTC module instance number.
mask	The DPA mask seed.

ltc_status_t LTC_DRV_aes_generate_decrypt_key	(	uint32_t	instance,
		const uint8_t *	encryptKey,
		uint8_t *	decryptKey,
		uint32_t	keySize
	)

Transforms the AES encrypt key (forward AES) into the decrypt key (inverse AES). The key derived by this function can be used as a direct load decrypt key for AES ECB and CBC decryption operations (keyType argument).

Parameters

	instance	LTC module instance number.
	encryptKey	Input key for decrypt key transformation
[out]	decryptKey	Output key, the decrypt form of the AES key.
	keySize	Size of the input key and output key in bytes. Must be 16, 24, or 32.

Returns: Status from key generation operation

ltc_status_t LTC_DRV_aes_encrypt_ecb	(	uint32_t	instance,
		const uint8_t	plaintext[16],
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t	ciphertext[16]
	)

Encrypts AES using the ECB block mode.

Parameters

	instance	LTC module instance number.
	plaintext	Input single block (128-bits) of plain text to encrypt
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	ciphertext	Ouput single block (128-bits) of cipher text

Returns: Status from encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_decrypt_ecb	(	uint32_t	instance,
		const uint8_t	ciphertext[16],
		const uint8_t *	key,
		uint32_t	keySize,
		ltc_drv_aes_key_t	keyType,
		uint8_t	plaintext[16]
	)

Decrypts AES using ECB block mode.

Parameters

	instance	LTC module instance number.
	ciphertext	Input single block (128-bits) of cipher text to decrypt
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
	keyType	Input type of the key (allows to directly load decrypt key for AES ECB decrypt operation.)
[out]	plaintext	Output single block (128-bits) of plain text

Returns: Status from encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_encrypt_cbc	(	uint32_t	instance,
		const uint8_t *	plaintext,
		uint32_t	inputSize,
		uint8_t	iv[LTC_AES_IV_SIZE],
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	ciphertext
	)

LTC_DRV_aes_encrypt_cbc

Parameters

	instance	LTC module instance number.
	plaintext	Input plain text to encrypt
	inputSize	Size of input data in bytes. Must be multiple of 16 bytes.
	iv	Input initial vector to combine with the first input block.
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	ciphertext	Output cipher text

Returns: Status from encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_decrypt_cbc	(	uint32_t	instance,
		const uint8_t *	ciphertext,
		uint32_t	inputSize,
		uint8_t	iv[LTC_AES_IV_SIZE],
		const uint8_t *	key,
		uint32_t	keySize,
		ltc_drv_aes_key_t	keyType,
		uint8_t *	plaintext
	)

LTC_DRV_aes_decrypt_cbc

Parameters

	instance	LTC module instance number.
	ciphertext	Input cipher text to decrypt
	inputSize	Size of input data in bytes. Must be multiple of 16 bytes.
	iv	Input initial vector to combine with the first input block.
	key	Input key to use for decryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
	keyType	Input type of the key (allows to directly load decrypt key for AES CBC decrypt operation.)
[out]	plaintext	Output plain text

Returns: Status from encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_ctr	(	uint32_t	instance,
		const uint8_t *	input,
		uint32_t	inputSize,
		uint8_t	counter[16],
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	output,
		uint8_t	counterlast[16],
		uint32_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

	instance	LTC module instance number.
	input	Input data for CTR block mode
	inputSize	Size of input data in bytes
[in,out]	counter	Input counter (updates on return)
	key	Input key to use for forward AES cipher
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	output	Output data for CTR block mode
[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 encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_encrypt_tag_gcm	(	uint32_t	instance,
		const uint8_t *	plaintext,
		uint32_t	inputSize,
		const uint8_t *	iv,
		uint32_t	ivSize,
		const uint8_t *	aad,
		uint32_t	aadSize,
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	ciphertext,
		uint8_t *	tag,
		uint32_t	tagSize
	)

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

Parameters

	instance	LTC module instance number.
	plaintext	Input plain text to encrypt
	inputSize	Size of input data in bytes
	iv	Input initial vector
	ivSize	Size of the IV
	aad	Input additional authentication data
	aadSize	Input size in bytes of AAD
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	ciphertext	Output cipher text.
[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/decrypt operation

ltc_status_t LTC_DRV_aes_decrypt_tag_gcm	(	uint32_t	instance,
		const uint8_t *	ciphertext,
		uint32_t	inputSize,
		const uint8_t *	iv,
		uint32_t	ivSize,
		const uint8_t *	aad,
		uint32_t	aadSize,
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	plaintext,
		const uint8_t *	tag,
		uint32_t	tagSize
	)

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

Parameters

	instance	LTC module instance number.
	ciphertext	Input cipher text to decrypt
	inputSize	Size of input data in bytes
	iv	Input initial vector
	ivSize	Size of the IV
	aad	Input additional authentication data
	aadSize	Input size in bytes of AAD
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	plaintext	Output plain text.
	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 encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_encrypt_tag_ccm	(	uint32_t	instance,
		const uint8_t *	plaintext,
		uint32_t	inputSize,
		const uint8_t *	iv,
		uint32_t	ivSize,
		const uint8_t *	aad,
		uint32_t	aadSize,
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	ciphertext,
		uint8_t *	tag,
		uint32_t	tagSize
	)

Encrypts AES using CCM block mode.

Parameters

	instance	LTC module instance number.
	plaintext	Input plain text to encrypt
	inputSize	Size of input data in bytes. Zero means authentication only.
	iv	Nonce
	ivSize	Length of the Nonce in bytes. Must be 7, 8, 9, 10, 11, 12, or 13.
	aad	Input additional authentication data. Can be NULL if aadSize is zero.
	aadSize	Input size in bytes of AAD. Zero means data mode only (authentication skipped).
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	ciphertext	Output cipher text.
[out]	tag	Generated output tag. Set to NULL to skip tag processing.
	tagSize	Input size of the tag to generate, in bytes. Must be 4, 6, 8, 10, 12, 14, or 16.

Returns: Status from encrypt/decrypt operation

ltc_status_t LTC_DRV_aes_decrypt_tag_ccm	(	uint32_t	instance,
		const uint8_t *	ciphertext,
		uint32_t	inputSize,
		const uint8_t *	iv,
		uint32_t	ivSize,
		const uint8_t *	aad,
		uint32_t	aadSize,
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	plaintext,
		const uint8_t *	tag,
		uint32_t	tagSize
	)

Decrypts AES using CCM block mode.

Parameters

	instance	LTC module instance number.
	ciphertext	Input cipher text to decrypt
	inputSize	Size of input data in bytes. Zero means authentication only.
	iv	Nonce
	ivSize	Length of the Nonce in bytes. Must be 7, 8, 9, 10, 11, 12, or 13.
	aad	Input additional authentication data. Can be NULL if aadSize is zero.
	aadSize	Input size in bytes of AAD. Zero means data mode only (authentication skipped).
	key	Input key to use for decryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[out]	plaintext	Output plain text.
	tag	Received tag. Set to NULL to skip tag processing.
	tagSize	Input size of the received tag to compare with the computed tag, in bytes. Must be 4, 6, 8, 10, 12, 14, or 16.

Returns: Status from encrypt/decrypt operation

Overview

Macros

Enumerations

Functions

Enumeration Type Documentation

Function Documentation