Creating a Zynq UltraScale+ MPSoC Device Boot Image using HSM Mode - 2022.1 English

Bootgen User Guide (UG1283)

Document ID
UG1283
Release Date
2022-04-26
Version
2022.1 English

The following figure provides a diagram of an HSM mode boot image.

Figure 1. 0 to 10 Stage Boot Process

To create a boot image using HSM mode for a Zynq® UltraScale+™ MPSoC device, it would be similar to a boot image created using a standard flow with the following BIF file. These examples, where needed, use the OpenSSL program to generate hash files.

all:
{
	[fsbl_config] bh_auth_enable
	[keysrc_encryption] bbram_red_key
	[pskfile] primary0.pem
	[sskfile] secondary0.pem
	
	[
	  bootloader,
	  destination_cpu=a53-0,
	  encryption=aes,
	  aeskeyfile=aes0.nky,
	  authentication=rsa
	] fsbl.elf

	[
	  destination_device=pl,
	  encryption=aes,
	  aeskeyfile=aes1.nky,
 	 authentication=rsa
	] system.bit

	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-3,
	  trustzone=secure
	] bl31.elf

	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-2
	] u-boot.elf
}
Note: To use pmufw_image in HSM flow, add [pmufw_image] pmufw.elf to the above bif. In similar lines, this should be added in the stage2a bif, where FSBL is encrypted. The rest of the flow remains same.

Stage 0: Generate a hash for SPK

The following is the snippet from the BIF file.

stage0:
{
	[ppkfile]primary.pub
	[spkfile]secondary.pub
}

The following is the Bootgen command:

bootgen -arch zynqmp -image stage0.bif -generate_hashes -w on -log error

Stage 1: Sign the SPK Hash (encrypt the partitions)

The following is a code snippet using OpenSSL to generate the SPK hash:

openssl rsautl -raw -sign -inkey primary0.pem -in secondary.pub.sha384 > secondary.pub.sha384.sig

The output of this command is secondary.pub.sha384.sig.

Stage 2a: Encrypt the FSBL

Encrypt the FSBL using the following snippet in the BIF file.

Stage 2a:
{
	[keysrc_encryption] bbram_red_key

	[
	  bootloader,destination_cpu=a53-0,
	  encryption=aes,
	  aeskeyfile=aes0.nky
	] fsbl.elf
}

The Bootgen command is:

bootgen -arch zynqmp -image stage2a.bif -o fsbl_e.bin -w on -log error

Stage 2b: Encrypt Bitstream

Generate the following BIF file entry:

stage2b:
{
	[
	  encryption=aes,
	  aeskeyfile=aes1.nky,
	  destination_device=pl,
	  pid=1
	] system.bit
}

The Bootgen command is:

bootgen -arch zynqmp -image stage2b.bif -o system_e.bin -w on -log error

Stage 3: Generate Boot Header Hash

Generate the boot header hash using the following BIF file:

stage3:
{
 	[fsbl_config] bh_auth_enable
 	[ppkfile] primary.pub
 	[spkfile] secondary.pub
 	[spksignature]secondary.pub.sha384.sig
 	[bootimage,authentication=rsa]fsbl_e.bin
}

The Bootgen command is:

bootgen -arch zynqmp -image stage3.bif -generate_hashes -w on -log error

Stage 4: Sign Boot Header Hash

Generate the boot header hash with the following OpenSSL command:

openssl rsautl -raw -sign -inkey secondary0.pem -in bootheader.sha384 > bootheader.sha384.sig

Stage 5: Get Partition Hashes

Get partition hashes using the following command in a BIF file:

stage5:
{		
	[ppkfile]primary.pub
	[spkfile]secondary.pub
	[spksignature]secondary.pub.sha384.sig
	[bhsignature]bootheader.sha384.sig 
	[bootimage,authentication=rsa]fsbl_e.bin
	[bootimage,authentication=rsa]system_e.bin
	
	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-3,
	  trustzone=secure
	] bl31.elf

	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-2
	] u-boot.elf
}

The Bootgen command is:

bootgen -arch zynqmp -image stage5.bif -generate_hashes -w on -log error

Multiple hashes will be generated for a bitstream partition. For more details, see Bitstream Authentication Using External Memory.

The Boot Header hash is also generated from in this stage5; which is different from the one generated in stage3, because the parameter bh_auth_enable is not used in stage5. This can be added in stage5 if needed, but does not have a significant impact because the Boot Header hash generated using stage3 is signed in stage4 and this signature will only be used in the HSM mode flow.

Stage 6: Sign Partition Hashes

Create the following files using OpenSSL:

openssl rsautl -raw -sign -inkey secondary0.pem -in fsbl.elf.0.sha384 > fsbl.elf.0.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in system.bit.0.sha384 > system.bit.0.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in system.bit.1.sha384 > system.bit.1.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in system.bit.2.sha384 > system.bit.2.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in system.bit.3.sha384 > system.bit.3.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in u-boot.elf.0.sha384 > u-boot.elf.0.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in bl31.elf.0.sha384 > bl31.elf.0.sha384.sig
openssl rsautl -raw -sign -inkey secondary0.pem -in bl31.elf.1.sha384 > bl31.elf.1.sha384.sig

Stage 7: Insert Partition Signatures into Authentication Certificate

Stage 7a: Insert the FSBL signature by adding this code to a BIF file:

Stage7a:
{
	[fsbl_config] bh_auth_enable
	[ppkfile] primary.pub
	[spkfile] secondary.pub
	[spksignature]secondary.pub.sha384.sig
	[bhsignature]bootheader.sha384.sig
	[bootimage,authentication=rsa,presign=fsbl.elf.0.sha384.sig]fsbl_e.bin
}
The Bootgen command is as follows:
bootgen -arch zynqmp -image stage7a.bif -o fsbl_e_ac.bin -efuseppkbits 
efuseppkbits.txt -nonbooting -w on -log error

Stage 7b: Insert the bitstream signature by adding the following to the BIF file:

stage7b:
{
	[ppkfile]primary.pub
	[spkfile]secondary.pub
	[spksignature]secondary.pub.sha384.sig
	[bhsignature]bootheader.sha384.sig
	[
	  bootimage,
	  authentication=rsa,
	  presign=system.bit.0.sha384.sig
	] system_e.bin
}

The Bootgen command is:

bootgen -arch zynqmp -image stage7b.bif -o system_e_ac.bin -nonbooting -w on -log error

Stage 7c: Insert the U-Boot signature by adding the following to the BIF file:

stage7c:
{
	[ppkfile] primary.pub
	[spkfile] secondary.pub
	[spksignature]secondary.pub.sha384.sig
	[bhsignature]bootheader.sha384.sig
	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-2,
	  presign=u-boot.elf.0.sha384.sig
	] u-boot.elf
}

The Bootgen command is:

bootgen -arch zynqmp -image stage7c.bif -o u-boot_ac.bin -nonbooting -w on -log error

Stage 7d: Insert the ATF signature by entering the following into a BIF file:

stage7d:
{
	[ppkfile] primary.pub
	[spkfile] secondary.pub
	[spksignature]secondary.pub.sha384.sig
	[bhsignature]bootheader.sha384.sig
	[
	  destination_cpu=a53-0,
	  authentication=rsa,
	  exception_level=el-3,
	  trustzone=secure,
	  presign=bl31.elf.0.sha384.sig
	] bl31.elf
}

The Bootgen command is:

bootgen -arch zynqmp -image stage7d.bif -o bl31_ac.bin -nonbooting -w on -log error

Stage 8: Combine Partitions, Get Header Table Hash

Enter the following in a BIF file:

stage8: 
{
	[bootimage]fsbl_e_ac.bin
	[bootimage]system_e_ac.bin
	[bootimage]bl31_ac.bin
	[bootimage]u-boot_ac.bin
}

The Bootgen command is:

bootgen -arch zynqmp -image stage8.bif -generate_hashes -o stage8.bin -w on -log error

Stage 9: Sign Header Table Hash

Generate the following files using OpenSSL:

openssl rsautl -raw -sign -inkey secondary0.pem -in ImageHeaderTable.sha384 > ImageHeaderTable.sha384.sig

Stage 10: Combine Partitions, Insert Header Table Signature

Enter the following in a BIF file:

stage10: 
{
	[headersignature]ImageHeaderTable.sha384.sig
	[bootimage]fsbl_e_ac.bin
	[bootimage]system_e_ac.bin
	[bootimage]bl31_ac.bin
	[bootimage]u-boot_ac.bin
}

The Bootgen command is:

bootgen -arch zynqmp -image stage10.bif -o final.bin -w on -log error
Note: At the moment, there is no support for the HSM mode on Versal devices.