xilsecure
Vitis Drivers API Documentation
Functions
xsecure.c File Reference

Overview

This file contains the implementation of the interface functions for secure library. 

MODIFICATION HISTORY:
Ver   Who Date     Changes
----- --- -------- -------------------------------------------------------
1.0   DP  02/15/17 Initial release
2.2   vns 09/18/17 Added APIs to support generic functionality
                   for SHA3 and RSA hardware at linux level.
                   Removed RSA-SHA2 authentication support
                   for loading linux image and dtb from u-boot, as here it
                   is using SHA2 hash and single RSA key pair authentication
3.0   vns 02/21/18 Added support for single partition image authentication
                   and/or decryption.
3.1   vns 04/13/18 Added device key support even if authentication is not
                   been enabled for single partition image, when PMUFW is
                   compiled by enabling secure environment variable in bsp
                   settings.
      ka  04/10/18 Added support for user-efuse revocation
      ka  04/18/18 Added support for Zeroization of the memory in case of
                   Gcm-Tag mismatch
3.2   ka  04/04/18 Added support for Sha3_Update, if the payload is not
             4 bytes aligned.
      ka  08/03/18 Added XSecure_Aes Api's to encrypt or decrypt data-blobs.
      ka  10/25/18 Added support to clear user key after use.
4.0   arc 18/12/18 Fixed MISRA-C violations.
      arc 12/02/19 Added support for validate image format.
      rama 18/03/19 Fixed IAR compiler errors and warnings
      arc 03/20/19 Reading the return value of the functions to validate
4.0  Nava 19/03/19 In the current implementation, the SecureIv variable
                   is sharing between xilfpga and Xilsecure libraries.
                   To avoid data sharing conflicts removed SecureIV
                   shared variable dependency.
      mmd 03/15/19 Refactored the code
      psl 03/26/19 Fixed MISRA-C violation
4.1   psl 07/02/19 Fixed Coverity warning.
      mmd 07/05/19 Optimized the code
      psl 07/31/19 Fixed MISRA-C violations.
4.2   kal 03/12/20 Authenticate SizeofImgHdr before use, in case of failure
                   return XSECURE_IMAGE_HEADER_SIZE_ERR.
                   Added support to hold Aes engine in reset after secure
                   image processing.
      vns 03/24/20 Cleared locally copied user key
                   Corrected IV calculation
      ana 04/03/20 Removed the support of storing key in global array
      rpo 04/09/20 Aligned the buffers used by DMA to 64 bytes
      kpt 04/10/20 Resolved coverity warnings
      ana 04/24/20 Removed support of boot header RSA with 0x1 and 0x2
4.6   am  09/17/21 Resolved compiler warnings
4.7   am  11/26/21 Resolved doxygen warnings
      har 01/03/22 Updated Status as XSECURE_SHA3_INIT_FAIL in case of failure
                   in XSecure_Sha3Initialize()
5.2   ng  07/05/23 add SDT support
Note





Functions


u32 XSecure_CsuDmaInit (void)


 This function is used to initialize the DMA driver.  More...


 


XCsuDma * Xsecure_GetCsuDma (void)


 This function is used to initialize CsuDma and return CsuDma pointer.  More...


 


u32 XSecure_Sha3Hash (u32 SrcAddrHigh, u32 SrcAddrLow, u32 SrcSize, u32 Flags)


 This function access the xilsecure SHA3 hardware based on the flags provided to calculate the SHA3 hash.  More...


 


u32 XSecure_RsaCore (u32 SrcAddrHigh, u32 SrcAddrLow, u32 SrcSize, u32 Flags)


 This is the function to RSA decrypt or encrypt the provided data and load back to memory.  More...


 


u32 XSecure_AesOperation (u32 AddrHigh, u32 AddrLow)


 This function checks for flags field of the XSecure_AesParams struct and resolves weather the request is encryption or decryption.  More...


 


u32 XSecure_DataAuth (u8 *Signature, XSecure_RsaKey *KeyInst, u8 *Hash)


 This function performs authentication of data by encrypting the signature with provided key and compares with hash of the data and returns success or failure.  More...


 


u32 XSecure_PartitionAuthentication (XCsuDma *CsuDmaInstPtr, u8 *Data, u32 Size, u8 *AuthCertPtr)


 This function performs authentication of a partition of an image.  More...


 


u32 XSecure_MemCopy (void *DestPtr, void *SrcPtr, u32 Size)


 This function copies the data from specified source to destination using CSU DMA.  More...


 


u32 XSecure_VerifySpk (u8 *AcPtr, u32 EfuseRsaenable)


 This function verifies SPK by authenticating SPK with PPK, also checks either SPK is revoked or not.if it is not boot header authentication.  More...


 


u32 XSecure_AuthenticationHeaders (u8 *StartAddr, XSecure_ImageInfo *ImageInfo)


 This function authenticates the single partition image's boot header and image header, also copies all the required details to the ImageInfo pointer.  More...


 


u32 XSecure_SecureImage (u32 AddrHigh, u32 AddrLow, u32 KupAddrHigh, u32 KupAddrLow, XSecure_DataAddr *Addr)


 This function process the secure image of single partition created by bootgen.  More...


 


u32 XSecure_IsRsaEnabled (void)


 This function tells whether RSA authentication is enabled or not.  More...


 


u32 XSecure_IsEncOnlyEnabled (void)


 This function tells whether encrypt only is enabled or not.  More...


 


u32 XSecure_PpkVerify (XCsuDma *CsuDmaInstPtr, u8 *AuthCert)


 This function verifies the PPK hash with PPK programmed on efuse.  More...


 


u32 XSecure_SpkAuthentication (XCsuDma *CsuDmaInstPtr, u8 *AuthCert, u8 *Ppk)


 This function authenticates SPK with provided PPK or PPK from authentication certificate.  More...


 


u32 XSecure_SpkRevokeCheck (u8 *AuthCert)


 This function checks whether SPK is been revoked or not.  More...


 




Function Documentation






      

        

          u32 XSecure_AesOperation 
          (
          u32 
          AddrHigh, 
        

        

          
          
          u32 
          AddrLow 
        

        

          
          )
          
        

      





This function checks for flags field of the XSecure_AesParams struct and resolves weather the request is encryption or decryption. 


Parameters

  

    
AddrHighHigher 32 bit address of the XSecure_AesParams structure. 

    
AddrLowLower 32 bit address of the XSecure_AesParams structure.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure 
    • 






References XSECURE_AES_KUP_KEY, XSECURE_DEC, XSECURE_DEC_WRONG_KEY_SOURCE, XSECURE_ENC, XSECURE_INVALID_FLAG, XSECURE_SIZE_ERR, and XSECURE_WORD_LEN.











      

        

          u32 XSecure_AuthenticationHeaders 
          (
          u8 * 
          StartAddr, 
        

        

          
          
          XSecure_ImageInfo * 
          ImageInfo 
        

        

          
          )
          
        

      





This function authenticates the single partition image's boot header and image header, also copies all the required details to the ImageInfo pointer. 


Parameters

  

    
StartAddrPointer to the single partition image. 

    
ImageInfoPointer to XSecure_ImageInfo structure.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure
    • 





    

  • XSECURE_AUTH_NOT_ENABLED - represents image is not authenticated.
    • 



Note
Copies the header and authentication certificate to internal buffer. 



References XSecure_PartitionHeader::NextPartitionOffset, XSECURE_AC_IMAGE_HDR_OFFSET, XSECURE_ARRAY_LENGTH, XSECURE_AUTH_CERT_MIN_SIZE, XSECURE_AUTH_ISCOMPULSORY, XSECURE_AUTH_NOT_ENABLED, XSECURE_BOOT_HDR_MAX_SIZE, XSECURE_BUFFER_SIZE, XSECURE_DEC_WRONG_KEY_SOURCE, XSECURE_ENC_ISCOMPULSORY, XSECURE_IMAGE_HDR_OFFSET, XSECURE_IMAGE_HEADER_SIZE_ERR, XSECURE_IMAGE_SYNC_WORD_OFFSET, XSECURE_IMAGE_WITH_MUL_PARTITIONS, XSECURE_IMG_HDR_FAIL, XSECURE_INVALID_IMAGE_ERROR, XSecure_IsEncOnlyEnabled(), XSecure_IsRsaEnabled(), XSECURE_IV_LEN, XSECURE_IV_OFFSET, XSECURE_KEY_SOURCE_OFFSET, XSECURE_KEY_SRC_BBRAM, XSECURE_KEY_SRC_BLACK_BH, XSECURE_KEY_SRC_GREY_BH, XSecure_MemCopy(), XSecure_PartitionAuthentication(), XSECURE_PH_ATTR_ENC_ENABLE, XSECURE_PH_IV_MASK, XSECURE_PH_OFFSET, XSECURE_PH_TABLE_OFFSET, and XSECURE_WORD_LEN.



Referenced by XSecure_SecureImage().











      

        

          u32 XSecure_CsuDmaInit 
          (
          void 
          )
          
        

      





This function is used to initialize the DMA driver. 


Returns
returns the error code on any error returns XST_SUCCESS on success 



References XSECURE_CSUDMA_DEVICEID, and XSECURE_ERROR_CSUDMA_INIT_FAIL.



Referenced by Xsecure_GetCsuDma(), XSecure_SecureImage(), and XSecure_Sha3Hash().











      

        

          u32 XSecure_DataAuth 
          (
          u8 * 
          Signature, 
        

        

          
          
          XSecure_RsaKey * 
          KeyInst, 
        

        

          
          
          u8 * 
          Hash 
        

        

          
          )
          
        

      





This function performs authentication of data by encrypting the signature with provided key and compares with hash of the data and returns success or failure. 


Parameters

  

    
SignaturePointer to the RSA signature of the data 

    
KeyInstPointer to XSecure_RsaKey structure. 

    
HashPointer to the hash of the data to be authenticated.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure 
    • 






References XSecure_RsaKey::Exponent, XSecure_RsaKey::Exponentiation, XSecure_RsaKey::Modulus, XSECURE_AUTH_FAILURE, XSECURE_HASH_TYPE_SHA3, XSECURE_MOD_LEN, XSECURE_RSA_ENCRYPT_ERR, XSECURE_RSA_INIT_ERR, XSecure_RsaInitialize(), XSecure_RsaPublicEncrypt(), XSecure_RsaSignVerification(), and XSECURE_VERIFY_ERR.











      

        

          XCsuDma* Xsecure_GetCsuDma 
          (
          void 
          )
          
        

      





This function is used to initialize CsuDma and return CsuDma pointer. 


Returns
returns reference to a XCsuDma driver instance 



References XSecure_CsuDmaInit().











      

        

          u32 XSecure_IsEncOnlyEnabled 
          (
          void 
          )
          
        

      





This function tells whether encrypt only is enabled or not. 


Returns
Returns Status
    

  • XSECURE_ENABLED if enc_only bit of efuse is programmed
    • 

  • XSECURE_NOTENABLED if enc_only bit of efuse is not programmed 
    • 






References XSECURE_EFUSE_SEC_CTRL, XSECURE_ENABLED, and XSECURE_NOTENABLED.



Referenced by XSecure_AuthenticationHeaders(), and XSecure_SecureImage().











      

        

          u32 XSecure_IsRsaEnabled 
          (
          void 
          )
          
        

      





This function tells whether RSA authentication is enabled or not. 


Returns
Returns Status
    

  • XSECURE_ENABLED if RSA bit of efuse is programmed
    • 

  • XSECURE_NOTENABLED if RSA bit of efuse is not programmed. 
    • 






References XSECURE_EFUSE_SEC_CTRL, XSECURE_ENABLED, and XSECURE_NOTENABLED.



Referenced by XSecure_AuthenticationHeaders(), and XSecure_VerifySpk().











      

        

          u32 XSecure_MemCopy 
          (
          void * 
          DestPtr, 
        

        

          
          
          void * 
          SrcPtr, 
        

        

          
          
          u32 
          Size 
        

        

          
          )
          
        

      





This function copies the data from specified source to destination using CSU DMA. 


Parameters

  

    
DestPtrPointer to the destination address. 

    
SrcPtrPointer to the source address. 

    
SizeData size to be copied.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • XST_FAILURE on failure 
    • 






Referenced by XSecure_AuthenticationHeaders(), and XSecure_SecureImage().











      

        

          u32 XSecure_PartitionAuthentication 
          (
          XCsuDma * 
          CsuDmaInstPtr, 
        

        

          
          
          u8 * 
          Data, 
        

        

          
          
          u32 
          Size, 
        

        

          
          
          u8 * 
          AuthCertPtr 
        

        

          
          )
          
        

      





This function performs authentication of a partition of an image. 


Parameters

  

    
CsuDmaInstPtrPointer to the CSU DMA instance. 

    
DataPointer to partition to be authenticated. 

    
SizeRepresents the size of the partition. 

    
AuthCertPtrPointer to authentication certificate of the partition.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure 
    • 






References XSECURE_AUTH_CERT_PARTSIG_OFFSET, and XSECURE_AUTH_FAILURE.



Referenced by XSecure_AuthenticationHeaders(), and XSecure_SecureImage().











      

        

          u32 XSecure_PpkVerify 
          (
          XCsuDma * 
          CsuDmaInstPtr, 
        

        

          
          
          u8 * 
          AuthCert 
        

        

          
          )
          
        

      





This function verifies the PPK hash with PPK programmed on efuse. 


Parameters

  

    
CsuDmaInstPtrPointer to CSU DMA instance. 

    
AuthCertPointer to authentication certificate.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on successful verification.
    • 

  • Error code on failure. 
    • 






References XSECURE_AC_PPK_OFFSET, XSECURE_AH_ATTR_PPK_SEL_MASK, XSECURE_AH_ATTR_PPK_SEL_SHIFT, XSECURE_EFUSE_PPK0, XSECURE_EFUSE_PPK1, XSECURE_EFUSE_SEC_CTRL, XSECURE_HASH_TYPE_SHA3, XSECURE_KEY_SIZE, XSECURE_PPK_ERR, XSECURE_REVOKE_ERR, XSECURE_SEL_ERR, XSECURE_SHA3_INIT_FAIL, XSECURE_SHA3_PADSELECT_ERR, XSecure_Sha3Digest(), XSecure_Sha3Initialize(), XSecure_Sha3PadSelection(), XSECURE_VERIFY_ERR, and XSECURE_WORD_LEN.











      

        

          u32 XSecure_RsaCore 
          (
          u32 
          SrcAddrHigh, 
        

        

          
          
          u32 
          SrcAddrLow, 
        

        

          
          
          u32 
          SrcSize, 
        

        

          
          
          u32 
          Flags 
        

        

          
          )
          
        

      





This is the function to RSA decrypt or encrypt the provided data and load back to memory. 


Parameters

  

    
SrcAddrHighHigher 32-bit Linear memory space from where CSUDMA will read the data 

    
SrcAddrLowLower 32-bit Linear memory space from where CSUDMA will read the data 

    
SrcSizeNumber of bytes to be encrypted or decrypted. 

    
Flags,:BIT(0) - Encryption/Decryption 0 - Rsa Private key Decryption 1 - Rsa Public key Encryption

  

  




Returns
Returns Status XST_SUCCESS on success and error code on failure.


Note
Data to be encrypted/Decrypted + Modulus + Exponent Modulus and Data should always be key size Exponent : private key's exponent is key size while decrypting the signature and 32 bit for public key for encrypting the signature In this API we are not taking exponentiation value. 



References XSECURE_DEC, XSECURE_RSA_CORE_OPERATION, XSecure_RsaInitialize(), XSecure_RsaPrivateDecrypt(), and XSecure_RsaPublicEncrypt().











      

        

          u32 XSecure_SecureImage 
          (
          u32 
          AddrHigh, 
        

        

          
          
          u32 
          AddrLow, 
        

        

          
          
          u32 
          KupAddrHigh, 
        

        

          
          
          u32 
          KupAddrLow, 
        

        

          
          
          XSecure_DataAddr * 
          Addr 
        

        

          
          )
          
        

      





This function process the secure image of single partition created by bootgen. 


Parameters

  

    
AddrHighHigher 32-bit linear memory space of single partition non-bitstream image. 

    
AddrLowLower 32-bit linear memory space of single partition non-bitstream image. 

    
KupAddrHighHigher 32-bit linear memory space of KUP key. 

    
KupAddrLowLigher 32-bit linear memory space of KUP key. 

    
AddrLocation of the secure image loaded after validation.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure 
    • 






References XSECURE_AUTH_CERT_MIN_SIZE, XSECURE_AUTH_NOT_ENABLED, XSecure_AuthenticationHeaders(), XSECURE_BUFFER_SIZE, XSecure_CsuDmaInit(), XSECURE_DEC_WRONG_KEY_SOURCE, XSECURE_ENC_ISCOMPULSORY, XSECURE_ERROR_CSUDMA_INIT_FAIL, XSECURE_HDR_NOAUTH_PART_AUTH, XSecure_IsEncOnlyEnabled(), XSECURE_ISNOT_SECURE_IMAGE, XSECURE_IV_LEN, XSECURE_IV_OFFSET, XSECURE_KEY_SOURCE_OFFSET, XSECURE_KEY_SRC_BBRAM, XSECURE_KEY_SRC_BLACK_BH, XSECURE_KEY_SRC_GREY_BH, XSECURE_KEY_SRC_KUP, XSecure_MemCopy(), XSECURE_PARTITION_FAIL, XSecure_PartitionAuthentication(), XSECURE_PH_ATTR_AUTH_ENABLE, XSECURE_PH_ATTR_ENC_ENABLE, XSECURE_PH_IV_MASK, XSECURE_PH_TABLE_OFFSET, XSECURE_PPK_SIZE, XSecure_VerifySpk(), XSECURE_WORD_LEN, and XSECURE_WORD_SHIFT.











      

        

          u32 XSecure_Sha3Hash 
          (
          u32 
          SrcAddrHigh, 
        

        

          
          
          u32 
          SrcAddrLow, 
        

        

          
          
          u32 
          SrcSize, 
        

        

          
          
          u32 
          Flags 
        

        

          
          )
          
        

      





This function access the xilsecure SHA3 hardware based on the flags provided to calculate the SHA3 hash. 


Parameters

  

    
SrcAddrHighHigher 32-bit of the input or output address. 

    
SrcAddrLowLower 32-bit of the input or output address. 

    
SrcSizeSize of the data on which hash should be calculated. 

    
Flags,:inputs for the operation requested BIT(0) - for initializing csudma driver and SHA3, (Here address and size inputs can be NULL) BIT(1) - To call Sha3_Update API which can be called multiple times when data is not contiguous. BIT(2) - to get final hash of the whole updated data. Hash will be overwritten at provided address with 48 bytes.

  

  




Returns
Returns Status XST_SUCCESS on success and error code on failure. 



References XSecure_CsuDmaInit(), XSECURE_ERROR_CSUDMA_INIT_FAIL, XSECURE_INVALID_FLAG, XSECURE_SHA3_FINAL, XSECURE_SHA3_INIT, XSECURE_SHA3_INIT_FAIL, XSECURE_SHA3_MASK, XSECURE_SHA3_UPDATE_FAIL, XSecure_Sha3Finish(), XSECURE_SHA3HASH_UPDATE, XSecure_Sha3Initialize(), XSecure_Sha3Start(), and XSecure_Sha3Update().



Referenced by XSecure_HmacFinal(), and XSecure_Sha3Kat().











      

        

          u32 XSecure_SpkAuthentication 
          (
          XCsuDma * 
          CsuDmaInstPtr, 
        

        

          
          
          u8 * 
          AuthCert, 
        

        

          
          
          u8 * 
          Ppk 
        

        

          
          )
          
        

      





This function authenticates SPK with provided PPK or PPK from authentication certificate. 


Parameters

  

    
CsuDmaInstPtrPointer to CSU DMA instance. 

    
AuthCertPointer to authentication certificate. 

    
PpkPointer to the PPK key.
    

  • If NULL uses PPK from provided authentication certificate.
    • 




  

  




Returns
Returns Status
    

  • XST_SUCCESS on successful verification.
    • 

  • Error code on failure. 
    • 






References XSECURE_AH_ATTR_SPK_ID_FUSE_SEL_MASK, XSECURE_AH_ATTR_SPKID_FUSESEL_SHIFT, XSECURE_AUTH_HEADER_SIZE, XSECURE_HASH_TYPE_SHA3, XSECURE_INVALID_EFUSE_SELECT, XSECURE_PPK_MOD_EXT_SIZE, XSECURE_PPK_MOD_SIZE, XSECURE_PPK_SIZE, XSECURE_RSA_AC_ALIGN, XSECURE_RSA_ENCRYPT_ERR, XSECURE_RSA_INIT_ERR, XSecure_RsaInitialize(), XSecure_RsaPublicEncrypt(), XSecure_RsaSignVerification(), XSECURE_SHA3_INIT_FAIL, XSecure_Sha3Finish(), XSecure_Sha3Initialize(), XSecure_Sha3PadSelection(), XSecure_Sha3Start(), XSecure_Sha3Update(), XSECURE_SPK_ERR, XSECURE_SPK_SIG_SIZE, XSECURE_SPK_SIZE, XSECURE_SPKID_EFUSE, XSECURE_USER_EFUSE, and XSECURE_VERIFY_ERR.



Referenced by XSecure_VerifySpk().











      

        

          u32 XSecure_SpkRevokeCheck 
          (
          u8 * 
          AuthCert)
          
        

      





This function checks whether SPK is been revoked or not. 


Parameters

  

    
AuthCertPointer to authentication certificate.

  

  




Returns
Returns Status
    

  • XST_SUCCESS on successful verification.
    • 

  • Error code on failure. 
    • 






References XSECURE_AC_SPKID_OFFSET, XSECURE_AH_ATTR_SPK_ID_FUSE_SEL_MASK, XSECURE_AH_ATTR_SPKID_FUSESEL_SHIFT, XSECURE_EFUSE_SPKID, XSECURE_INVALID_EFUSE_SELECT, XSECURE_OUT_OF_RANGE_USER_EFUSE_ERROR, XSECURE_REVOKE_ERR, XSECURE_SPK_ERR, XSECURE_SPKID_EFUSE, XSECURE_USER_EFUSE, XSECURE_USER_EFUSE_MAX_VALUE, XSECURE_USER_EFUSE_MIN_VALUE, XSECURE_USER_EFUSE_START_ADDR, XSECURE_WORD_LEN, and XSECURE_WORD_SHIFT.



Referenced by XSecure_VerifySpk().











      

        

          u32 XSecure_VerifySpk 
          (
          u8 * 
          AcPtr, 
        

        

          
          
          u32 
          EfuseRsaenable 
        

        

          
          )
          
        

      





This function verifies SPK by authenticating SPK with PPK, also checks either SPK is revoked or not.if it is not boot header authentication. 


Parameters

  

    
AcPtrPointer to the authentication certificate. 

    
EfuseRsaenableInput variable which holds efuse RSA authentication or boot header authentication. 0 - Boot header authentication 1 - RSA authentication

  

  




Returns
Returns Status
    

  • XST_SUCCESS on success
    • 

  • Error code on failure 
    • 






References XSecure_IsRsaEnabled(), XSecure_SpkAuthentication(), and XSecure_SpkRevokeCheck().



Referenced by XSecure_SecureImage().