The XilSecure library provides APIs to access hardened cryptography engines of Zynq® UltraScale+. MPSoC devices. More information can be found in the XilSecure Standalone Library Documentation.

Features supported

Hashing

XilSecure library provides access to SHA-3 algorithms for hashing. ZynqMP has inbuilt hardware accelerator for SHA-3/384 based hash calculation.

SHA-3

• XilSecure SHA-3 APIs in provides access to ZynqMP hardware accelerator for SHA-3/384 hash calculation
• Uses NIST SHA-3 padding by default

• User can configure system to use Keccak padding.

  Initialization Functions
  XSecure_Sha3Initialize	Initializes a specific Xsecure_Sha3 instance so that it is ready to be used
  Hash functions
  XSecure_Sha3Start	Configure and start SHA3 engine
  XSecure_Sha3Update	Updates hash for new input data block
  XSecure_Sha3Finish	Sends the last data and padding when blocksize is not multiple of 104 bytes
  XSecure_Sha3Digest	Calculates the SHA-3 digest on the given input data
  XSecure_Sha3_ReadHash	Reads the SHA3 hash of the data. It can be called intermediately of updates also to read hashs.
  XSecure_Sha3PadSelection	This function provides an option to select the SHA-3 padding type (NIST / KECCAK) to be used while calculating the hash

Symmetric Key Encryption/Decryption

XilSecure library provides access to symmetric key based AES-GCM algorithms for encryption, decryption and authentication using GCM tag. ZynqMP has inbuilt hardware accelerator to accelerate AES-GCM algorithm.

AES-GCM

• XilSecure encryption APIs provides access to ZynqMP AEC-GCM cryptographic engine for encryption
• XilSecure encryption API allows to choose 256-bit AES key source among user defined key (KUP key) and device keys
• XilSecure encryption APIs also takes initialization vector (IV) as input along with AES key
• XilSecure encryption APIs allow encryption and decryption on only WORD aligned data
• XilSecure encryption algorithm appends GCM tag to encrypted data
• XilSecure decryption APIs provides access to ZynqMP AEC-GCM hardware accelerator engine for decryption

• XilSecure decryption APIs provides option to check GCM tag matching while decryption of the data. Not that GCM tag should be provided explicitly during decryption.

  Initialization Function
  XSecure_AesInitialize	Initializes AES instance
  Encryption Functions
  XSecure_AesEncryptInit	Initialize the AES engine for encryption
  XSecure_AesEncryptUpdate	Updates the AES engine with provided data for encryption
  XSecure_AesEncryptData	Encrypts the data provided by using hardware AES engine
  Decryption Functions
  XSecure_AesDecryptInit	Initializes the AES engine for decryption
  XSecure_AesDecryptUpdate	Update the AES engine for decryption with provided data
  XSecure_AesDecryptData	Decrypts the encrypted data provided for decryption
  XSecure_AesDecrypt	Handles the AES-GCM Decryption of image partition
  Control Functions
  XSecure_AesReset	Encrypts the data provided by using hardware AES engine
  XSecure_AesWaitForDone	Function waits for AES completion

Restrictions

• XilSecure supports only word aligned data and each update should not be more than 512MB
• Key rolling encryption feature is available during secure boot and not through XilSecure APIs

Asymmetric Key Encryption/Decryption

ZynqMP has inbuilt hardware accelerator to accelerate RSA algorithm. XilSecure library provides access to this hardware accelerator to run asymmetric algorithm.

RSA

• XilSecure authentication APIs supports RSA-4096 and RSA-2048 only

• XilSecure authentication APIs expect key parameters modulus, exponent and exponentiation values as an input.

  Initialization Functions
  XSecure_RsaInitialize	Initializes RSA instance
  Encryption Functions
  XSecure_RsaPublicEncrypt	This function handles the RSA signature encryption with public key components provide at XSecure_RsaInitialize() API
  Decryption Functions
  XSecure_RsaDecrypt	Decrypts the input data
  XSecure_RsaPrivateDecrypt	This function handles the RSA signature decryption with private key components provide at XSecure_RsaInitialize() API
  Sign Verification Functions
  XSecure_RsaSignVerification	Verifies the RSA decrypted data provided is matching with the provided expected hash by taking care of PKCS padding

Changelog

2016.3

• Provided SHA2 hash support, and also an example to illustrate the SHA2 hash generation

2017.1

• Xilsecure is made support for PMU
• Added comments with .nky fields for aes encryption example.
• Provided genric APIs for encryption and decryption of data.
• Support for calculation of exponential value can also be done internally while doing RSA decryption, for this user needs to pass NULL pointer.
• Modified AES APIs such that, data passed to APIs should be in little endian format

2017.2

• Added new version and modified pre-compiled binary file to support hard floating point.

2017.3

• Added RSA APIs for private key decryption.
• Added support for RSA- 2048 key size.

2017.4

• None

2018.1

• Added support for NIST SHA3 padding.
• Added API to select NIST/KECCAK SHA3 padding of choice
• Modified XSecure_AesDecrypt() API to fix Secure key and IV vulnerabilities.

2018.2

• Added support for additional AES key sizes - 512, 576, 704, 768, 992, 1024, 1152, 1408, 1536, 1984, 3072 bits.
• Fixed wrong memory zeroization issue on GCM tag failure.
• Added support of secondary public key revocation using user eFuses.
• Added compilation flag for opting secure/non-secure environment for image loading. By default it is non-secure.

2018.3

• Added input data validation for XSecure_RsaPrivateDecrypt.
• Added support to existing SHA3 library functions to accept input data which is not 4-byte/Word aligned and no restriction on data sizes.
• Added supportive APIs to encrypt/decrypt the data blobs from Linux/u-boot.
• Added support to clear user key after use.

2019.1

• Added support to clear RSA engine's key component memory after every RSA operation.
• Added support to hold AES engine in reset condition after use.
• Fixed limited memory zeroization issue on GCM tag failure.
• Added support to hold SHA3 engine in reset condition after use.
• Deprecated SHA2 support.
• Deprecated XSecure_RsaDecrypt function, replacement to this function is XSecure_RsaPublicEncrypt.
• Added IAR compiler support.
• XSecure_Sha3Finish is updated to return error condition if padding is wrongly selected.
• Fixed wrong IV length issue in xilsecure.c file.

2019.2

• Fixed MISRAC and coverity warnings.
• Optimized code in xsecure.c file

2020.1

•  Updated RSA zeroize API, RSA zeroization and verification are only done for private operations
• Optimized Sha3 data transfer for unaligned sizes and addresses
• Moved AES reset calls into library code.

• ZynqMP single parition image IV calculation is corrected