XilSecure AES ZynqMP APIs

Macros
#define	XSecure_AesWaitForDone(InstancePtr)
	This macro waits for AES engine completes configured operation. More...

Functions
s32	XSecure_AesInitialize (XSecure_Aes *InstancePtr, XCsuDma *CsuDmaPtr, u32 KeySel, u32 *IvPtr, u32 *KeyPtr)
	This function initializes the instance pointer. More...
u32	XSecure_AesDecryptInit (XSecure_Aes *InstancePtr, u8 *DecData, u32 Size, u8 *GcmTagAddr)
	This function initializes the AES engine for decryption and is required to be called before calling XSecure_AesDecryptUpdate. More...
s32	XSecure_AesDecryptUpdate (XSecure_Aes *InstancePtr, u8 *EncData, u32 Size)
	This function decrypts the encrypted data passed in and updates the GCM tag from any previous calls. More...
s32	XSecure_AesDecryptData (XSecure_Aes *InstancePtr, u8 *DecData, u8 *EncData, u32 Size, u8 *GcmTagAddr)
	This function decrypts the encrypted data provided and updates the DecData buffer with decrypted data. More...
s32	XSecure_AesDecrypt (XSecure_Aes *InstancePtr, u8 *Dst, const u8 *Src, u32 Length)
	This function will handle the AES-GCM Decryption. More...
u32	XSecure_AesEncryptInit (XSecure_Aes *InstancePtr, u8 *EncData, u32 Size)
	This function is used to initialize the AES engine for encryption. More...
u32	XSecure_AesEncryptUpdate (XSecure_Aes *InstancePtr, const u8 *Data, u32 Size)
	This function encrypts the clear-text data passed in and updates the GCM tag from any previous calls. More...
u32	XSecure_AesEncryptData (XSecure_Aes *InstancePtr, u8 *Dst, const u8 *Src, u32 Len)
	This function encrypts Len (length) number of bytes of the passed in Src (source) buffer and stores the encrypted data along with its associated 16 byte tag in the Dst (destination) buffer. More...
void	XSecure_AesReset (XSecure_Aes *InstancePtr)
	This function sets and then clears the AES-GCM's reset line. More...

Macro Definition Documentation

#define XSecure_AesWaitForDone

(

InstancePtr

)

Value:

Xil_WaitForEvent((InstancePtr)->BaseAddress + XSECURE_CSU_AES_STS_OFFSET,\
                        XSECURE_CSU_AES_STS_AES_BUSY,   \
                        0U,     \
                        XSECURE_AES_TIMEOUT_MAX)

This macro waits for AES engine completes configured operation.

Parameters

InstancePtr

Pointer to the XSecure_Aes instance.

Returns

XST_SUCCESS if the AES engine completes configured operation. XST_FAILURE if a timeout has occurred.

Referenced by XSecure_AesDecryptUpdate(), and XSecure_AesEncryptUpdate().

Function Documentation

s32 XSecure_AesDecrypt	(	XSecure_Aes *	InstancePtr,
		u8 *	Dst,
		const u8 *	Src,
		u32	Length
	)

This function will handle the AES-GCM Decryption.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
Src	Pointer to encrypted data source location
Dst	Pointer to location where decrypted data will be written.
Length	Expected total length of decrypted image expected.

Returns

returns XST_SUCCESS if successful, or the relevant errorcode.

Note

This function is used for decrypting the Image's partition encrypted by Bootgen

References XSecure_AesKeyZero(), XSecure_AesReset(), XSECURE_CSU_AES_CFG_OFFSET, XSECURE_CSU_AES_IV_0_OFFSET, XSECURE_CSU_AES_IV_3_OFFSET, XSECURE_CSU_AES_KEY_CLR_OFFSET, XSECURE_CSU_AES_KUP_0_OFFSET, XSECURE_CSU_AES_RESET_OFFSET, XSecure_Out32, XSecure_SetReset(), and XSECURE_SSS_DMA0.

Referenced by SecureAesExample().

s32 XSecure_AesDecryptData	(	XSecure_Aes *	InstancePtr,
		u8 *	DecData,
		u8 *	EncData,
		u32	Size,
		u8 *	GcmTagAddr
	)

This function decrypts the encrypted data provided and updates the DecData buffer with decrypted data.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
DecData	Pointer to a buffer in which decrypted data will be stored.
EncData	Pointer to the encrypted data which needs to be decrypted.
Size	Size of data to be decrypted in bytes, whereas the number of bytes should be multiples of 4.
Size	Size of data to be decrypted in bytes, whereas the number of bytes should be multiples of 4.
GcmTagAddr	Pointer to a buffer in which GCM tag address will be stored.

Returns

This API returns the status of GCM tag matching.

• XSECURE_CSU_AES_GCM_TAG_MISMATCH: If GCM tag was mismatched
• XST_SUCCESS: If GCM tag was matched.

Note

When using this function to decrypt data that was encrypted with XSecure_AesEncryptData, the GCM tag will be stored as the last sixteen (16) bytes of data in XSecure_AesEncryptData's Dst (destination) buffer and should be used as the GcmTagAddr's pointer.

References XSecure_AesDecryptInit(), and XSecure_AesDecryptUpdate().

u32 XSecure_AesDecryptInit	(	XSecure_Aes *	InstancePtr,
		u8 *	DecData,
		u32	Size,
		u8 *	GcmTagAddr
	)

This function initializes the AES engine for decryption and is required to be called before calling XSecure_AesDecryptUpdate.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
DecData	Pointer in which decrypted data will be stored.
Size	Expected size of the data in bytes whereas the number of bytes provided should be multiples of 4.
GcmTagAddr	Pointer to the GCM tag which needs to be verified during decryption of the data.

Returns

None

Note

If all of the data to be decrypted is available, the XSecure_AesDecryptData function can be used instead.

References XSecure_AesKeyZero(), XSecure_AesReset(), XSECURE_CSU_AES_CFG_OFFSET, XSECURE_CSU_AES_KEY_CLR_OFFSET, XSECURE_CSU_AES_KUP_0_OFFSET, XSECURE_CSU_AES_RESET_OFFSET, XSECURE_CSU_AES_START_MSG_OFFSET, XSecure_Out32, XSecure_SetReset(), and XSECURE_SSS_DMA0.

s32 XSecure_AesDecryptUpdate	(	XSecure_Aes *	InstancePtr,
		u8 *	EncData,
		u32	Size
	)

This function decrypts the encrypted data passed in and updates the GCM tag from any previous calls.

The size from XSecure_AesDecryptInit is decremented from the size passed into this function to determine when the GCM tag passed to XSecure_AesDecryptInit needs to be compared to the GCM tag calculated in the AES engine.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
EncData	Pointer to the encrypted data which needs to be decrypted.
Size	Expected size of data to be decrypted in bytes, whereas the number of bytes should be multiples of 4.

Returns

Final call of this API returns the status of GCM tag matching.

• XSECURE_CSU_AES_GCM_TAG_MISMATCH: If GCM tag is mismatched
• XSECURE_CSU_AES_ZEROIZATION_ERROR: If GCM tag is mismatched, zeroize the decrypted data and send the status of zeroization.
• XST_SUCCESS: If GCM tag is matching.

Note

When Size of the data equals to size of the remaining data that data will be treated as final data. This API can be called multpile times but sum of all Sizes should be equal to Size mention in init. Return of the final call of this API tells whether GCM tag is matching or not.

References XSecure_AesKeyZero(), XSecure_AesWaitForDone, XSECURE_CSU_AES_IV_3_OFFSET, XSECURE_CSU_AES_RESET_OFFSET, XSECURE_CSU_AES_STS_OFFSET, and XSecure_SetReset().

u32 XSecure_AesEncryptData	(	XSecure_Aes *	InstancePtr,
		u8 *	Dst,
		const u8 *	Src,
		u32	Len
	)

This function encrypts Len (length) number of bytes of the passed in Src (source) buffer and stores the encrypted data along with its associated 16 byte tag in the Dst (destination) buffer.

Parameters

InstancePtr	A pointer to the XSecure_Aes instance.
Dst	A pointer to a buffer where encrypted data along with GCM tag will be stored. The Size of buffer provided should be Size of the data plus 16 bytes
Src	A pointer to input data for encryption.
Len	Size of input data in bytes, whereas the number of bytes provided should be multiples of 4.

Returns

None

Note

If data to be encrypted is not available in one buffer one can call XSecure_AesEncryptInit() and update the AES engine with data to be encrypted by calling XSecure_AesEncryptUpdate() API multiple times as required.

References XSecure_AesEncryptInit(), and XSecure_AesEncryptUpdate().

u32 XSecure_AesEncryptInit	(	XSecure_Aes *	InstancePtr,
		u8 *	EncData,
		u32	Size
	)

This function is used to initialize the AES engine for encryption.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
EncData	Pointer of a buffer in which encrypted data along with GCM TAG will be stored. Buffer size should be Size of data plus 16 bytes.
Size	A 32 bit variable, which holds the size of the input data to be encrypted in bytes, whereas number of bytes provided should be multiples of 4.

Returns

None

Note

If all of the data to be encrypted is available, the XSecure_AesEncryptData function can be used instead.

References XSecure_AesKeyZero(), XSecure_AesReset(), XSECURE_CSU_AES_CFG_OFFSET, XSECURE_CSU_AES_KEY_CLR_OFFSET, XSECURE_CSU_AES_KUP_0_OFFSET, XSECURE_CSU_AES_RESET_OFFSET, XSECURE_CSU_AES_START_MSG_OFFSET, XSecure_Out32, XSecure_SetReset(), and XSECURE_SSS_DMA0.

u32 XSecure_AesEncryptUpdate	(	XSecure_Aes *	InstancePtr,
		const u8 *	Data,
		u32	Size
	)

This function encrypts the clear-text data passed in and updates the GCM tag from any previous calls.

The size from XSecure_AesEncryptInit is decremented from the size passed into this function to determine when the final CSU DMA transfer of data to the AES-GCM cryptographic core.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
Data	Pointer to the data for which encryption should be performed.
Size	A 32 bit variable, which holds the size of the input data in bytes, whereas the number of bytes provided should be multiples of 4.

Returns

None

Note

If all of the data to be encrypted is available, the XSecure_AesEncryptData function can be used instead.

References XSecure_AesKeyZero(), XSecure_AesWaitForDone, XSECURE_CSU_AES_RESET_OFFSET, and XSecure_SetReset().

s32 XSecure_AesInitialize	(	XSecure_Aes *	InstancePtr,
		XCsuDma *	CsuDmaPtr,
		u32	KeySel,
		u32 *	IvPtr,
		u32 *	KeyPtr
	)

This function initializes the instance pointer.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance.
CsuDmaPtr	Pointer to the XCsuDma instance.
KeySel	Key source for decryption, can be KUP/device key XSECURE_CSU_AES_KEY_SRC_KUP :For KUP key XSECURE_CSU_AES_KEY_SRC_DEV :For Device Key
IvPtr	Pointer to the Initialization Vector for decryption
KeyPtr	Pointer to Aes key in case KUP key is used. Pass Null if the device key is to be used.

Returns

XST_SUCCESS if initialization was successful.

Note

All the inputs are accepted in little endian format but the AES engine accepts the data in big endian format, The decryption and encryption functions in xsecure_aes handle the little endian to big endian conversion using few API's, Xil_Htonl (provided by Xilinx xil_io library) and XSecure_AesCsuDmaConfigureEndiannes for handling data endianness conversions. If higher performance is needed, users can strictly use data in big endian format and modify the xsecure_aes functions to remove the use of the Xil_Htonl and XSecure_AesCsuDmaConfigureEndiannes functions as required.

References XSecure_CryptoCheck(), and XSECURE_CSU_AES_BASE.

void XSecure_AesReset

(

XSecure_Aes *

InstancePtr

)

This function sets and then clears the AES-GCM's reset line.

Parameters

InstancePtr

is a pointer to the XSecure_Aes instance.

Returns

None

References XSECURE_CSU_AES_RESET_OFFSET, and XSecure_ReleaseReset().

Referenced by XSecure_AesDecrypt(), XSecure_AesDecryptInit(), and XSecure_AesEncryptInit().