Use Cases and Examples

The following example shows how to create a boot image with applications running on different cores. The pmu_fw.elf is loaded by BootROM. The fsbl_a53.elf is the bootloader and loaded on to A53-0 core. The app_a53.elf is executed by A53-1 core, and app_r5.elf by r5-0 core.

the_ROM_image: 
{ 
	[pmufw_image] pmu_fw.elf 
	[bootloader, destination_cpu=a53-0] fsbl_a53.elf 
	[destination_cpu=a53-1] app_a53.elf 
	[destination_cpu=r5-0] app_r5.elf
}

This example shows how to create a boot image with pmu_fw.elf loaded by BootROM.

the_ROM_image: 
{ 
	[pmufw_image] pmu_fw.elf 
	[bootloader, destination_cpu=a53-0] fsbl_a53.elf 
	[destination_cpu=r5-0] app_r5.elf
}

This example shows how to create a boot image with pmu_fw.elf loaded by BootROM. If PMU firmware is specified with attribute [pmufw_image], then PMU firmware is not treated as a separate partition. It is appended to the FSBL, and FSBL and PMU firmware together will be one single large partition. Hence, you cannot not see the PMU firmware in the bootgen log as well.

This example shows how to create a boot image with pmu_fw.elf loaded by FSBL.

the_ROM_image:
{ 
	[bootloader, destination_cpu=a53-0] fsbl_a53.elf 
	[destination_cpu=pmu] pmu_fw.elf 
	[destination_cpu=r5-0] app_r5.elf
}

the_ROM_image: 
{ 
	[bootloader, destination_cpu = a53-0]fsbl_a53.elf 
	[destination_cpu=pmu]pmu_fw.elf 
	[destination_cpu=a53-0, exception_level=el-3, trustzone]bl31.elf  
	[destination_cpu=a53-0, exception_level=el-2] u-boot.elf 
	[offset=0x1E40000, load=0X10000000, destination_cpu=a53-0]image.ub 
}

This example shows how to create a boot image with the encryption enabled for FSBL and the application with the Red key stored in BBRAM:

the_ROM_image: 
{
	[keysrc_encryption] bbram_red_key 
	[
 	 bootloader, 
 	 encryption=aes, 
 	 aeskeyfile=aes0.nky, 
 	 destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 
	[destination_cpu=a53-0, encryption=aes, aeskeyfile=aes1.nky]App_A53_0.elf 
}

This example shows how to create a boot image with encryption enabled for FSBL and application with the RED key stored in eFUSE.

the_ROM_image: 
{ 
	[keysrc_encryption] efuse_red_key 

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

	[
	  destination_cpu = a53-0, 
	  encryption=aes, 
	  aeskeyfile=aes1.nky
	] App_A53_0.elf 
}

This example shows how to create a boot image with the encryption enabled for FSBL and an application with the efuse_blk_key stored in eFUSE. Authentication is also enabled for FSBL.

the_ROM_image: 
{ 
	[fsbl_config] puf4kmode, shutter=0x0100005E
	[auth_params] ppk_select=0; spk_id=0x5
	[pskfile] primary_4096.pem
	[sskfile] secondary_4096.pem
	[keysrc_encryption] efuse_blk_key 
	[bh_key_iv] bhkeyiv.txt
	[
	  bootloader,
	  encryption=aes,
	  aeskeyfile=aes0.nky,
	  authentication=rsa
	] fsbl.elf 
}

This example shows how to create a boot image with encryption enabled for FSBL and the application with the bh_blk_key stored in the Boot Header. Authentication is also enabled for FSBL.

the_ROM_image: 
{ 
	[pskfile] PSK.pem
	[sskfile] SSK.pem
	[fsbl_config] shutter=0x0100005E
	[auth_params] ppk_select=0
	[bh_keyfile] blackkey.txt
	[bh_key_iv] black_key_iv.txt
	[puf_file]helperdata4k.txt
	[keysrc_encryption] bh_blk_key 
	[
	  bootloader,
	  encryption=aes,
	  aeskeyfile=aes0.nky,
	  authentication=rsa,
	  destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 

	[
	  destination_cpu = a53-0,
	  encryption=aes,
	  aeskeyfile=aes1.nky
	] App_A53_0.elf 
}

This example shows how to create a boot image with encryption enabled for FSBL and the application with the efuse_gry_key stored in eFUSE.

the_ROM_image: 
{ 
	[keysrc_encryption] efuse_gry_key
	[bh_key_iv] bh_key_iv.txt 
	
	[
	  bootloader,
	  encryption=aes,
	  aeskeyfile=aes0.nky,
	  destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 
	
	[
	  destination_cpu=a53-0,
	  encryption=aes,
	  aeskeyfile=aes1.nky
	] App_A53_0.elf 
}

This example shows how to create a boot image with encryption enabled for FSBL and the application with the bh_gry_key stored in the Boot Header.

the_ROM_image:
{ 
	[keysrc_encryption] bh_gry_key 
	[bh_keyfile] bhkey.txt
	[bh_key_iv] bh_key_iv.txt
	
	[
	  bootloader,
	  encryption=aes,
	  aeskeyfile=aes0.nky,
	  destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 
	
	[
	  destination_cpu=a53-0,
	  encryption=aes,
	  aeskeyfile=aes1.nky
	] App_A53_0.elf 
}

This example shows how to create a boot image with encryption enabled for FSBL and application with the red key stored in eFUSE.

the_ROM_image:
{
	[fsbl_config] opt_key
	[keysrc_encryption] efuse_red_key

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

	[
	  destination_cpu=a53-0,
	  encryption=aes,
	  aeskeyfile=aes1.nky
	] App_A53_0.elf 
}

The following steps provide a solution in a scenario where two development teams, Team-A (secure team), which manages the secret red key and Team-B, (Not so secure team), work collaboratively to build an encrypted image without sharing the secret red key. Team-A manages the secret red key. Team-B builds encrypted images for development and test. However, it does not have access to the secret red key.

Team-A encrypts the boot loader with the device key (using the Op_key option) - delivers the encrypted bootloader to Team-B. Team-B encrypts all the other partitions using the Op_key.

Team-B takes the encrypted partitions that they created, and the encrypted boot loader they received from the Team-A and uses bootgen to stitch everything together into a single boot.bin.

The following procedures describe the steps to build an image:

Procedure-1

In the initial step, Team-A encrypts the boot loader with the device Key using the opt_key option, delivers the encrypted boot loader to Team-B. Now, Team-B can create the complete image at a go with all the partitions and the encrypted boot loader using Operational Key as Device Key.

1. Encrypt Bootloader with device key:

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

   Example stage1.bif:

   stage1:
   {
   	[fsbl_config] opt_key
   	[keysrc_encryption] bbram_red_key
   	[
   	  bootloader,
   	  destination_cpu=a53-0,
   	  encryption=aes,aeskeyfile=aes.nky
   	] fsbl.elf
   }

   Example aes.nky for stage1:

   Device xc7z020clg484;
   Key 0 AD00C023E238AC9039EA984D49AA8C819456A98C124AE890ACEF002100128932;
   IV 0 F7F8FDE08674A28DC6ED8E37;
   Key Opt 229C993D1310DD27B6713749B6D07FCF8D3DCA01EC9C64778CBAF457D613508F;

2. Attach the encrypted bootloader and rest of the partitions with Operational Key as device Key, to form a complete image:

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

   Example of stage2.bif:

   stage2:
   {
   	[bootimage]fsbl_e.bin
   	
   	[
   	  destination_cpu=a53-0,
   	  encryption=aes,
   	  aeskeyfile=aes-opt.nky
   	] hello.elf
   	
   	[
   	  destination_cpu=a53-1,
   	  encryption=aes,
   	  aeskeyfile=aes-opt1.nky
   	] hello1.elf
   }

   Example aes-opt.nky for stage2:

   Device xc7z020clg484;
   Key 0 229C993D1310DD27B6713749B6D07FCF8D3DCA01EC9C64778CBAF457D613508F;
   IV 0 F7F8FDE08674A28DC6ED8E37;

Procedure-2

In the initial step, Team-A encrypts the boot loader with the device Key using the opt_key option, delivers the encrypted boot loader to Team-B. Now, Team-B can create encrypted images for each partition independently, using the Operational Key as Device Key. Finally, Team-B can use bootgen to stitch all the encrypted partitions and the encrypted boot loader, to get the complete image.

1. Encrypt Bootloader with device key:

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

   Example stage1.bif:

   stage1:
   {
   	[fsbl_config] opt_key
   	[keysrc_encryption] bbram_red_key
   	
   	[
   	  bootloader,
   	  destination_cpu=a53-0,
   	  encryption=aes,aeskeyfile=aes.nky
   	] fsbl.elf
   }

   Example aes.nky for stage1:

   Device xc7z020clg484;
   Key 0 AD00C023E238AC9039EA984D49AA8C819456A98C124AE890ACEF002100128932;
   IV 0 F7F8FDE08674A28DC6ED8E37;
   Key Opt 229C993D1310DD27B6713749B6D07FCF8D3DCA01EC9C64778CBAF457D613508F

2. Encrypt the rest of the partitions with Operational Key as device key:

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

   Example of stage2a.bif:

   stage2a:
   {
   	[
   	  destination_cpu=a53-0,
   	  encryption=aes,
   	  aeskeyfile=aes-opt.nky
   	] hello.elf
   }
   bootgen -arch zynqmp -image stage2b.bif -o hello1_e.bin -w on -log error

   Example of stage2b.bif:

   stage2b:
   {
   	[aeskeyfile] aes-opt.nky
   	[
   	  destination_cpu=a53-1,
   	  encryption=aes,
   	  aeskeyfile=aes-opt.nky
   	] hello1.elf
   }

   Example of aes-opt.nky for stage2a and stage2b:

   Device xc7z020clg484;
   Key 0 229C993D1310DD27B6713749B6D07FCF8D3DCA01EC9C64778CBAF457D613508F;
   IV 0 F7F8FDE08674A28DC6ED8E37;

3. Use Bootgen to stitch the above example to form a complete image:

   Use bootgen to stitch the above, to form a complete image.

   Example of stage3.bif:

   stage3:
   {
   	[bootimage]fsbl_e.bin
   	[bootimage]hello_e.bin
   	[bootimage]hello1_e.bin
   }

   Note: opt_key of aes.nky is same as Key 0 in aes-opt.nky and IV 0 must be same in both nky files.

U-Boot Command for Loading Secure Images

zynqmp secure <srcaddr> <len> [key_addr] 

This command verifies secure images of $len bytes\ long at address $src. Optional key_addr can be specified if user key needs to be used for decryption.

Only Authentication Use Case

To use only authentication at U-Boot, create the authenticated image using bif as shown in the following example.

1. Create a single partition image that is authenticated at U-Boot.
   Note: If you provide an elf file, it should not contain multiple loadable sections. If your elf file contains multiple loadable sections, you should convert the input to the .bin format and provide the .bin as input in bif. An example bif is as follows:

   the_ROM_image:
   {
   	[pskfile]rsa4096_private1.pem
   	[sskfile]rsa4096_private2.pem
   	[auth_params] ppk_select=1;spk_id=0x1
   	[authentication = rsa]Data.bin
   }

2. When the image is generated, download the authenticated image to the DDR.
3. Execute the U-Boot command to authenticate the secure image as shown in the following example.

   ZynqMP> zynqmp secure 100000 2d000
   Verified image at 0x102800

4. U-Boot returns the start address of the actual partition after successful authentication. U-Boot prints an error code in the event of a failure. If RSA_EN eFUSE is programmed, image authentication is mandatory. Boot header authentication is not supported when eFUSE RSA enabled.

Only Encryption Use Case

In case the image is only encrypted, there is no support for device key. When authentication is not enabled, only KUP key decryption is supported.

This example shows how to create a boot image with authentication enabled for FSBL and application with Boot Header authentication enabled to bypass the PPK hash verification:

the_ROM_image: 
{ 
	[fsbl_config] bh_auth_enable
	[auth_params] ppk_select=0; spk_id=0x00000000 
	[pskfile] PSK.pem
	[sskfile] SSK.pem
	
	[
	  bootloader,
	  authentication=rsa,
	  destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 
	
	[destination_cpu=a53-0, encryption=aes] App_A53_0.elf 
}

This example shows how to create a boot image with authentication enabled for FSBL and the application with boot header authentication enabled to bypass the PPK hash verification:

the_ROM_image: 
{ 
	[auth_params] ppk_select=0; spk_id=0x00000000 
	[pskfile] PSK.pem
	[sskfile] SSK.pem
	
	[
	  bootloader,
	  authentication=rsa,
	  destination_cpu=a53-0
	] ZynqMP_Fsbl.elf 
	
	[destination_cpu=a53-0, authentication=aes] App_A53_0.elf 
}

This example shows how to create a boot image that executes in place for a zynqmp (Zynq® UltraScale+™ MPSoC:

the_ROM_image:
{
	[
	  bootloader,
	  destination_cpu=a53-0,
	  xip_mode
	] mpsoc_qspi_xip.elf
}

See xip_mode for more information about the command.

This example helps to understand how split works with offset attribute.

the_ROM_image:
{    
  [split]mode=slaveboot,fmt=bin
  [bootloader, destination_cpu = a53-0] fsbl.elf   
  [destination_cpu = pmu, offset=0x3000000] pmufw.elf    
  [destination_device = pl, offset=0x4000000] design_1_wrapper.bit
  [destination_cpu = a53-0, exception_level = el-3, trustzone, offset=0x6000000]\ hello.elf 
}

When offset is specified to a partition, then the address of that partition in the boot image starts from the given offset. To cover any gap between the mentioned offset of the current partition and the previous partition, bootgen appends 0xFFs to the previous partition. So, now when split is tried on the same, the boot image is expected to be split based on the address of that partition, which is the mentioned offset in this case. So, you see the padded 0xFFs in the split partition outputs.