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

Table of content