16.12. Using Secure Flash Boot on TMS320F2838x Devices

The hex conversion utility supports the secure flash boot capability provided by TMS320F2838x devices, which have both C28 and Arm cores. The secure flash boot applies the Cipher-based Message Authentication Protocol (CMAC) algorithm to verify CMAC tags for regions of allocated memory.

Secure flash boot is similar to the regular flash boot mode in that the boot flow branches to the configured memory address in flash. The difference is that this branch occurs only after the flash memory contents have been authenticated. The flash authentication uses CMAC to authenticate 16 KB of flash. The CMAC calculation requires a 128-bit key that you define. Additionally, you must calculate a golden CMAC tag based on the 16 KB flash memory range and store it along with the application code at a hardcoded address in flash. During secure flash boot, the calculated CMAC tag is compared to the golden CMAC tag in flash to determine the pass/fail status of the CMAC authentication. If authentication passes, the boot flow continues and branches to flash to begin executing the application. See the TMS320F2838x Microcontrollers Technical Reference Manual (SPRUII0) for further details about secure flash boot and the CMAC algorithm.

In order to apply the CMAC algorithm to the appropriate regions in allocated memory, use the hex conversion utility as follows:

  • Use the --cmac=file option. The file should contain a 128-bit hex CMAC key.

    The CMAC key in the file specified by the --cmac command-line option must use the format 0xkey0key1key2key3 in order to access the device registers for CMACKEY0-3. For example, the following file contents represent CMACKEY registers containing key0=0x7c0b7db9, key1=`0x811f10d0`, key2=`0x0e476c7a`, and key3=`0x0d92f6e0`:

    0x7c0b7db9811f10d00e476c7a0d92f6e0

  • Use either the --image option or the --load_image option when using the --cmac option. If you use the --image option, set both --memwidth and --romwidth to the same value.

  • If you use the --boot option (and other boot table options described in Building a Table for an On-Chip Boot Loader) with the --cmac option, the CMAC algorithm assumes that a fill value of 1 is used for gaps between boot table regions. Because of this assumption, you should also set --fill=0xFFFFFFFF when using the --boot and --cmac options together.

  • Specify a HEX directive with one entry that represents all the allocated flash memory. Use a 128-bit aligned length and specify the optional fill value. (The default fill is set to 0’s.)

  • Define the global CMAC tags in C code.

The CMAC feature uses four secure flash boot memory regions that are hardcoded for start/end/tag addresses, and one flexible CMAC region. The flexible region can encompass the entire allocated region as input in the HEX directive or user-specified start/end addresses defined in C code.

C code definitions like the following are required to reserve space for the CMAC tag symbols.

struct   CMAC_TAG
{  uint8_t  tag[16];
   uint32_t start;
   uint32_t end;
};

#pragma RETAIN(cmac_sb_1)
#pragma LOCATION(cmac_sb_1, 0x00200004)
const uint8_t cmac_sb_1[16] =  { 0 };

#pragma RETAIN(cmac_sb_2)
#pragma LOCATION(cmac_sb_2, 0x00210004)
const uint8_t cmac_sb_2[16] =  { 0 };

#pragma RETAIN(cmac_sb_3)
#pragma LOCATION(cmac_sb_3, 0x00250004)
const uint8_t cmac_sb_3[16] =  { 0 };

#pragma RETAIN(cmac_sb_4)
#pragma LOCATION(cmac_sb_4, 0x0027C004)
const uint8_t cmac_sb_4[16] =  { 0 };

#pragma RETAIN(cmac_all)
#pragma LOCATION(cmac_all, 0x00204004)
const struct CMAC_TAG cmac_all =  { { 0 }, 0x0, 0x0};

The four secure flash boot region CMAC tags are stored in the cmac_sb_1 through cmac_sb_4 symbols. The cmac_all symbol stores the CMAC tag for the flexible user-specified region. For cmac_all:

  • If the start and end CMAC_TAG struct members are zero, then the CMAC algorithm runs over entire memory region specified in the HEX directive. The hex conversion utility populates the start and end memory locations with the addresses input from the HEX directive entry.

  • If the start and end members are non-zero, then the CMAC algorithm is instead applied between the specified addresses.

RETAIN pragmas are required in the C code if these symbols are not accessed in the application code.

LOCATION pragmas are required to place symbols at the required memory locations. The LOCATION entries for cmac_sb_1 through cmac_sb_4 are at fixed addresses. The LOCATION address for cmac_all can be user-specified. However, it must not be located within any secure flash boot regions, because the ROM CMAC implementation on the devices does not support this.

The CMAC algorithm is applied prior to the hex conversion. No changes are made to the original input ELF executable.

The hex conversion utility applies the CMAC algorithm only to CMAC regions that have global symbols defined. So if an ELF executable defines only cmac_sb_1 and cmac_all, then only those two CMAC tags will be generated and populated in the generated hex output file.