doc/README.ti-secure

   1 README on how boot images are created for secure TI devices
   2
   3 CONFIG_TI_SECURE_DEVICE:
   4 Secure TI devices require a boot image that is authenticated by ROM
   5 code to function. Without this, even JTAG remains locked and the
   6 device is essentially useless. In order to create a valid boot image for
   7 a secure device from TI, the initial public software image must be signed
   8 and combined with various headers, certificates, and other binary images.
   9
  10 Information on the details on the complete boot image format can be obtained
  11 from Texas Instruments. The tools used to generate boot images for secure
  12 devices are part of a secure development package (SECDEV) that can be
  13 downloaded from:
  14
  15         http://www.ti.com/mysecuresoftware (login required)
  16
  17 The secure development package is access controlled due to NDA and export
  18 control restrictions. Access must be requested and granted by TI before the
  19 package is viewable and downloadable. Contact TI, either online or by way
  20 of a local TI representative, to request access.
  21
  22 Booting 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
 172 Booting 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.