CAAM AES driver

Overview

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

Macros
#define	CAAM_AES_BLOCK_SIZE   16
	AES block size in bytes.

Functions
status_t	CAAM_AES_EncryptEcb (CAAM_Type *base, caam_handle_t *handle, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t *key, size_t keySize)
	Encrypts AES using the ECB block mode. More...
status_t	CAAM_AES_DecryptEcb (CAAM_Type *base, caam_handle_t *handle, const uint8_t *ciphertext, uint8_t *plaintext, size_t size, const uint8_t *key, size_t keySize)
	Decrypts AES using ECB block mode. More...
status_t	CAAM_AES_EncryptCbc (CAAM_Type *base, caam_handle_t *handle, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[CAAM_AES_BLOCK_SIZE], const uint8_t *key, size_t keySize)
	Encrypts AES using CBC block mode. More...
status_t	CAAM_AES_DecryptCbc (CAAM_Type *base, caam_handle_t *handle, const uint8_t *ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[CAAM_AES_BLOCK_SIZE], const uint8_t *key, size_t keySize)
	Decrypts AES using CBC block mode. More...
status_t	CAAM_AES_CryptCtr (CAAM_Type *base, caam_handle_t *handle, const uint8_t *input, uint8_t *output, size_t size, uint8_t counter[CAAM_AES_BLOCK_SIZE], const uint8_t *key, size_t keySize, uint8_t counterlast[CAAM_AES_BLOCK_SIZE], size_t *szLeft)
	Encrypts or decrypts AES using CTR block mode. More...
status_t	CAAM_AES_EncryptTagCcm (CAAM_Type *base, caam_handle_t *handle, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t *iv, size_t ivSize, const uint8_t *aad, size_t aadSize, const uint8_t *key, size_t keySize, uint8_t *tag, size_t tagSize)
	Encrypts AES and tags using CCM block mode. More...
status_t	CAAM_AES_DecryptTagCcm (CAAM_Type *base, caam_handle_t *handle, 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 *key, size_t keySize, const uint8_t *tag, size_t tagSize)
	Decrypts AES and authenticates using CCM block mode. More...
status_t	CAAM_AES_EncryptTagGcm (CAAM_Type *base, caam_handle_t *handle, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t *iv, size_t ivSize, const uint8_t *aad, size_t aadSize, const uint8_t *key, size_t keySize, uint8_t *tag, size_t tagSize)
	Encrypts AES and tags using GCM block mode. More...
status_t	CAAM_AES_DecryptTagGcm (CAAM_Type *base, caam_handle_t *handle, 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 *key, size_t keySize, const uint8_t *tag, size_t tagSize)
	Decrypts AES and authenticates using GCM block mode. More...

Function Documentation

status_t CAAM_AES_EncryptEcb	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t *	key,
		size_t	keySize
	)

Encrypts AES using the ECB block mode.

Parameters

	base	CAAM 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.
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.

Returns

Status from encrypt operation

status_t CAAM_AES_DecryptEcb	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t *	key,
		size_t	keySize
	)

Decrypts AES using ECB block mode.

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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.
	key	Input key.
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.

Returns

Status from decrypt operation

status_t CAAM_AES_EncryptCbc	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t	iv[CAAM_AES_BLOCK_SIZE],
		const uint8_t *	key,
		size_t	keySize
	)

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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.
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.

Returns

Status from encrypt operation

status_t CAAM_AES_DecryptCbc	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	size,
		const uint8_t	iv[CAAM_AES_BLOCK_SIZE],
		const uint8_t *	key,
		size_t	keySize
	)

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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.
	key	Input key to use for decryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.

Returns

Status from decrypt operation

status_t CAAM_AES_CryptCtr	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	input,
		uint8_t *	output,
		size_t	size,
		uint8_t	counter[CAAM_AES_BLOCK_SIZE],
		const uint8_t *	key,
		size_t	keySize,
		uint8_t	counterlast[CAAM_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	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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)
	key	Input key to use for forward AES cipher
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[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 operation

status_t CAAM_AES_EncryptTagCcm	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t *	iv,
		size_t	ivSize,
		const uint8_t *	aad,
		size_t	aadSize,
		const uint8_t *	key,
		size_t	keySize,
		uint8_t *	tag,
		size_t	tagSize
	)

Encrypts AES and optionally tags using CCM block mode.

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	plaintext	Input plain text to encrypt
[out]	ciphertext	Output cipher text.
	size	Size of input and output 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]	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 operation

status_t CAAM_AES_DecryptTagCcm	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		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 *	key,
		size_t	keySize,
		const uint8_t *	tag,
		size_t	tagSize
	)

Decrypts AES and optionally authenticates using CCM block mode.

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	ciphertext	Input cipher text to decrypt
[out]	plaintext	Output plain text.
	size	Size of input and output data in bytes. Zero means authentication data 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 data skipped).
	key	Input key to use for decryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
	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 decrypt operation

status_t CAAM_AES_EncryptTagGcm	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	size,
		const uint8_t *	iv,
		size_t	ivSize,
		const uint8_t *	aad,
		size_t	aadSize,
		const uint8_t *	key,
		size_t	keySize,
		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	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
[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 CAAM_AES_DecryptTagGcm	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		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 *	key,
		size_t	keySize,
		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	CAAM peripheral base address
	handle	Handle used for this request. Specifies jobRing.
	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
	key	Input key to use for encryption
	keySize	Size of the input key, in bytes. Must be 16, 24, or 32.
	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