Macros
#define	XSECURE_KEK_DEC_ENABLE (0x1U)
	Triggers decryption operation for black key. More...

#define	XSECURE_AES_DISABLE_KUP_IV_UPDATE (0x0U)
	Disables IV and Key save features for KUP. More...

#define	XSECURE_AES_ENABLE_KUP_IV_UPDATE (0x1U)
	Enables IV and Key save features for KUP. More...

#define	XSECURE_AES_AAD_ENABLE (0x1U)
	Enables authentication of data pushed in AES engine. More...

#define	XSECURE_AES_AAD_DISABLE (0x0U)
	Disables authentication of data pushed in AES engine. More...

#define	XSECURE_AES_DEC_KEY_SRC_MASK (0x000000FFU)
	AES decrypt key source mask for KEK decryption. More...

#define	XSECURE_AES_DST_KEY_SRC_MASK (0x0000FF00U)
	AES destination key source mask for KEK decryption. More...

#define	XSECURE_AES_KEY_SIZE_MASK (0xFFFF0000U)
	Key Size mask. More...

#define	XSECURE_PMCDMA_DEVICEID (PMCDMA_0_DEVICE_ID)
	AES destination key source mask for KEK decryption. More...

#define	XSECURE_AES_KEY_WRAP_MAX_ROUNDS (5U)
	AES key wrap maximum rounds. More...

#define	XSECURE_AES_256BIT_MAX_KEY_BLOCK_ROUNDS (4U)
	AES 256-bit number of blocks. More...

#define	XSECURE_AES_128BIT_MAX_KEY_BLOCK_ROUNDS (2U)
	AES 128-bit number of blocks. More...

#define	XSECURE_AES_KEY_WRAP_INIT_DEF_VAL (0xA6A6A6A6A6A6A6A6U)
	AES init default value. More...

#define	XSECURE_AES_ECB_MODE_EN (1U)
	AES ECB Mode Enable. More...

#define	XSECURE_AES_ECB_MODE_DIS (0U)
	AES ECB Mode Enable. More...

#define	XSECURE_AES_64BIT_BLOCK_SIZE (8U)
	AES 64-bit block size in bytes. More...

Enumerations
enum	XSecure_AesKeySize { XSECURE_AES_KEY_SIZE_128 = 0, XSECURE_AES_KEY_SIZE_256 = 2, XSECURE_AES_KEY_SIZE_128 = 0, XSECURE_AES_KEY_SIZE_256 = 2 }
	Used for selecting the Key size of AES Core. More...

Functions
int	XSecure_AesInitialize (XSecure_Aes InstancePtr, XPmcDma PmcDmaPtr)
	This function initializes the AES instance pointer. More...

int	XSecure_AesSetDpaCm (const XSecure_Aes *InstancePtr, u32 DpaCmCfg)
	This function enables or disables DPA counter measures in AES engine based on user input. More...

int	XSecure_AesWriteKey (const XSecure_Aes *InstancePtr, XSecure_AesKeySrc KeySrc, XSecure_AesKeySize KeySize, u64 KeyAddr)
	This function writes the key provided into the specified AES key registers. More...

int	XSecure_AesUpdateAad (XSecure_Aes *InstancePtr, u64 AadAddr, u32 AadSize)
	This function is used to update the AES engine with Additional Authenticated Data(AAD). More...

int	XSecure_AesKekDecrypt (const XSecure_Aes *InstancePtr, XSecure_AesKeySrc DecKeySrc, XSecure_AesKeySrc DstKeySrc, u64 IvAddr, XSecure_AesKeySize KeySize)
	This function decrypts the KEK/obfuscated key which is found encrypted in boot header/eFUSE/BBRAM. More...

int	XSecure_AesDecryptInit (XSecure_Aes *InstancePtr, XSecure_AesKeySrc KeySrc, XSecure_AesKeySize KeySize, u64 IvAddr)
	This function initializes the AES engine for decryption. More...

int	XSecure_AesDecryptUpdate (XSecure_Aes *InstancePtr, u64 InDataAddr, u64 OutDataAddr, u32 Size, u8 IsLastChunk)
	This function is used to update the AES engine for decryption with provided data and stores the decrypted data at specified address. More...

int	XSecure_AesDecryptFinal (XSecure_Aes *InstancePtr, u64 GcmTagAddr)
	This function verifies the GCM tag provided for the data decrypted till the point. More...

int	XSecure_AesDecryptData (XSecure_Aes *InstancePtr, u64 InDataAddr, u64 OutDataAddr, u32 Size, u64 GcmTagAddr)
	This function decrypts the size (length) number of bytes of the passed in InDataAddr (source) buffer and stores the decrypted data in the OutDataAddr (destination) buffer and verifies GcmTagAddr. More...

int	XSecure_AesEncryptInit (XSecure_Aes *InstancePtr, XSecure_AesKeySrc KeySrc, XSecure_AesKeySize KeySize, u64 IvAddr)
	This function initializes the AES engine for encryption. More...

int	XSecure_AesEncryptUpdate (XSecure_Aes *InstancePtr, u64 InDataAddr, u64 OutDataAddr, u32 Size, u8 IsLastChunk)
	This function is used to update the AES engine for encryption with provided data and stores the decrypted data at specified address. More...

int	XSecure_AesEncryptFinal (XSecure_Aes *InstancePtr, u64 GcmTagAddr)
	This function updates the GCM tag for the encrypted data. More...

int	XSecure_AesEncryptData (XSecure_Aes *InstancePtr, u64 InDataAddr, u64 OutDataAddr, u32 Size, u64 GcmTagAddr)
	This function encrypts size (length) number of bytes of the passed in InDataAddr (source) buffer and stores the encrypted data along with its associated 16 byte tag in the OutDataAddr (destination) buffer and GcmTagAddr (buffer) respectively. More...

int	XSecure_AesCfgKupKeyNIv (const XSecure_Aes *InstancePtr, u8 Config)
	This function sets AES engine to update key and IV during decryption of secure header or footer of encrypted partition. More...

int	XSecure_AesGetNxtBlkLen (const XSecure_Aes InstancePtr, u32 Size)
	This function gives the AES next block length after decryption of PDI block. More...

int	XSecure_AesKeyZero (const XSecure_Aes *InstancePtr, XSecure_AesKeySrc KeySrc)
	This function zeroizes the selected AES key storage register. More...

int	XSecure_AesDpaCmDecryptData (const XSecure_Aes AesInstance, const u32 KeyPtr, const u32 DataPtr, u32 OutputPtr)
	This function updates data and key to the AES core in split mode with DPACM enabled. More...

int	XSecure_AesGmacCfg (XSecure_Aes *InstancePtr, u32 IsGmacEn)
	This function enables or disables the GMAC configuration. More...

int	XSecure_AesUpdateAadAndValidate (XSecure_Aes *InstancePtr, u64 AadAddr, u32 AadSize, u64 GcmTagAddr)
	This function is used to update the AES engine with Additional Authenticated Data(AAD) and validate. More...

int	XSecure_CfgSssAes (XPmcDma DmaPtr, const XSecure_Sss SssInstance)
	This function configures SSS to AES engine. More...

int	XSecure_AesIpiHandler (XPlmi_Cmd *Cmd)
	This function calls respective IPI handler based on the API_ID. More...

int	XSecure_AesInit (void)
	This function handler calls XSecure_AesInitialize Server API. More...

int	XSecure_AesKeyZeroize (u32 KeySrc)
	This function handler calls XSecure_AesKeyZero server API. More...

int	XSecure_AesKeyWrite (u8 KeySize, u8 KeySrc, u32 KeyAddrLow, u32 KeyAddrHigh)
	This function handler calls XSecure_AesWriteKey server API. More...

int	XSecure_AesPerformOperation (u32 SrcAddrLow, u32 SrcAddrHigh)
	This function handler calls XSecure_AesPerformOperation. More...

int	XSecure_AesEcbCfg (XSecure_Aes *InstancePtr, u32 EcbModeFlag)
	This function sets AES ECB mode. More...

int	XSecure_AesEcbDecrypt (XSecure_Aes *InstancePtr, u64 KeyAddr, XSecure_AesKeySize KeySize, u64 InDataAddr, u64 OutDataAddr, u32 Size)
	This function writes AES key into XSECURE_AES_USER_KEY_7 and decrypts the data in ECB mode. More...

int	XSecure_AesKeyUnwrap (XSecure_Aes InstancePtr, u8 EphAesKey, XSecure_AesKeySize KeySize, u8 *AesWrapKey, u64 OutDataAddr, u32 Size)
	This function unwraps the given AES wrapped key. More...

int	XSecure_PlatAesIpiHandler (XPlmi_Cmd *Cmd)
	This function calls respective IPI handler based on the API_ID. More...

Macro Definition Documentation

#define XSECURE_AES_128BIT_MAX_KEY_BLOCK_ROUNDS (2U)

AES 128-bit number of blocks.

Referenced by XSecure_AesKeyUnwrap().

#define XSECURE_AES_256BIT_MAX_KEY_BLOCK_ROUNDS (4U)

AES 256-bit number of blocks.

Referenced by XSecure_AesKeyUnwrap().

#define XSECURE_AES_64BIT_BLOCK_SIZE (8U)

AES 64-bit block size in bytes.

Referenced by XSecure_AesKeyUnwrap(), and XSecure_KeyUnwrap().

#define XSECURE_AES_AAD_DISABLE (0x0U)

Disables authentication of data pushed in AES engine.

#define XSECURE_AES_AAD_ENABLE (0x1U)

Enables authentication of data pushed in AES engine.

#define XSECURE_AES_DEC_KEY_SRC_MASK (0x000000FFU)

AES decrypt key source mask for KEK decryption.

#define XSECURE_AES_DISABLE_KUP_IV_UPDATE (0x0U)

Disables IV and Key save features for KUP.

#define XSECURE_AES_DST_KEY_SRC_MASK (0x0000FF00U)

AES destination key source mask for KEK decryption.

#define XSECURE_AES_ECB_MODE_DIS (0U)

AES ECB Mode Enable.

Referenced by XSecure_AesEcbCfg(), XSecure_AesEcbDecrypt(), and XSecure_AesKeyUnwrap().

#define XSECURE_AES_ECB_MODE_EN (1U)

AES ECB Mode Enable.

Referenced by XSecure_AesEcbCfg().

#define XSECURE_AES_ENABLE_KUP_IV_UPDATE (0x1U)

Enables IV and Key save features for KUP.

#define XSECURE_AES_KEY_SIZE_MASK (0xFFFF0000U)

Key Size mask.

#define XSECURE_AES_KEY_WRAP_INIT_DEF_VAL (0xA6A6A6A6A6A6A6A6U)

AES init default value.

Referenced by XSecure_AesKeyUnwrap().

#define XSECURE_AES_KEY_WRAP_MAX_ROUNDS (5U)

AES key wrap maximum rounds.

Referenced by XSecure_AesKeyUnwrap().

#define XSECURE_KEK_DEC_ENABLE (0x1U)

Triggers decryption operation for black key.

#define XSECURE_PMCDMA_DEVICEID (PMCDMA_0_DEVICE_ID)

AES destination key source mask for KEK decryption.

Referenced by XSecure_AesInit().

Enumeration Type Documentation

enum XSecure_AesKeySize

Used for selecting the Key size of AES Core.

Enumerator
XSECURE_AES_KEY_SIZE_128	Key Length = 16 bytes = 128 bits.
XSECURE_AES_KEY_SIZE_256	Key Length = 32 bytes = 256 bits.
XSECURE_AES_KEY_SIZE_128	Key Length = 32 bytes = 256 bits.
XSECURE_AES_KEY_SIZE_256	Key Length = 16 bytes = 128 bits.

Function Documentation

int XSecure_AesCfgKupKeyNIv	(	const XSecure_Aes *	InstancePtr,
		u8	Config
	)

This function sets AES engine to update key and IV during decryption of secure header or footer of encrypted partition.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
Config	XSECURE_AES_ENABLE_KUP_IV_UPDATE to enable KUP and IV update, XSECURE_AES_DISABLE_KUP_IV_UPDATE to disable KUP and IV update

Returns

XST_SUCCESS On successful configuration
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

Enable/disable the KUP and IV update as per the configuration provided

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesDecryptData	(	XSecure_Aes *	InstancePtr,
		u64	InDataAddr,
		u64	OutDataAddr,
		u32	Size,
		u64	GcmTagAddr
	)

This function decrypts the size (length) number of bytes of the passed in InDataAddr (source) buffer and stores the decrypted data in the OutDataAddr (destination) buffer and verifies GcmTagAddr.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
InDataAddr	Address of the encrypted data which needs to be decrypted
OutDataAddr	Address of output buffer where the decrypted to be updated
Size	Size of data to be decrypted in bytes, whereas number of bytes provided should be multiples of 4 for Versal For Versal Net, byte aligned data is acceptable
GcmTagAddr	Address of a buffer which should contain GCM Tag

Returns

XST_SUCCESS On successful decryption and GCM tag verification
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_INVALID_MODE If input mode is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

Update AES engine with encrypted data and get the decrypted data output

Verify GCM tag

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesDecryptFinal	(	XSecure_Aes *	InstancePtr,
		u64	GcmTagAddr
	)

This function verifies the GCM tag provided for the data decrypted till the point.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
GcmTagAddr	Address of a buffer which should holds GCM Tag

Returns

XST_SUCCESS On successful GCM tag verification
XSECURE_AES_GCM_TAG_MISMATCH User provided GCM tag does not match calculated tag
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_INVALID_MODE If input mode is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

Update AES engine with the GCM Tag data to verify the GCM Tag

Verify whether GCM Tag is matched or not

int XSecure_AesDecryptInit	(	XSecure_Aes *	InstancePtr,
		XSecure_AesKeySrc	KeySrc,
		XSecure_AesKeySize	KeySize,
		u64	IvAddr
	)

This function initializes the AES engine for decryption.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
KeySrc	Key Source for decryption of the data
KeySize	Size of the AES key to be used for decryption is XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size
IvAddr	Address to the buffer holding IV

Returns

XST_SUCCESS On successful init
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XSECURE_AES_ZERO_PUF_KEY_NOT_ALLOWED If keysrc is puf and puf key is zero
XST_FAILURE On failure

int XSecure_AesDecryptUpdate	(	XSecure_Aes *	InstancePtr,
		u64	InDataAddr,
		u64	OutDataAddr,
		u32	Size,
		u8	IsLastChunk
	)

This function is used to update the AES engine for decryption with provided data and stores the decrypted data at specified address.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
InDataAddr	Address of the encrypted data which needs to be decrypted
OutDataAddr	Address of output buffer where the decrypted to be updated
Size	Size of data to be decrypted in bytes, whereas number of bytes shall be aligned as below for Versal 16 byte aligned when it is not the last chunk 4 byte aligned when the data is the last chunk For Versal Net, byte aligned data is accepted
IsLastChunk	If this is the last update of data to be decrypted, this parameter should be set to TRUE otherwise FALSE

Returns

XST_SUCCESS On successful decryption of the data
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_UNALIGNED_SIZE_ERROR If input IsLastChunk is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

int XSecure_AesDpaCmDecryptData	(	const XSecure_Aes *	AesInstance,
		const u32 *	KeyPtr,
		const u32 *	DataPtr,
		u32 *	OutputPtr
	)

This function updates data and key to the AES core in split mode with DPACM enabled.

Parameters

AesInstance	InstancePtr Pointer to the XSecure_Aes instance
KeyPtr	Key Pointer
DataPtr	Data Pointer
OutputPtr	Output where the decrypted data to be stored

Returns

XST_SUCCESS On success
XSECURE_AESKAT_INVALID_PARAM Invalid Argument
XSECURE_AESDPACM_KAT_WRITE_KEY_FAILED_ERROR Error when AESDPACM key write fails
XSECURE_AESDPACM_KAT_KEYLOAD_FAILED_ERROR Error when AESDPACM key load fails
XSECURE_AESDPACM_SSS_CFG_FAILED_ERROR Error when AESDPACM sss configuration fails
XSECURE_AESDPACM_KAT_FAILED_ERROR Error when AESDPACM KAT fails
XST_FAILURE On failure

Note: This function is used during DPACM KAT where key and data are updated in split mode with DPACM enabled

Configure AES for Encryption

Configure AES engine in split mode to update data and key to aes core

Write Key mask value

Write AES key

Start the message.

Configure the PMC DMA Tx/Rx for the incoming Block.

References XSECURE_AESKAT_INVALID_PARAM.

Referenced by XSecure_AesDecryptCmKat().

int XSecure_AesEcbCfg	(	XSecure_Aes *	InstancePtr,
		u32	EcbModeFlag
	)

This function sets AES ECB mode.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
EcbModeFlag	Flag to enable/disable ECB mode

Returns

XST_SUCCESS On Success
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR On state mismatch

References XSECURE_AES_ECB_MODE_DIS, XSECURE_AES_ECB_MODE_EN, XSECURE_AES_ECB_OFFSET, XSECURE_AES_INVALID_PARAM, and XSECURE_AES_STATE_MISMATCH_ERROR.

int XSecure_AesEcbDecrypt	(	XSecure_Aes *	InstancePtr,
		u64	KeyAddr,
		XSecure_AesKeySize	KeySize,
		u64	InDataAddr,
		u64	OutDataAddr,
		u32	Size
	)

This function writes AES key into XSECURE_AES_USER_KEY_7 and decrypts the data in ECB mode.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
KeyAddr	Address of the key to be programmed in XSECURE_AES_USER_KEY_7
KeySize	Size of the AES key to be used for decryption is XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size
InDataAddr	Address of the encrypted data which needs to be decrypted
OutDataAddr	Address of output buffer where the decrypted data to be updated
Size	Size of data to be decrypted in bytes, whereas number of bytes shall be aligned as below 16 byte aligned when it is not the last chunk 4 byte aligned when the data is the last chunk

Returns

XST_SUCCESS On Success
XST_FAILURE On Failure

References XSECURE_AES_DATA_SWAP_OFFSET, XSECURE_AES_ECB_MODE_DIS, XSECURE_AES_ECB_OFFSET, XSECURE_AES_SOFT_RST_OFFSET, XSECURE_AES_USER_KEY_7, XSecure_AesDecryptUpdate(), XSecure_AesKeyZero(), XSecure_AesWriteKey(), XSECURE_DISABLE_BYTE_SWAP, and XSecure_SetReset().

int XSecure_AesEncryptData	(	XSecure_Aes *	InstancePtr,
		u64	InDataAddr,
		u64	OutDataAddr,
		u32	Size,
		u64	GcmTagAddr
	)

This function encrypts size (length) number of bytes of the passed in InDataAddr (source) buffer and stores the encrypted data along with its associated 16 byte tag in the OutDataAddr (destination) buffer and GcmTagAddr (buffer) respectively.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
InDataAddr	Address of the data which needs to be encrypted
OutDataAddr	Address of output buffer where the encrypted data to be updated
Size	Size of data to be encrypted in bytes, whereas number of bytes provided should be multiples of 4 for Versal For Versal Net, byte aligned data is acceptable
GcmTagAddr	Address to the buffer of GCM tag size, where the API updates GCM tag

Returns

XST_SUCCESS On successful encryption
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_INVALID_MODE If input mode is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

Validate the input arguments

Update the data to AES engine

Get the GCM Tag

int XSecure_AesEncryptFinal	(	XSecure_Aes *	InstancePtr,
		u64	GcmTagAddr
	)

This function updates the GCM tag for the encrypted data.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
GcmTagAddr	Address to the buffer of GCM tag size, where the API updates GCM tag

Returns

XST_SUCCESS On successful GCM tag updation
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_INVALID_MODE If input mode is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesEncryptInit	(	XSecure_Aes *	InstancePtr,
		XSecure_AesKeySrc	KeySrc,
		XSecure_AesKeySize	KeySize,
		u64	IvAddr
	)

This function initializes the AES engine for encryption.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
KeySrc	Key Source for encryption
KeySize	Size of the AES key to be used for encryption is XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size
IvAddr	Address to the buffer holding IV

Returns

XST_SUCCESS On successful initialization
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XSECURE_AES_ZERO_PUF_KEY_NOT_ALLOWED If keysrc is puf and puf key is zero
XST_FAILURE On failure

int XSecure_AesEncryptUpdate	(	XSecure_Aes *	InstancePtr,
		u64	InDataAddr,
		u64	OutDataAddr,
		u32	Size,
		u8	IsLastChunk
	)

This function is used to update the AES engine for encryption with provided data and stores the decrypted data at specified address.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
InDataAddr	Address of the encrypted data which needs to be encrypted
OutDataAddr	Address of output buffer where the encrypted data to be updated
Size	Size of data to be decrypted in bytes, whereas number of bytes shall be aligned as below for Versal 16 byte aligned when it is not the last chunk 4 byte aligned when the data is the last chunk For Versal Net, byte aligned data is acceptable
IsLastChunk	If this is the last update of data to be encrypted, this parameter should be set to TRUE otherwise FALSE

Returns

XST_SUCCESS On successful encryption of the data
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_UNALIGNED_SIZE_ERROR If input IsLastChunk is invalid
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XST_FAILURE On failure

int XSecure_AesGetNxtBlkLen	(	const XSecure_Aes *	InstancePtr,
		u32 *	Size
	)

This function gives the AES next block length after decryption of PDI block.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
Size	Pointer to a 32 bit variable where next block length will be updated

Returns

XST_SUCCESS On success
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesGmacCfg	(	XSecure_Aes *	InstancePtr,
		u32	IsGmacEn
	)

This function enables or disables the GMAC configuration.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
IsGmacEn	User choice to enable/disable GMAC

Returns

XST_SUCCESS On successful configuration
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR On state mismatch

Note: To generate GMAC on AAD data, this API must be called with IsGmacEn set to TRUE just before the last AAD update. After the last AAD update XSecure_AesEncryptFinal or XSecure_AesDecryptFinal must be called to generate or validate the GMAC tag.

Enable/disable GMAC configuration

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesInit ( void )

This function handler calls XSecure_AesInitialize Server API.

Returns

XST_SUCCESS If the initialization is successful
XST_FAILURE If PMCDMA instance is NULL.

Initialize the Aes driver so that it's ready to use

References XSecure_AesInitialize(), XSecure_GetAesInstance(), and XSECURE_PMCDMA_DEVICEID.

int XSecure_AesInitialize	(	XSecure_Aes *	InstancePtr,
		XPmcDma *	PmcDmaPtr
	)

This function initializes the AES instance pointer.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
PmcDmaPtr	Pointer to the XPmcDma instance

Returns

XST_SUCCESS If initialization was successful
XSECURE_AES_INVALID_PARAM For invalid parameter
XST_FAILURE On failure

Note: All the inputs are accepted in little endian format, but AES engine accepts the data in big endianness, this will be taken care while passing data to AES engine

Initialize the instance

Initialize SSS Instance

int XSecure_AesIpiHandler ( XPlmi_Cmd * Cmd )

This function calls respective IPI handler based on the API_ID.

Parameters

Cmd	is pointer to the command structure

Returns

XST_SUCCESS If the handler execution is successful
XST_INVALID_PARAM On invalid parameter
XST_DEVICE_BUSY If IPI channel is busy

Handle the present command based on AES core status

Call the respective API handler according to API ID

XSecure_AesInit
XSecure_AesOperationInit
XSecure_AesAadUpdate
XSecure_AesEncUpdate
XSecure_AesEncFinal
XSecure_AesDecUpdate
XSecure_AesDecFinal
XSecure_AesKeyZeroize
XSecure_AesKeyWrite
XSecure_AesDecryptKek
XSecure_AesSetDpaCmConfig
XSecure_AesPerformOperation

References XSecure_AesKeyWrite(), XSecure_AesKeyZeroize(), XSecure_AesPerformOperation(), XSECURE_API, XSECURE_API_AES_DECRYPT_FINAL, XSECURE_API_AES_DECRYPT_UPDATE, XSECURE_API_AES_ENCRYPT_FINAL, XSECURE_API_AES_ENCRYPT_UPDATE, XSECURE_API_AES_INIT, XSECURE_API_AES_KEK_DECRYPT, XSECURE_API_AES_KEY_ZERO, XSECURE_API_AES_OP_INIT, XSECURE_API_AES_PERFORM_OPERATION, XSECURE_API_AES_SET_DPA_CM, XSECURE_API_AES_UPDATE_AAD, XSECURE_API_AES_WRITE_KEY, XSECURE_API_ID_MASK, XSecure_GetAesInstance(), XSecure_IpiEventHandling(), XSecure_MakeResFree(), and XSecure_Printf.

int XSecure_AesKekDecrypt	(	const XSecure_Aes *	InstancePtr,
		XSecure_AesKeySrc	DecKeySrc,
		XSecure_AesKeySrc	DstKeySrc,
		u64	IvAddr,
		XSecure_AesKeySize	KeySize
	)

This function decrypts the KEK/obfuscated key which is found encrypted in boot header/eFUSE/BBRAM.

It then places it in the specified red key register.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
DecKeySrc	Select key source which holds KEK and needs to be decrypted
DstKeySrc	Select the key in which decrypted red key should be updated
IvAddr	Address of IV holding buffer for decryption of the key
KeySize	A variable of type XSecure_AesKeySize, which specifies the size of the key to be XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size

Returns

XST_SUCCESS On successful key decryption
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch occurs
XST_FAILURE If timeout has occurred

Load AES key to registers from PUF key

Configure the AES engine for Key decryption and starts operation

Trigger key decryption operation

Wait for AES Decryption completion.

int XSecure_AesKeyUnwrap	(	XSecure_Aes *	InstancePtr,
		u8 *	EphAesKey,
		XSecure_AesKeySize	KeySize,
		u8 *	AesWrapKey,
		u64	OutDataAddr,
		u32	Size
	)

This function unwraps the given AES wrapped key.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
EphAesKey	Address of the key to be programmed in XSECURE_AES_USER_KEY_7
KeySize	Size of the AES key to be used for decryption is XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size
AesWrapKey	Address of the wrapped key which needs to be decrypted
OutDataAddr	Address of output buffer where the decrypted data to be updated
Size	Size of data to be decrypted in bytes, whereas number of bytes shall be aligned as below 16 byte aligned when it is not the last chunk 4 byte aligned when the data is the last chunk

Returns

XST_SUCCESS On success.
XSECURE_ERR_AES_KEY_SIZE_NOT_SUPPORTED If AES key size is invalid.
XSECURE_ERR_AES_KEY_UNWRAP_FAILED_ERROR If key unwrap is failed.
XST_FAILURE On failure.

References XSECURE_AES_128BIT_MAX_KEY_BLOCK_ROUNDS, XSECURE_AES_256BIT_MAX_KEY_BLOCK_ROUNDS, XSECURE_AES_64BIT_BLOCK_SIZE, XSECURE_AES_DATA_SWAP_OFFSET, XSECURE_AES_ECB_MODE_DIS, XSECURE_AES_ECB_OFFSET, XSECURE_AES_KEY_WRAP_INIT_DEF_VAL, XSECURE_AES_KEY_WRAP_MAX_ROUNDS, XSECURE_AES_SOFT_RST_OFFSET, XSECURE_AES_USER_KEY_7, XSecure_AesDecryptUpdate(), XSecure_AesKeyZero(), XSecure_AesWriteKey(), XSECURE_DISABLE_BYTE_SWAP, XSECURE_ERR_AES_KEY_SIZE_NOT_SUPPORTED, XSECURE_ERR_AES_KEY_UNWRAP_FAILED_ERROR, and XSecure_SetReset().

Referenced by XSecure_KeyUnwrap().

int XSecure_AesKeyWrite	(	u8	KeySize,
		u8	KeySrc,
		u32	KeyAddrLow,
		u32	KeyAddrHigh
	)

This function handler calls XSecure_AesWriteKey server API.

Parameters

KeySize	Size of the key to specify 128/256 bit key
KeySrc	KeySrc to which key has to be written
KeyAddrLow	Lower 32 bit address of the Key
KeyAddrHigh	Higher 32 bit address of the Key

Returns

XST_SUCCESS If the key write is successful
XSECURE_AES_INVALID_PARAM For invalid parameter
XST_FAILURE On failure

Writes the key provided into the specified AES key registers

References XSECURE_AES_BH_KEY, XSECURE_AES_BH_RED_KEY, XSECURE_AES_INVALID_PARAM, XSecure_AesWriteKey(), and XSecure_GetAesInstance().

Referenced by XSecure_AesIpiHandler().

int XSecure_AesKeyZero	(	const XSecure_Aes *	InstancePtr,
		XSecure_AesKeySrc	KeySrc
	)

This function zeroizes the selected AES key storage register.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
KeySrc	Select the key source which needs to be zeroized

Returns

XST_SUCCESS When key zeroization is success
XST_INVALID_PARAM if key source is invalid
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XSECURE_AES_KEY_CLEAR_ERROR AES key clear error

Zeroize the specified key source

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesKeyZeroize ( u32 KeySrc )

This function handler calls XSecure_AesKeyZero server API.

Parameters

KeySrc Key source to be zeroized

Returns

XST_SUCCESS If the key zeroize is successful
XSECURE_AES_INVALID_PARAM On invalid parameter
XST_FAILURE On failure

Validate key source to allow clearing of keysources other than device keys

References XSECURE_AES_EXPANDED_KEYS, XSECURE_AES_INVALID_PARAM, XSECURE_AES_KUP_KEY, XSECURE_AES_PUF_KEY, XSECURE_AES_USER_KEY_0, XSECURE_AES_USER_KEY_7, XSecure_AesKeyZero(), and XSecure_GetAesInstance().

Referenced by XSecure_AesIpiHandler().

int XSecure_AesPerformOperation	(	u32	SrcAddrLow,
		u32	SrcAddrHigh
	)

This function handler calls XSecure_AesPerformOperation.

Parameters

SrcAddrLow	Lower 32 bit address of the XSecure_AesDataBlockParams structure.
SrcAddrHigh	Higher 32 bit address of the XSecure_AesDataBlockParams structure.

Returns

XST_SUCCESS If the initialization is successful
XST_FAILURE On failure

Validate key source and initialise AES to encryption/decryption

Update AAD

Based on user's choice GCM/GMAC encryption/decryption is performed

References XSecure_AesDecryptData(), XSecure_AesDecryptFinal(), XSecure_AesEncryptData(), XSecure_AesEncryptFinal(), XSECURE_ENCRYPT, and XSecure_GetAesInstance().

int XSecure_AesSetDpaCm	(	const XSecure_Aes *	InstancePtr,
		u32	DpaCmCfg
	)

This function enables or disables DPA counter measures in AES engine based on user input.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
DpaCmCfg	User choice to enable/disable DPA CM TRUE - to enable AES DPA counter measure (Default setting) FALSE - to disable AES DPA counter measure

Returns

XST_SUCCESS If configuration is success
XSECURE_AES_INVALID_PARAM For invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch is occurred
XSECURE_AES_DPA_CM_NOT_SUPPORTED If DPA CM is disabled on chip (Enabling/Disabling in AES engine does not impact functionality)
XST_FAILURE On failure

Set DPA counter measures as per the user input

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesUpdateAad	(	XSecure_Aes *	InstancePtr,
		u64	AadAddr,
		u32	AadSize
	)

This function is used to update the AES engine with Additional Authenticated Data(AAD).

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
AadAddr	Address of the additional authenticated data
AadSize	Size of additional authenticated data in bytes, whereas number of bytes provided should be quad-word aligned(multiples of 16 bytes) for Versal For Versal Net, byte aligned data is accepted

Returns

XST_SUCCESS On successful update of AAD
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR If State mismatch occurs
XST_FAILURE On failure to update AAD

Note: The API must be called after XSecure_AesEncryptInit() or XSecure_AesDecryptInit()

Enable AAD by writing to the register

Configure DMA and transfer AAD to AES engine

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesUpdateAadAndValidate	(	XSecure_Aes *	InstancePtr,
		u64	AadAddr,
		u32	AadSize,
		u64	GcmTagAddr
	)

This function is used to update the AES engine with Additional Authenticated Data(AAD) and validate.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
AadAddr	Address of the additional authenticated data
AadSize	Size of additional authenticated data in bytes, whereas number of bytes provided should be multiples of 4
GcmTagAddr	GCM tag of the additional authenticated data

Returns

XST_SUCCESS AAD updation and validation is success
XSECURE_AES_INVALID_PARAM On invalid parameter
XSECURE_AES_STATE_MISMATCH_ERROR On state mismatch
XSECURE_AES_GCM_TAG_MISMATCH User provided GCM tag does not match calculated tag
XST_FAILURE On failure

References XSECURE_AES_INVALID_PARAM.

int XSecure_AesWriteKey	(	const XSecure_Aes *	InstancePtr,
		XSecure_AesKeySrc	KeySrc,
		XSecure_AesKeySize	KeySize,
		u64	KeyAddr
	)

This function writes the key provided into the specified AES key registers.

Parameters

InstancePtr	Pointer to the XSecure_Aes instance
KeySrc	Key Source to be selected to which provided key should be updated by XSECURE_AES_USER_KEY_0 XSECURE_AES_USER_KEY_1 XSECURE_AES_USER_KEY_2 XSECURE_AES_USER_KEY_3 XSECURE_AES_USER_KEY_4 XSECURE_AES_USER_KEY_5 XSECURE_AES_USER_KEY_6 XSECURE_AES_USER_KEY_7 XSECURE_AES_BH_KEY
KeySize	A variable of type XSecure_AesKeySize, which holds the size of the input key to be written by XSECURE_AES_KEY_SIZE_128 for 128 bit key size XSECURE_AES_KEY_SIZE_256 for 256 bit key size
KeyAddr	Address of a buffer which should contain the key to be written