aeskeyfile - 2021.2 English

Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400)

Document ID
UG1400
ft:locale
English (United States)
Release Date
2021-12-15
Version
2021.2 English

Syntax

  • For Zynq devices and FPGAs:
    [aeskeyfile] <key filename>
  • For Zynq UltraScale+ MPSoC:
    [aeskeyfile = <keyfile name>] <partition>
  • For Versal ACAP:
    { aeskeyfile = <keyfile name>, file = <filename> }

Description

The path to the AES keyfile. The keyfile contains the AES key used to encrypt the partitions. The contents of the key file must be written to eFUSE or BBRAM. If the key file is not present in the path specified, a new key is generated by Bootgen, which is used for encryption.

Note: For Zynq UltraScale+ MPSoC only: Multiple key files need to be specified in the BIF file. Key0, IV0 and Key Opt should be the same across all nky files that will be used. For cases where multiple partitions are generated for an ELF file, each partition can be encrypted using keys from a unique key file. Refer to the following examples.

Arguments

Specified file name.

Return Value

None

Zynq-7000 SoC Example

The partitions fsbl.elf and hello.elf are encrypted using keys in test.nky.

all:                                                          
{                                                             
     [keysrc_encryption] bbram_red_key                        
     [aeskeyfile] test.nky                                    
     [bootloader, encryption=aes] fsbl.elf                    
     [encryption=aes] hello.elf                               
}

Sample key (.nky) file - test.nky

Device       xc7z020clg484;                                  
  Key 0        8177B12032A7DEEE35D0F71A7FC399027BF....D608C58; 
  Key StartCBC 952FD2DF1DA543C46CDDE4F811506228;               
  Key HMAC     123177B12032A7DEEE35D0F71A7FC3990BF....127BD89; 

Zynq UltraScale+ MPSoC Example

Example 1:

The partition fsbl.elf is encrypted with keys in test.nky, hello.elf using keys in test1.nky and app.elf using keys in test2.nky. Sample BIF - test_multipl.bif.
all:                                                           
{                                                              
     [keysrc_encryption] bbram_red_key                         
     [bootloader,encryption=aes,aeskeyfile=test.nky] fsbl.elf  
     [encryption=aes,aeskeyfile=test1.nky] hello.elf           
     [encryption=aes,aeskeyfile=test2.nky] app.elf             
}      

Example 2:

Consider Bootgen creates three partitions for hello.elf, called hello.elf.0, hello.elf.1, and hello.elf.2. Sample BIF - test_mulitple.bif

all:                                                           
{                                                              
     [keysrc_encryption] bbram_red_key                         
     [bootloader,encryption=aes,aeskeyfile=test.nky] fsbl.elf  
     [encryption=aes,aeskeyfile=test1.nky] hello.elf           
}

Additional information:

  • The partition fsbl.elf is encrypted with keys in test.nky. All hello.elf partitions are encrypted using keys in test1.nky.
  • You can have unique key files for each hello partition by having key files named test1.1.nky and test1.2.nky in the same path as test1.nky.
  • hello.elf.0 uses test1.nky
  • hello.elf.1 uses test1.1.nky
  • hello.elf.2 uses test1.2.nky
  • If any of the key files (test1.1.nky or test1.2.nky) is not present, Bootgen generates the key file.
  • aeskeyfile format:

    An .nky file accepts the following fields.

    Device
    The name of the device for which the nky file is being used. Valid for both Zynq device and Zynq UltraScale+ MPSoC.
    Keyx, IVx
    Here 'x' refers to an integer, that corresponds to the Key/IV number, for example, Key0, Key1, Key2 ..., IV0,IV1,IV2... An AES key must be 256 bits long while an IV key must be 12 bytes long. Keyx is valid for both Zynq devices and Zynq UltraScale+ MPSoC but IVx is valid only for Zynq UltraScale+ MPSoC.
    Key Opt
    An optional key that user wants to use to encrypt the first block of boot loader. Valid only for Zynq UltraScale+ MPSoC.
    StartCBC - CBC Key
    An CBC key must be 128 bits long. Valid for Zynq devices only.
    HMAC - HMAC Key
    An HMAC key must be 128 bits long. Valid for Zynq devices only.
    Seed
    An initial seed that should be used to generate the Key/IV pairs needed to encrypt a partition. An AES Seed must be 256 bits long. Valid only for Zynq UltraScale+ MPSoC.
    FixedInputData
    The data that is used as input to Counter Mode KDF, along with the Seed. An AES Fixed Input Data must be 60 Bytes long. Valid only for Zynq UltraScale+ MPSoC.
    Note:
    • Seed must be specified along with FixedInputData.
    • Seed is not expected with multiple key/iv pairs.

Versal ACAP Example

all:                                                         
{                                                            
   image                                                     
   {                                                         
      name = pmc_subsys, id = 0x1c000001                     
      {                                                      
         type = bootloader, encryption = aes,                
         keysrc = bbram_red_key, aeskeyfile = key1.nky,      
         file = plm.elf                                      
      }                                                      
      {                                                      
         type = pmcdata, load = 0xf2000000,                  
         aeskeyfile = key2.nky, file = pmc_cdo.bin           
      }                                                      
      {                                                      
         type=cdo, encryption = aes,                         
         keysrc = efuse_red_key, aeskeyfile = key3.nky,      
         file=fpd_data.cdo                                   
      }                                                      
   }                                                         
}