xilsecure Library

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_Sha3PadSelectionThis 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_RsaPublicEncryptThis function handles the RSA signature encryption with public key components provide at XSecure_RsaInitialize() API

    Decryption Functions

    XSecure_RsaDecrypt

    Decrypts the input data

    XSecure_RsaPrivateDecryptThis 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