1README on how boot images are created for secure TI devices 2 3CONFIG_TI_SECURE_DEVICE: 4Secure TI devices require a boot image that is authenticated by ROM 5code to function. Without this, even JTAG remains locked and the 6device is essentially useless. In order to create a valid boot image for 7a secure device from TI, the initial public software image must be signed 8and combined with various headers, certificates, and other binary images. 9 10Information on the details on the complete boot image format can be obtained 11from Texas Instruments. The tools used to generate boot images for secure 12devices are part of a secure development package (SECDEV) that can be 13downloaded from: 14 15 http://www.ti.com/mysecuresoftware (login required) 16 17The secure development package is access controlled due to NDA and export 18control restrictions. Access must be requested and granted by TI before the 19package is viewable and downloadable. Contact TI, either online or by way 20of a local TI representative, to request access. 21 22Booting of U-Boot SPL 23===================== 24 25 When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process 26 requires the presence and use of these tools in order to create a 27 viable boot image. The build process will look for the environment 28 variable TI_SECURE_DEV_PKG, which should be the path of the installed 29 SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or 30 if it is defined but doesn't point to a valid SECDEV package, a 31 warning is issued during the build to indicate that a final secure 32 bootable image was not created. 33 34 Within the SECDEV package exists an image creation script: 35 36 ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh 37 38 This is called as part of the SPL/u-boot build process. As the secure 39 boot image formats and requirements differ between secure SOC from TI, 40 the purpose of this script is to abstract these details as much as 41 possible. 42 43 The script is basically the only required interface to the TI SECDEV 44 package for creating a bootable SPL image for secure TI devices. 45 46 Invoking the script for AM33xx Secure Devices 47 ============================================= 48 49 create-boot-image.sh \ 50 <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> 51 52 <IMAGE_FLAG> is a value that specifies the type of the image to 53 generate OR the action the image generation tool will take. Valid 54 values are: 55 SPI_X-LOADER - Generates an image for SPI flash (byte swapped) 56 X-LOADER - Generates an image for non-XIP flash 57 MLO - Generates an image for SD/MMC/eMMC media 58 2ND - Generates an image for USB, UART and Ethernet 59 XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP 60 61 <INPUT_FILE> is the full path and filename of the public world boot 62 loaderbinary file (depending on the boot media, this is usually 63 either u-boot-spl.bin or u-boot.bin). 64 65 <OUTPUT_FILE> is the full path and filename of the final secure 66 image. The output binary images should be used in place of the standard 67 non-secure binary images (see the platform-specific user's guides and 68 releases notes for how the non-secure images are typically used) 69 u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash 70 u-boot-spl_HS_X-LOADER - boot image for NAND or SD/MMC/eMMC rawmode 71 u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC media 72 u-boot-spl_HS_2ND - boot image for USB, UART and Ethernet 73 u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI Xip flash 74 75 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the 76 <INPUT_FILE> 77 78 Invoking the script for AM43xx Secure Devices 79 ============================================= 80 81 create-boot-image.sh \ 82 <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> 83 84 <IMAGE_FLAG> is a value that specifies the type of the image to 85 generate OR the action the image generation tool will take. Valid 86 values are: 87 SPI_X-LOADER - Generates an image for SPI flash (byte 88 swapped) 89 XIP_X-LOADER - Generates a single stage u-boot for 90 NOR/QSPI XiP 91 ISSW - Generates an image for all other boot modes 92 93 <INPUT_FILE> is the full path and filename of the public world boot 94 loaderbinary file (depending on the boot media, this is usually 95 either u-boot-spl.bin or u-boot.bin). 96 97 <OUTPUT_FILE> is the full path and filename of the final secure 98 image. The output binary images should be used in place of the standard 99 non-secure binary images (see the platform-specific user's guides and 100 releases notes for how the non-secure images are typically used) 101 u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash 102 u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash 103 u-boot-spl_HS_ISSW - boot image for all other boot media 104 105 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the 106 <INPUT_FILE> 107 108 Invoking the script for DRA7xx/AM57xx Secure Devices 109 ==================================================== 110 111 create-boot-image.sh \ 112 <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR> 113 114 <IMAGE_TYPE> is a value that specifies the type of the image to 115 generate OR the action the image generation tool will take. Valid 116 values are: 117 X-LOADER - Generates an image for NOR or QSPI boot modes 118 MLO - Generates an image for SD/MMC/eMMC boot modes 119 ULO - Generates an image for USB/UART peripheral boot modes 120 121 <INPUT_FILE> is the full path and filename of the public world boot 122 loader binary file (for this platform, this is always u-boot-spl.bin). 123 124 <OUTPUT_FILE> is the full path and filename of the final secure image. 125 The output binary images should be used in place of the standard 126 non-secure binary images (see the platform-specific user's guides 127 and releases notes for how the non-secure images are typically used) 128 u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is 129 copied to a file named MLO, which is the name that 130 the device ROM bootloader requires for loading from 131 the FAT partition of an SD card (same as on 132 non-secure devices) 133 u-boot-spl_HS_ULO - boot image for USB/UART peripheral boot modes 134 u-boot-spl_HS_X-LOADER - boot image for all other flash memories 135 including QSPI and NOR flash 136 137 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the 138 <INPUT_FILE> 139 140 Invoking the script for Keystone2 Secure Devices 141 ================================================ 142 143 create-boot-image.sh \ 144 <UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED> 145 146 <UNUSED> is currently ignored and reserved for future use. 147 148 <INPUT_FILE> is the full path and filename of the public world boot 149 loader binary file (only u-boot.bin is currently supported on 150 Keystone2 devices, u-boot-spl.bin is not currently supported). 151 152 <OUTPUT_FILE> is the full path and filename of the final secure image. 153 The output binary images should be used in place of the standard 154 non-secure binary images (see the platform-specific user's guides 155 and releases notes for how the non-secure images are typically used) 156 u-boot_HS_MLO - signed and encrypted boot image that can be used to 157 boot from all media. Secure boot from SPI NOR flash is not 158 currently supported. 159 160 Invoking the script for K3 Secure Devices 161 ========================================= 162 163 The signing steps required to produce a bootable SPL image on secure 164 K3 TI devices are the same as those performed on non-secure devices. 165 The only difference is the key is not checked on non-secure devices so 166 a dummy key is used when building U-Boot for those devices. For secure 167 K3 TI devices simply use the real hardware key for your device. This 168 real key can be set with the Kconfig option "K3_KEY". The environment 169 variable TI_SECURE_DEV_PKG is also searched for real keys when the 170 build targets secure devices. 171 172Booting of Primary U-Boot (u-boot.img) 173====================================== 174 175 The SPL image is responsible for loading the next stage boot loader, 176 which is the main u-boot image. For secure TI devices, the SPL will 177 be authenticated, as described above, as part of the particular 178 device's ROM boot process. In order to continue the secure boot 179 process, the authenticated SPL must authenticate the main u-boot 180 image that it loads. 181 182 The configurations for secure TI platforms are written to make the boot 183 process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK 184 and CONFIG_SPL_LOAD_FIT). With these configurations the binary 185 components that the SPL loads include a specific DTB image and u-boot 186 image. These DTB image may be one of many available to the boot 187 process. In order to secure these components so that they can be 188 authenticated by the SPL as they are loaded from the FIT image, the 189 build procedure for secure TI devices will secure these images before 190 they are integrated into the FIT image. When those images are extracted 191 from the FIT image at boot time, they are post-processed to verify that 192 they are still secure. The outlined security-related SPL post-processing 193 is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which 194 must be enabled for the secure boot scheme to work. In order to allow 195 verifying proper operation of the secure boot chain in case of successful 196 authentication messages like "Authentication passed" are output by the 197 SPL to the console for each blob that got extracted from the FIT image. 198 199 The exact details of the how the images are secured is handled by the 200 SECDEV package. Within the SECDEV package exists a script to process 201 an input binary image: 202 203 ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh 204 205 This is called as part of the u-boot build process. As the secure 206 image formats and requirements can differ between the various secure 207 SOCs from TI, this script in the SECDEV package abstracts these 208 details. This script is essentially the only required interface to the 209 TI SECDEV package for creating a u-boot.img image for secure TI 210 devices. 211 212 The SPL/u-boot code contains calls to dedicated secure ROM functions 213 to perform the validation on the secured images. The details of the 214 interface to those functions is shown in the code. The summary 215 is that they are accessed by invoking an ARM secure monitor call to 216 the device's secure ROM (fixed read-only-memory that is secure and 217 only accessible when the ARM core is operating in the secure mode). 218 219 Invoking the secure-binary-image script for Secure Devices 220 ========================================================== 221 222 secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE> 223 224 <INPUT_FILE> is the full path and filename of the input binary image 225 226 <OUTPUT_FILE> is the full path and filename of the output secure image. 227