xilskey Library

Introduction

The XilSKey library provides APIs for programming and reading eFUSE bits and for programming the battery-backed RAM (BBRAM). Each SoC has different configuration of eFUSEs and BBRAM. Following list gives features with respect to each device.

Features Supported

  • Programming/reading eFUSE's AES key, RSA Hashs, User key and Control Secure bits.
  • Programming BBRAM with AES key.

Zynq-7000 Devices

  • Processing System (PS) eFUSEs holds the RSA primary key hash bits and user feature bits, which can enable or disable some Zynq-7000 processor features
  • Programmable Logic (PL) eFUSEs holds the AES key, the user key and some of the feature bits
  • PL BBRAM holds the AES key

UltraScale/UltraScale+ Devices

Supports for both mono or SSIT devices.

  • PL eFUSE holds the AES key, 32 bit and 128 bit user key, RSA hash and some of the feature bits
  • PL BBRAM holds AES key with or without DPA protection enable or obfuscated key programming

Zynq UltraScale+ MPSoC Devices

  • eFUSEs of Processing System (PS) of ZynqMP SoC holds the AES key, user data, PPK0 and PPK1 hashes, SPK_ID, some bits which can be used to enable/disable some of the features of SoC
  • BBRAM holds the AES key
  • Support of Physically Unclonable Function (PUF)
  • Supports ZU+ PL similar to Ultrascale plus devices.


Refer following documents for detailed information on BBRAM and eFUSE functionality.

    1. Programming BBRAM and eFUSEs (XAPP1319)
    2. Internal programming of BBRAM and eFUSEs (XAPP1283)
    3. Xilinx Standalone Library Documentation (UG1191)



XilSKey Library APIs

XilSKey library APIs divided into two parts – BBRAM APIs and eFUSE APIs. Following section gives glimpse of API functions of XilSKey library.

BBRAM APIs

XilSKey_ZynqMp_Bbram_Program

Writes input AES red key in BBRAM and verifies the write

XilSKey_ZynqMp_Bbram_Zeroise

Zeroize's Key stored in BBRAM

eFUSE APIs 

Processing Systems (PS) eFUSE API

XilSKey_ZynqMp_EfusePs_CheckAesKeyCrc

Performs CRC check of AES key stored in eFUSE

XilSKey_ZynqMp_EfusePs_ReadUserFuse

Reads user eFUSE from eFUSE or cache

XilSKey_ZynqMp_EfusePs_ReadPpk0Hash

Reads PPK0 hash from eFUSE or cache

XilSKey_ZynqMp_EfusePs_ReadPpk1Hash

Reads PPK1 hash from eFUSE or cache

XilSKey_ZynqMp_EfusePs_ReadSpkId

Reads SPK_ID hash from eFUSE or cache

XilSKey_ZynqMp_EfusePs_ReadDna

Reads ZynqMP SoC DNA from eFUSE

XilSKey_ZynqMp_EfusePs_ReadSecCtrlBits

Read the PS eFUSE secure control bits from eFUSE or cache

XilSKey_ZynqMp_EfusePs_Write

Program the PS eFUSE of ZynqMP

XilSKey_ZynqMp_EfusePs_WritePufHelprData

Programs the PS eFUSE's with PUF helper data

XilSKey_ZynqMp_EfusePs_ReadPufHelprData

Reads the PS eFUSE's with PUF helper data

XilSKey_ZynqMp_EfusePs_WritePufChash

Programs eFUSE's with PUF Chash value

XilSKey_ZynqMp_EfusePs_ReadPufChash

Reads eFUSE's with PUF Chash value

XilSKey_ZynqMp_EfusePs_WritePufAux

Programs eFUSE PUF Auxiliary Data

XilSKey_ZynqMp_EfusePs_ReadPufAux

Reads eFUSE PUF Auxiliary Data

Programmable Logic (PL) eFUSE API

XilSKey_EfusePl_Program

Programs PL eFUSE with input data

XilSKey_EfusePl_ReadStatus

Reads the PL eFUSE status bits and gets all Secure and Control bits

XilSKey_EfusePl_ReadKey

Verifies the input CRC matches with CRC of AES Key stored in eFUSE.

It also initializes the timer, XADC and JTAG server subsystems, if not already done so.

XilSKey_CrcCalculation

Calculates CRC value of provided key in string format

XilSkey_CrcCalculation_AesKey

Calculates CRC value of provided key in binary format

PUF APIs

XilSKey_Write_Puf_EfusePs_SecureBits

Programs the eFUSE PUF Secure Bits

XilSKey_Read_Puf_EfusePs_SecureBits

Read the PS eFUSE PUF Secure Bits from eFUSE or cache

XilSKey_Puf_Registration

Registration/Re-registration of PUF

XilSKey_Puf_RegenerationRegenerates PUF data


Changelog

2016.3

Zynq

  • Fixed Zynq eFUSE programming sequence, by programming DFT bits before eFUSE write protect bit.
  • Added margin 2 read checks for Zynq eFUSE PS and PL.

Ultrascale

  • Ultrscale eFUSE programming is handled using hardware module, Hardware module is controlled through GPIO pins, modified Ultrascale eFUSE example and input.h files to accept GPIO pin numbers from user.
  • Corrected sysmon temperature reads of sysmon to 16-bit resolution.
  • Added 128 bit user key programming.
  • Provided single bit programming for User keys 32 and 128 bit User keys.
  • Added error codes on failures.
  • BBRAM is updated to have DPA protection and count configuration.

ZynqMP

  • Modified ZynqMP PS eFUSE's single USER key programming to separate 32 bit User keys. Provided single bit programming for User Key.

2016.4

ZynqMP

  • Added support for PUF registration, programming eFUSE with syndrome data, Auxilary value and CHash value.

Zynq

  • Removed ForcePowerCycle and JtagDisable, from BBRAM Zynq PL instance as they are not actually programming any control bit. These are already exists in Zynq eFUSE PL instance.

2017.1

ZynqMP

  • On ZynqMP Added CRC check after programming whole AES key.
  • For each ZynqMP eFUSE bit programming added verification with all 3 margin reads
  • Removed temperature and voltage checks for every eFUSE bit programming for ZynqMP.
  • Added support for programming more secure control bits-Lbist,LPD/FPD SC enable.
  • Modified PROG_GATE programming from three inputs to one.

2017.2

None

2017.3

  • Provided support for programming eFUSE and BBRAM of Kintex Ultrascale plus

2017.4

None

2018.1

  • Corrected status bits of Ultrascale Plus

2018.2

  • Fixed hanging issue during program/zeroize request to ZynqMP BBRAM when programming mode is in enabled state.

2018.3

  • Fixed armcc compile errors.
  • Added support for programming eFuse from Linux via SMC calls.
  • Added support for PUF regeneration.

2019.1

  • Added IAR compiler support.
  • Deprecated PPK0/1 SHA2 hash programming support.
  • Added support to handle PUF underflow condition.
  • Added support for Microblaze devices to select GPIO based on the design.
  • Added support for SSIT devices on Microblaze.

2019.2

Zynq Ultrascale plus

  • Fixed MISRAC violations and coverity warnings and updated doxygen comments.
  • Updated doxygen comments.
  • Moved floating point calculation to compile time in ZU+ PS
  • Fixed CHASH reading from wrong location of syndrome
    data in Zynqmp
  • Corrected length of data to be read.
  • Fixed controller locking back in ZU+
  • Reporting puf_acc_error to user.
  • Added assert statements
  • Initialized Status variables to XST_FAILURE
  • Removed Tbits programming code in ZU+
  • Added sysmon override or not option under BSP settings

Ultrascale/Ultrascale plus device

  • Added support for user to add IDCODES for microblaze devices
  • Added Debug define for dummy programming for microblaze
  • Added support to access ZU+ PL efuse and BBRAM
  • Modified Microblaze SSIT devices based on CONFIG ORDER
    INDEX.

Generic

  • Aligned spaces in dependecies.props

2020.1

  • Disabled BBRAM programming mode after key write
  • Fixes coverity warnings
  • Depecrated XilSKey_Puf_Fetch_Dbg_Mode2_result functionality
  • Fixed ARMCC compilation errors
  • Removed ZynqMP efuse temperature and voltage checks for efuse reads
  • Deprecated support to read from efuse memory, if requested throws an error
  • Placed temperature and voltage checks before enabling programming

Table of Content