| Size | Name | Description | MACRO define |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| 32 | USER\_{0:7} | 256 user defined eFUSEs:**Note:** In the **input.h**file (see text), write data in the XSK\_EFUSEPS\_USER{0:7}\_FUSES macro and execute the write by setting the XSK\_EFUSEPS\_USER{0:7}\_FUSE macro = True. | USER{0:7}\_FUSE |
| 1 | USER\_WRLK | 8 user-defined eFUSE locks.USER\_WRLK columns:0: Locks USER\_0,1: Locks USER\_1,...7: Locks USER\_7,**Note:** Each eFUSE permanently locks the entire corresponding user-defined USER\_{0:7} eFUSE row so it cannot be changed. | USER\_WRLK\_{0:7} |
| 1 | LBIST\_EN | Enables logic BIST to run during boot. | LBIST\_EN |
| 3 | LPD\_SC | Enables zeroization of registers in low power domain (LBD) during boot.**Note:** Any of the eFUSE programmed will perform zeroization. Xilinx recommends programming all of them. | LPD\_SC\_EN |
| 3 | FPD\_SC | Enables zeroization of registers in full power domain (FBD) during boot.**Note:** MGTs must be powered to perform zeroization of the FPD.**Note:** Any of the eFUSE programmed will perform zeroization. Xilinx recommends programming all of them. | FPD\_SC\_EN |
| 3 | PBR\_BOOT\_ERROR | When programmed, boot is halted on any PMU error. | PBR\_BOOT\_ERR |
| 32 | CHASH | PUF helper data（参考：2.2.1 PUF Helper Data） | N/A - handled by PUF registration software directly. |
| 24 | AUX | PUF helper data: ECC vector | N/A - handled by PUF registration software directly. |
| 1 | SYN\_INVLD | Invalidates PUF helper data stored in eFUSEs. | XSK\_PUF\_SYN\_INVALID |
| 1 | SYN\_LOCK | Locks PUF helper data from future programming. | XSK\_PUF\_SYN\_WRLK |
| 1 | REG\_DIS | Disables PUF registration. | XSK\_PUF\_REGISTER\_DISABLE |
| 1 | AES\_RD | Disables the AES key CRC integrity check for eFUSE key storage. | AES\_RD\_LOCK |
| 1 | AES\_WR | Locks AES key from future programming. | AES\_WR\_LOCK |
| 1 | ENC\_ONLY[^(1)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_29338_1_IMPORTANT)[^(2)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_36827_2_When_the_ENC) | When programmed, all partitions are required to be encrypted. Xilinx recommends using this only if security is required and the hardware root of trust (RSA\_EN) is not used. | ENC\_ONLY |
| 1 | BBRAM\_DIS | Disables the use of the AES key stored in BBRAM. | BBRAM\_DISABLE |
| 1 | ERR\_DIS | Prohibits error messages from being read via JTAG (ERROR\_STATUS register).**Note:** The error is still readable from inside the device. | ERR\_DISABLE |
| 1 | JTAG\_DIS[^(1)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_29338_1_IMPORTANT) | Disables JTAG. IDCODE and BYPASS are the only allowed commands. | JTAG\_DISABLE |
| 1 | DFT\_DIS[^(1)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_29338_1_IMPORTANT) | Disables design for test (DFT) boot mode. | DFT\_DISABLE |
| 3 | PROG\_GATE | When programmed, these fuses prohibit the PROG\_GATE feature from being engaged. If any of these are programmed, the PL is always reset when the PS is reset.**Note:** Only one eFUSE needs to be programed to prohibit the PROG\_GATE feature from being engaged. Xilinx recommends programming all three. | PROG\_GATE\_DISABLE |
| 1 | SEC\_LK | When programmed, the device does not enable BSCAN capability while in secure lockdown. | SECURE\_LOCK |
| 15 | RSA\_EN[^(1)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_29338_1_IMPORTANT)[^(2)^](https://docs.xilinx.com/r/dqE2tE0k~iMhpEDoQwXIKg/2Ubsx6RiXaJnAO2rAuCVYA?section=XREF_36827_2_When_the_ENC) | When any one of the eFUSEs is programmed, every boot must be authenticated using RSA. Xilinx recommends programming all 15 eFUSEs. | RSA\_ENABLE |
| 1 | PPK0\_WR | Primary public key write lock. When programmed, this prohibits future programming of PPK0. | PPK0\_WR\_LOCK |
| 2 | PPK0\_INVLD | When either of the eFUSEs are programmed, PPK0 is revocated. Xilinx recommends programming both eFUSEs when revocating PPK0. | PPK0\_INVLD |
| 1 | PPK1 WR | Primary public key write lock. When programmed this prohibits future programming of PPK1. | PPK1\_WR\_LOCK |
| 2 | PPK1\_INVLD | When either of the eFUSEs are programmed, PPK1 is revocated. Xilinx recommends programming both eFUSEs when revocating PPK1. | PPK1\_INVLD |
| 32 | SPK\_ID | Secondary public key ID.**Note:** Write the SPK ID bits into the XSK\_EFUSEPS\_SPK\_ID eFUSE array and set XSK\_EFUSEPS\_SPKID = True. | SPK\_ID |
| 256 | AES | User AES key**Note:** Write data in the XSK\_EFUSEPS\_AES\_KEY macro and execute the write by setting the XSK\_EFUSEPS\_WRITE\_AES\_KEYmacro = True. | AES\_KEY |
| 384 | PPK0 | User primary public key0 HASH**Note:** Write data in the XSK\_EFUSEPS\_PPK0\_HASH macro. To program 256 bits, use the LSBs and set XSK\_EFUSEPS\_PPK0\_IS\_SHA3 = False. To program 384 bits, set XSK\_EFUSEPS\_PPK0\_IS\_SHA3 = True. Execute the write by setting the XSK\_EFUSEPS\_WRITE\_PPK0\_HASH macro = True. | PPK0\_HASH |
| 384 | PPK1 | User primary public key1 HASH**Note:** Write data in the XSK\_EFUSEPS\_PPK1\_HASH macro. To program 256 bits, use the LSBs and set XSK\_EFUSEPS\_PPK1\_IS\_SHA3 = False. To program 384 bits, set XSK\_EFUSEPS\_PPK1\_IS\_SHA3 = True. Execute the write by setting the XSK\_EFUSEPS\_WRITE\_PPK1\_HASH macro = True. | PPK1\_HASH |
| N/A | PUF\_HD | Syndrome of PUF HD. These eFUSEs are programmed using Xilinx provided software, Xilskey | N/A - handled by PUF registration software directly. |
这个表，很关键，eFUSE会影响到ZYNQ处理器的工作状态、安全信息，配置错了之后，Xilinx已经声明不接受要求eFUSE复原的返厂件。在操作这些位的时候，尤其是Provisioning的时候，会影响其他非安全的测试。
> **IMPORTANT**: THESE INSTRUCTIONS MODIFY THE EFUSES ON THE ZCU102 DEVELOPMENT BOARD AND MAY LIMIT FUTURE USE OF THE DEVELOPMENT BOARD FOR NON-SECURE TESTING AND DEBUGGING!
### 2.2 PUF
#### 2.2.1 PUF Helper Data
PUF使用大约4Kb的辅助数据来帮助PUF在正确的寿命、规定的工作温度和电压范围内重新创建原始KEK值。辅助数据由Syndrome值、Aux值和Chash值组成（请参见表：PUF辅助数据）。助手数据可以存储在eFUSE或引导映像中。
| PUF Helper Data Field | Size (Bits) | Description |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Syndrome | 4060 | 鉴于环形振荡器在温度、电压和时间上的微小变化，这些比特有助于PUF恢复正确的PUF特征 |
| Aux | 24 | 这是一个汉明码，允许PUF对PUF签名执行某种程度的纠错。 |
| Chash | 32 | •如果CHASH未被编写，则只要使用（bh\_auth或rsa\_en），就可以使用boot-header black key。
•如果对CHASH进行了编写，则只要（使用bh\_auth或rsa\_en）且eFUSE的Syndrome数据未失效，就可以使用eFUSE的black key。
•如果对CHASH进行了编写，则只要使用（bh\_auth或rsa\_en）且efuse的Syndrome数据无效，就可以使用boot-header black key。
|
helper data 简单的说是帮助生成PUF key时候所需要的材料（Syndrome，Aux）。如图所示，生成PUF key及调用AES引擎的过程。PUF原数据复原的算法，可以参考：\[Helper Data Algorithms for PUF-Based Key Generation: Overview and Analysis]\() （有点专业和复杂。。） 特征值（Syndrome）和Aux（汉明距）是算法需要的输入。汉明距是实现比特纠错码的一种手段，可以参考，文献：\[ ]。
生成puf helper data的过程参考：
{% embed url="" %}
#### 2.2.2 PUF operations
只有CSU可以访问PUF，所以PUF的初始化包括黑密钥的产生，必然是在CSU阶段完成。PUF暴露出以下接口供CSU操作：
| Command | Description |
| --------------- | ------------------------------- |
| Registration | 产生一个新的KEK并且关联helper data |
| Re-registration | 产生一个新的KEK并且关联**新的**helper data |
| Reuse | 使用已经存在的KEK进行加解密，并且关联helper data |
当一个设备上电的时候，CSU bootROM会检测已经校验过的boot header，确认以下信息：
* 是否使用了PUF；
* 加密的密钥存储在哪里？（eFUSE 或者 boot image）
* helper data存储在哪里？（eFUSE 或者 boot image）
接着CSU初始化PUF，并且加载helper data，最后产生KEK，`这个过程叫做regeneration`。一旦KEK产生成功，CSU bootROM使用它来解密剩下boot image需要的key。
#### 2.2.3 PUF Control eFUSEs
eFUSE也给PUF留了一些功能接口：
| Command | Description |
| ------------ | ------------------------- |
| REG\_DIS | 屏蔽PUF的注册 |
| SYN\_INVALID | 使存在eFUSE上的helper data无效 |
| SYN\_LOCK | 屏蔽修改eFUSE上的helper data的功能 |
Xilinx也做了PUF的强度分析，包含加密，安全强度KEK，过温过压的测试的数据报告，需要联系FAE或者销3. Example售才可以拿到这个报告。
### 3.1 Provisioning
Provisioning是所有安全机制的基础。其目的是把根凭证写入eFUSE或者其他存储密钥的敏感介质。包含RSA的根密钥，也包含GCM的Key。
在ZYNQ中我们需要Provisioning的内容：
* PPK HASH （主引导Primary Public Key Hash）
* GCM-AES Key （用于image解密）
* PSK ID (写入key的id信息，作为PUF解密时候比对，参考'防重放攻击'一节)
在调试阶段为了不伤害eFUSE。对于PPK HASH，zynq提供了bh\_boot模式，即可以绕过eFUSE的PPK HASH检测，直接使用AC中的hash值。
同样，为了不伤害eFUSE。对于GCM-AES key，我们可以不使用eFUSE，而把Key烧录到BBRAM中。
**在调试阶段，推荐配置为**：
* **ppk hash**，对于验证，使用bh\_boot（不需要包含到Provisioning过程中）
* **gcm aes key**，对于验证，使用bbram （需要包含到Provisioning过程中）
* id
* **ID**，对于验证，在bootgen阶段选择`spk_id = 0`，不需要包含到Provisioning中。
**在产品阶段，必须配置为**： ppk hash 和 gcm aes key都需要在eFUSE中。
我们可以把完整的Provisioning过程总结为：
* 手动产生两对RSA密钥，产生gcm-aes-key；
* 使能PUF eFUSE的配置；
* 使用写入寄存器的方法写入eFUSE。
**可以通过JTAG烧录eFUSE（这种方法数据操作互动型，具备一定的危险性，eFUSE烧录不可撤销），因此建议使用配置寄存器的方法烧录eFUSE**。
#### 3.1.1 Gen Key
密钥生成主要是需要以下材料：
* AES Key Generation
* 输出nky文件（包含key和iv）
* RSA Asymmetric Key Generation
* 输出1：psk0.pem
* 输出2：ssk0.pem
* Generate SHA3 of Public RSA Asymmetric Key
* 输出是：sha3.txt
#### 3.1.2 PUF eFUSE config
PUF eFUSE的配置需要使用Vitis建立AP的工程，使用ZYNQ上面的AP来完成PUF的配置。非常重要的提示：**这一步会修改eFUSE上面的内容**！
需要配置的项目是：
* XSK\_PUF\_INFO\_ON\_UART
* XSK\_PUF\_PROGRAM\_EFUSE
* XSK\_PUF\_PROGRAM\_SECUREBITS
* XSK\_PUF\_SYN\_WRLK
* XSK\_PUF\_AES\_KEY
* XSK\_PUF\_IV
`XSK_PUF_AES_KEY`是用户指定的，而且这个`XSK_PUF_IV`和AES Key Generation中的IV不相关。这个IV是用于PUF KEK的red key加密。
#### 3.1.3 RSA eFUSE config
这一步是配置RSA相关的信息到eFUSE上面，非常重要的提示：**这一步会修改eFUSE上面的内容**！
* XSK\_EFUSEPS\_RSA\_ENABLE
* XSK\_EFUSEPS\_PPK0\_WR\_LOCK
* XSK\_EFUSEPS\_WRITE\_PPK0\_HASH
* XSK\_EFUSEPS\_PPK0\_HASH
#### 3.1.4 RSA Key Revocation Support
RSA密钥提供了撤销一个分区的**secondary**密钥（SPK）的能力，而无需撤销所有分区的密钥。这是通过使用新的BIF参数`spk_select`利用`USER_FUSE0`到`USER_FUSE7` 位域实现（如果这些位域没有用于表示其他信息，只用于表示密钥的id，最多可以撤销256个SPK，如图所示）。
下图表示ZYNQ使用SPK\_ID进行SPK revocation的过程。
以下是使用辅助密钥创建经过身份验证的映像的步骤：
* 使用bootgen生成RSA密钥对。
* 我们在步骤1中生成了一个辅助密钥（SSK）。如果需要更多的SSK，请重复步骤1以创建SSK密钥。
* 使用bootgen和下面的bif文件模板生成经过验证的引导映像。下面的模板假设bootloader和u-boot使用\[sskfile]标记提供的密钥进行了验证，并且该密钥根据eFUSE中存储的SPK\_ID进行了验证；PMU FW和ATF images使用sskfile提供的密钥进行验证，并根据存储在USER\_eFUSE中的SPK\_ID bitmap 验证该密钥。(确保在生成映像时使用命令行参数–efuseppkbits\命令bootgen生成PPK哈希。)
* 使能RSA认证通过设定 “RSA\_EN” 在eFUSE上. 参考 [Programming BBRAM and eFUSEs Application Note (XAPP1319)](https://www.xilinx.com/support/documentation/application_notes/xapp1319-zynq-usp-prog-nvm.pdf)
* 写入在第三步创建的PPK的SHA-3 hash 到eFUSE的PPK0 hash位域。
确保在生成image时使用命令行参数–efuseppkbits\命令bootgen生成PPK hash。
**模板示例**：\
image header和FSBL使用不同的SSK进行身份验证（分别为ssk1.pem和ssk2.pem），用以下bif文件：
```
the_ROM_image: {
[auth_params]ppk_select = 0
[pskfile]psk.pem
[sskfile]ssk1.pem
[bootloader, authentication = rsa, spk_select = spk-efuse, spk_id = x00000001, sskfile = ssk2.pem]zynqmp_fsbl.elf
[destination_cpu =a53-0, authentication = rsa, spk_select = user-efuse,spk_id = 0x1, sskfile = ssk3.pem]Application1.elf
[destination_cpu =a53-0, authentication = rsa, spk_select = spk-efuse, spk_id = 0x00000001, sskfile = ssk4.pem]Application2.elf
}
```
相同的SSK将作用于image header和FSBL（ssk2.pem）：
```
the_ROM_image: {
[auth_params]ppk_select = 0 [pskfile]psk.pem
[bootloader, authentication = rsa, spk_select = spk-efuse, spk_id = 0x00000001, sskfile = ssk2.pem]zynqmp_fsbl.elf
[destination_cpu =a53-0, authentication = rsa, spk_select = user-efuse, spk_id = 1, sskfile = ssk3.pem]Application1.elf
[destination_cpu =a53-0, authentication = rsa, spk_select = spk-efuse, spk_id = 0x00000001, sskfile = ssk4.pem]Application2.elf
}
```
注意：
* `spk_select = spk-efuse` 表示 指定的分区将会使用`spk_id`eFUSE位域。
* `spk_select = user-efuse` 指示 指定的分区将会使用user eFUSE位域，而CSU ROM总是使用`spk_id`eFUSE位域。
### 3.2 PUF Enc/Dec demo
完成上面PUF的注册，我们假定eFUSE和PUF的配置已经OK了，现在我们需要编写APU(Application Processor Unit)的固件（bare-mental程序），来使用PUF的加密和解密功能。
该固件是在xilinx的vitis ide上完成的，vitis已经集成了ZYNQ所用的bsp驱动包，并提供了相应的操作key、加密解密、访问寄存器、控制外设等接口。
打开vitis ide创建工程：
选择bsp包：
选择processor为APU (Application Processor Unit)：CortexA53\_0：
导入bare-mental的源码（下面就是源码核心）：
源码进行编译：
最后生成`BOOT.BIN`文件，将其复制到SD卡的boot分区。启动即可运行。
#### 3.2.1 加密
对于一个PUF加密过程的程序：
```c
void puf_encrypt(u8 *Iv, u8 *Dst, u8 *Src, u32 Size) {
XCsuDma_Config *Config;
XCsuDma_Configure ConfigurValues = {0};
/* Configure PUF configuration 0 and configure the shutter. */
XilSKey_WriteReg(XSK_ZYNQMP_CSU_BASEADDR, XSK_ZYNQMP_CSU_PUF_CFG0,
XSK_ZYNQMP_CSU_PUF_CFG0_DEFAULT);
XilSKey_WriteReg(XSK_ZYNQMP_CSU_BASEADDR, XSK_ZYNQMP_CSU_PUF_SHUT,
XSK_ZYNQMP_CSU_PUF_SHUT_DEFAULT);
// Spin up the PUF and connect the key to the AES engine
XilSKey_WriteReg(XSK_ZYNQMP_CSU_BASEADDR, XSK_ZYNQMP_CSU_PUF_CMD,
XSK_ZYNQMP_PUF_REGENERATION);
/* Wait for the PUF regeneration to complete. */
usleep(PUF_REGEN_TIME_US);
/* Initialize & configure the DMA */
Config = XCsuDma_LookupConfig(XSK_CSUDMA_DEVICE_ID);
XCsuDma_CfgInitialize(&CsuDma, Config, Config->BaseAddress);
/* Initialize AES engine */
XSecure_AesInitialize(&AesInstance, &CsuDma, XSK_PUF_DEVICE_KEY, (u32 *) Iv, NULL);
/* Set the data endianess for IV */
XCsuDma_GetConfig(&CsuDma, XCSUDMA_SRC_CHANNEL,
&ConfigurValues);
ConfigurValues.EndianType = 1U;
XCsuDma_SetConfig(&CsuDma, XCSUDMA_SRC_CHANNEL,
&ConfigurValues);
/* Enable CSU DMA Dst channel for byte swapping.*/
XCsuDma_GetConfig(&CsuDma, XCSUDMA_DST_CHANNEL,
&ConfigurValues);
ConfigurValues.EndianType = 1U;
XCsuDma_SetConfig(&CsuDma, XCSUDMA_DST_CHANNEL,
&ConfigurValues);
/* Request to encrypt the AES key using PUF Key */
XSecure_AesEncryptData(&AesInstance, (u8 *) Dst, (u8 *) Src, Size);
/* Clear the PUF key. */
XilSKey_WriteReg(XSK_ZYNQMP_CSU_BASEADDR, XSK_ZYNQMP_CSU_PUF_CMD,
XSK_ZYNQMP_PUF_RESET);
}
```
#### 3.2.2 解密
## Ref
1. [External Secure Storage Using the PUF Application Note](https://docs.xilinx.com/r/en-US/xapp1333-external-storage-puf/External-Secure-Storage-Using-the-PUF-Application-Note)
2. [Programming BBRAM and eFUSEs Application Note (XAPP1319)](https://docs.xilinx.com/v/u/en-US/xapp1319-zynq-usp-prog-nvm)
3. [Zynq UltraScale+ Device Technical Reference Manual (UG1085) - Security](https://docs.xilinx.com/r/en-US/ug1085-zynq-ultrascale-trm/Introduction?tocId=A~Ce_pZ6I0b4P1VxSk8qcg)
4. [secure-boot-encrypted-data-storage](https://www.timesys.com/security/secure-boot-encrypted-data-storage/)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://carloss-organization-4.gitbook.io/tech/ecus/zynq_documents/zynq-encrypt-external-files-based-on-file-system-using-puf-key.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.