Basic Secure Boot for OMAP-L138 C6748

TI's Basic Secure Boot for OMAP-L138 and C6748

Description

TI's Basic Secure Boot provides IP protection on the OMAP-L138 DSP+ARM and C6748 DSP processors. Secure OMAPL138/C6748 devices ensure that critical code is executed in a secure environment, hiding sensitive information from the outside world.

Current Security Collateral

The current version of Basic Security User's Guide document for the OMAP-L138/C674x devices can be found here.

Software Downloads

• OMAP-L138/DA850 Secure Utilities can be downloaded from : OMAP-L138 Release

Note: The software is under export control and hence you will need a ti login to obtain the software package.

Booting Secure OMAP-L1x Devices

Secure HexAIS Tool

The SecureHexAIS tool is a command-line AIS generation utility for secure OMAP-L1x and derivative devices. The SecureHexAIS tool relies on its input parameters to be provided in INI files, example of which are included in the package. The ini files are processed in order and are primarily used to specify what AIS Function Execute commands you want to use to initialize the system. The comments in the INI file themselves provide a rough documentation, but further details can be found below.

Command-line Syntax

SecureHexAIS_<DEVICE_NAME>[Options] [Input File Names]
        <Option> can be any of the following:
                -h                      Show this help screen.
                -entrypoint <Addr>      Force specified entry point for AIS boot image.
                -ini <INI file name>    Specify the ini file (default is OMAP-L138.ini).
                -otype <Output Type>    Specify type of output file, from following:.
                     binary                  Create a binary AIS file (.bin), default.
                     carray                  Create a text file with AIS data in a C array (.c).
                     srecord@addr            Create a Motorola S-record format (.srec) at addr.
                     text                    Create a text file with AIS data as ASCII text (.txt).
                -o <Output File Name>   Explicitly specify the output filename.
                                        Default is input file name with extension based on
                                        output type.

INI File Syntax

The INI file consists of a collection of INI sections. Except for the [General] and [Security] sections, which describe configuration information for the AIS file, the INI sections are processed in order and result in contents being added to the generated AIS output. Each INI section contains a collection of fields which are described below:

Configuration INI Syntax

  [GENERAL]
  ; Can be 8 or 16 - used in emifa (NOR boot mode)
  busWidth=8            

  ; SPIMASTER,I2CMASTER,EMIFA,NAND,EMAC,UART,PCI,HPI,USB,MMC_SD,VLYNQ,RAW
  BootMode=Specify boot mode (typically use NONE).  Some boot modes can require 
           certain extra information beyond the actual AIS data. The tools
           may support generating this information depending on the boot mode selection.

  ; TRUE/ON or FALSE/OFF
  seqReadEn=Specify that sequential read should be used for I2C or SPI master modes. This
            is equivalent to using the [AIS_SeqReadEnable] section (see below).

  
  [SECURITY]
  securityType=Specify the type of secure device (GENERIC, CUSTOM)
  
  ; Boot Exit Type: NONSECURE, SECUREWITHSK, SECURENOSK
  ; NONSECURE = Device switches from secure type to non-secure type, jumping to loaded code 
  ;             (no secure kernel since no longer secure device).
  ; SECUREWITHSK = Device remains as secure type, secure kernel is loaded, allowing run-time
  ;                security context switching.
  ; SECURENOSK = Device remains as secure type, secure kernel is NOT loaded, no run-time
  ;              security context switching available.
  bootExitType=Specify the exit mode of the ROM boot loader (NONSECURE, SECUREWITHSK, SECURENOSK).
               SECURENOSK not supported on GENERIC secure devices.
  
  ; Encrypt section list
  encryptSections=Specify the sections to encrypt (ALL or comma-separated list of section names).
                  This can be specifically overridden in the INPUTFILE ini section.
  
  encryptionKey=Specify the 128 bit AES encryption key. String of 32 hexadecimal characters

  ; Binary file containing RSA key info (public and private) for custom secure device
  ; Can be in PEM/DER format (OpenSSL), or XML format (Mono or .Net Framework)  
  rsaKeyFileName=The filename (relative to path program executes from) to the private RSA key
                 needed to generate the load module signature (only applies to CUSTOM secure
                 devices).
                 
  ; SHA Algorithm Selection for 
  genericSHASelection=Selection of Secure Hash algorithm (SHA1 or SHA256) for generic devices

  ; Binary file containing secure key header for generic device
  genKeyHeaderFileName=Specify binary file containing key header for generic devices. If this 
                       is not given, an unencrypted key header is generated from the
                       genericSHASelection and the encryptionKey.

Include a file INI syntax

The INPUTFILE section allows including a binary or object file into the AIS boot image. The result of this INI section will be one or more AIS SectionLoad or EncryptedSectionLoad commands inserted into the AIS output. Note that input files can be specified on the command line, but using individual [INPUTFILE] sections offer more control over placement and content.

  [INPUTFILE]
  FILENAME=Filename of the binary or object file to include in the AIS iamge
  LOADADDRESS=Address to which file contents are loaded. If specified, input file is treated as a
              binary file. For object files, the load address for loadable sections is embedded
              in the object file itself.
  ENTRYPOINTADDRESS=Allows specifying the entry point for this module. This is typically used
                    with binary files since object files embed the entry point.
  USEENTRYPOINT=Set to YES or TRUE to ensure that the entrypoint is taken from this input file
                for the JUMP_CLOSE command
  ENCRYPT=Set to YES or TRUE to encrypt the data 

Insert ROM Fucntion Calls (AIS Function Execute) for L138

These INI sections are used to insert specific AIS Function Execute commands into the AIS output.

These INI sections are used to insert specific AIS Function Execute
  commands into the AIS output.
  
  ; This section allows setting the PLL0 system clock with a  
  ; specified multiplier and divider as shown. The clock source
  ; can also be chosen for internal or external.
  ;           |------24|------16|-------8|-------0|
  ; PLL0CFG0: | CLKMODE| PLLM   | PREDIV | POSTDIV|
  ; PLL0CFG1: | RSVD   | PLLDIV1| PLLDIV3| PLLDIV7|
  [PLL0CONFIG]
  PLL0CFG0=
  PLL0CFG1=

  ; This section allows setting up the PLL1. Usually this will 
  ; take place as part of the EMIF3a DDR setup. The format of
  ; the input args is as follows:
  ;           |------24|------16|-------8|-------0|
  ; PLL1CFG0: |    PLLM| POSTDIV| PLLDIV1| PLLDIV2|
  ; PLL1CFG1: |           RSVD           | PLLDIV3|  
  [PLL1CONFIG]
  PLL1CFG0=
  PLL1CFG1=

  ; This section lets us configure the peripheral interface
  ; of the current booting peripheral (I2C, SPI, or UART).
  ; Use with caution. The format of the PERIPHCLKCFG field 
  ; is as follows:
  ; SPI:        |------24|------16|-------8|-------0|
  ;             |           RSVD           |PRESCALE|
  ;
  ; I2C:        |------24|------16|-------8|-------0|
  ;             |  RSVD  |PRESCALE|  CLKL  |  CLKH  |
  ;
  ; UART:       |------24|------16|-------8|-------0|
  ;             | RSVD   |  OSR   |  DLH   |  DLL   |  
  [PERIPHCLKCFG]
  PERIPHCLKCFG=

  ; This section can be used to configure the PLL1 and the EMIF3a registers
  ; for starting the DDR2 interface. 
  ; See PLL1CONFIG section for the format of the PLL1CFG fields.
  ;            |------24|------16|-------8|-------0|
  ; PLL1CFG0:  |              PLL1CFG              |
  ; PLL1CFG1:  |              PLL1CFG              |
  ; DDRPHYC1R: |             DDRPHYC1R             |
  ; SDCR:      |              SDCR                 |
  ; SDTIMR:    |              SDTIMR               |
  ; SDTIMR2:   |              SDTIMR2              |
  ; SDRCR:     |              SDRCR                |
  ; CLK2XSRC:  |             CLK2XSRC              |
  [EMIF3DDR]
  PLL1CFG0=
  PLL1CFG1=
  DDRPHYC1R=
  SDCR=
  SDTIMR=
  SDTIMR2=
  SDRCR=
  CLK2XSRC=
  
  ; This section can be used to configure the EMIFA to use 
  ; CS0 as an SDRAM interface.  The fields required to do this
  ; are given below.
  ;                     |------24|------16|-------8|-------0|
  ; SDBCR:              |               SDBCR               |
  ; SDTIMR:             |               SDTIMR              |
  ; SDRSRPDEXIT:        |             SDRSRPDEXIT           |
  ; SDRCR:              |               SDRCR               |
  ; DIV4p5_CLK_ENABLE:  |         DIV4p5_CLK_ENABLE         |
  [EMIF25SDRAM]
  SDBCR=
  SDTIMR=
  SDRSRPDEXIT=
  SDRCR=
  DIV4p5_CLK_ENABLE=

  ; This section can be used to configure the async chip selects
  ; of the EMIFA (CS2-CS5).  The fields required to do this
  ; are given below.
  ;           |------24|------16|-------8|-------0|
  ; A1CR:     |                A1CR               |
  ; A2CR:     |                A2CR               |
  ; A3CR:     |                A3CR               |
  ; A4CR:     |                A4CR               |
  ; NANDFCR:  |              NANDFCR              |  
  [EMIF25ASYNC]
  A1CR=
  A2CR=
  A3CR=
  A4CR=
  NANDFCR=
  
  ; This section should be used in place of PLL0CONFIG when
  ; the I2C, SPI, or UART modes are being used.  This ensures that 
  ; the system PLL and the peripheral's clocks are changed together.
  ; See PLL0CONFIG section for the format of the PLL0CFG fields.
  ; See PERIPHCLKCFG section for the format of the CLKCFG field.
  ;               |------24|------16|-------8|-------0|
  ; PLL0CFG0:     |              PLL0CFG              |
  ; PLL0CFG1:     |              PLL0CFG              |
  ; PERIPHCLKCFG: |              CLKCFG               |
  [PLLANDCLOCKCONFIG]
  PLL0CFG0=
  PLL0CFG1=
  PERIPHCLKCFG=

  ; This section should be used to setup the power state of modules
  ; of the two PSCs.  This section can be included multiple times to
  ; allow the configuration of any or all of the device modules.
  ;           |------24|------16|-------8|-------0|
  ; LPSCCFG:  | PSCNUM | MODULE |   PD   | STATE  |  
  [PSCCONFIG]
  LPSCCFG=

  ; This section allows setting of a single PINMUX register.
  ; This section can be included multiple times to allow setting
  ; as many PINMUX registers as needed.
  ;         |------24|------16|-------8|-------0|
  ; REGNUM: |              regNum               |
  ; MASK:   |               mask                |
  ; VALUE:  |              value                |  
  [PINMUX]
  REGNUM=
  MASK=
  VALUE=
  
  ; This section allows configuration of one the systme IOPUs.
  ; The iopuNum field must be valid (0-5) and then mppaStart
  ; and mppaend fields allow setting a range of mppa MMRs to the 
  ; same supplied mppa value.
  ; IOPUSELECT: |  RSVD  | iopuNum| mppaStart |  mppaEnd  |
  ; MPPAVALUE:  |              mppaValue                  |
  [IOPUCONFIG]
  IOPUSELECT=
  MPPAVALUE=
  
  ; This section allow setting the MPU1 or MPU2. If the 
  ; rangenum is out of the allowed range then all the ranges
  ; (including the fixed range) take the start, end, and 
  ; protection values.
  ;            |------24|------16|----------8|----------0|
  ; MPUSELECT: |      RSVD       |   mpuNum  | rangeNum  |
  ; STARTADDR: |              startAddr                  |
  ; ENDADDR:   |               endAddr                   |
  ; MPPAVALUE: |              mppaValue                  |
  [MPUCONFIG]
  MPUSELECT=
  STARTADDR=
  ENDADDR=
  MPPAVALUE=
  
  ; This function allows the user to selectively open up the
  ; the debug TAPs of the device.  Since the function is not
  ; executed until the signature is checked, it does not 
  ; pose a security issue.
  ;          |------24|------16|----------8|----------0|
  ; TAPSCFG: |      RSVD       |       tapscfg         |
  [TAPSCONFIG]
  TAPSCFG=

INI Syntax to Insert Other AIS commands

  ; Requires no fields, simply inserts AIS Enable CRC command
  [AIS_EnableCRC]
  
  ; Requires no fields, simply inserts AIS Disable CRC command
  [AIS_DisableCRC] 
  
  ; Requires no fields, simply inserts AIS Disable CRC command
  [AIS_RequestCRC] 
  CRCVALUE=CRC value for comparison for the Request CRC command
  SEEKVALUE=Seek value for the the Request CRC command
  
  [AIS_Jump]
  LOCATION=Raw address or symbol to which to jump
  
  [AIS_JumpClose]              
  ENTRYPOINT=Raw address or symbol to which to jump upon close boot.  
  
  NOTE: The AIS JumpClose command is automatically inserted at the end of the boot
  with the currently specified entry point.  Manually inserting this command will 
  cause all commands following it to be ignored during boot, though the AIS file 
  generated will still include all those extra commands.
  
  [AIS_Set]
  TYPE=Type field for AIS SET/BOOT_TABLE command
  ADDRESS=Address field for AIS SET/BOOT_TABLE command
  DATA=Data field for AIS SET/BOOT_TABLE command
  SLEEP=Sleep field for AIS SET/BOOT_TABLE command
  
  [AIS_SectionFill]
  ADDRESS=Address field for AIS SECTION_FILL command
  SIZE=Size field for AIS SECTION_FILL command
  TYPE=Type field for AIS SECTION_FILL command
  PATTERN=Pattern field for AIS SECTION_FILL command
  
  [AIS_ReadWait]
  ADDRESS=Address field for READWAIT command
  MASK=Mask field for READWAIT command
  DATA=Data field for READWAIT command
  
  ; Requires no fields, simply inserts AIS Sequential Read command
  [AIS_SeqReadEnable] 
  
  [AIS_FinalFunctionReg]
  FINALFXNSYMBOLNAME=Symbol name of function that should be called after boot completes
                     but before boot loader exits.
  
  ; Install a new RSA/AES key pair
  [AIS_SetDelegateKey]
  RSAKEYFILENAME=Filename to the new (delegate) RSA key.
  ENCRYPTIONKEY=32 hex characters representing the new (delegate) encryption key
  
  ; Remove installed RSA/AES key pair and return to using root keys (installed at start of 
  ; boot image). Requires no fields.
  [AIS_RemoveDelegateKey]

Secure UART Host Tool for UART booting

The Secure UART Host tool is a GUI application to boot secure AIS images over the serial port, from a host PC. To use it:

1. Start the Host app on a PC.
2. Connect the serial port of the PC to the EVM or platform
3. Make sure the device is in the correct UART boot mode to talk to the serial port
4. Load the intended AIS boot file in the GUI
5. Check the "Wait for BOOTME" box
6. Click "Start" button in the GUI.
7. Power up the OMAP platform

At this point the GUI should show activity over the UART port as the host PC boots the slave device.

FAQ

How do I know I have received a secure part?

TI device nomenclature includes a suffix to indicate if Basic secure boot is enabled. For basic secure boot suffix "E" is added on the chip as shown in the below. The complete detail of device nomenclature is described on Pg 276 of OMAPL138 datasheet

Can I boot a non-secure boot image on a secure C6748 part?

No, an non-secure boot image created using HexAis tool can`t be used to boot a secure C6748/OMAPL138 part.

What is some background on CPU execution from power up?

At Power On, the CPU begins executing in Secure Supervisor mode from the secure portion of the ROM. It continues to execute in Secure Supervisor as it executes the AIS image to set up the system (ie the commands defined in the ini file). Once the code image has been decrypted and placed in to the desired location, the ROM has two options for exit: SECUREWITHSK and NONSECURE.

If you have chosen the NONSECURE path, then the ROM will perform a SW sequence (nicknamed "Secure to Non-secure override sequence") that will purge all the secure information from the device; lower the security level of all the MPUs, IOPUs, etc; and then jump to the image (One thing to note is that the TAP configuration remains unchanged during the sequence). At this point, only the non-secure world exists and your code should have access to everything in the chip that was not rendered invisible (ie all the secure information) by that SW sequence performed by the ROM.

If you have chosen the SECUREWITHSK path, then the ROM will set up the Secure Kernel and configure the system such that the Secure Kernel has memory with which to work in the secure world. It will then downgrade the security level in the processor and jump to the image so that it begins executing the image in non-secure supervisor mode. Since the CPU has not gone through the Secure to Non-secure override sequence, both the secure and non-secure worlds exist. As part of the ROM, the secure kernel APIs are available and callable by the non-secure world. With Basic Secure Boot, we do not allow arbitrary secure code to be loaded or run b/c that has the potential to compromise the security of the device. Since you are now executing in non-secure world, you can move between non-secure user and non-secure supervisor like you would normally. The only addition is that you have the ability to have the secure world perform some functions for you, such as decrypting modules. The caveat is that because you have not gone through the override sequence, the security level of the MPUs, IOPUs, etc are still high and in order to access certain functionality, you need to make sure that the security level has been lowered through the INI file.

How to convert application image file into secure boot image?

1. How to convert customer file into secure image?

In the Secure boot and flashing utility package, we provide Secure_HexAIS utitility that converts a Hex file into a secure boot image that contains an unencrypted secure software header followed by an encrypted customer application.Details of this utility are discussed here:

http://processors.wiki.ti.com/index.php/Basic_Secure_Boot_for_OMAP-L138_C6748#Secure_HexAIS_Tool

Like a general purpose device, user has the ability to configure the PLL and device pin mux settings. In addition to this user also provides the customer encryption key, configures the memory and IO protection registers and has the ability to control the debug taps to open the JTAG debug mechanism. all this configurations are done using a ini file rather than a GUI interface as is the case in general purpose device. The description of fields of the ini file are given here:

http://processors.wiki.ti.com/index.php/Basic_Secure_Boot_for_OMAP-L138_C6748#INI_File_Syntax

One additional detail is that after the application development is complete the user needs to add code to bind the image to the device. this process requires the user to add a control statement at the start of his application that will check if the software header is encrypted or not. hence after the first boot the device will check for this information, if the header is not encrypted the device will encrypt the header using the unique device encryption key called (KEK) that is burnt in the efuse of the secure device.

How do I create a ini file for my device?

Please refer the section for INI file to see the syntax of defining parameters in the ini file. Reference ini files are included in the Basic secure package under the path OMAP-L138_Secure\GNU\AISUtils\ini_generic\

Is the CEK provided by TI or the application developer? When and how does the developer use it?

CEK is selected by the application developer. TI does not need to know the CEK used to encrypt the application. CEK is provided in the ini file as described in the wiki above. It is used for encrypting the application while creation of the secure boot image using Secure_HexAis utility.

How to debug secure device?

Application development and debugging on a secure device is not really recommended but there is flexibility in the boot process that allow this functionality when required. The ini file for creation of secure boot images contains field called BootExitType and TAPCFG. Specifying the BootExit type as NONSECURE and TAPCFG= 0x0000FFFF will force the device to exit ROM boot in NON-secure mode and open the JTAG pins to connect the emulator.

Where can I find the location and description of memory protection(MPU) and IO protection(IOPU) registers?

Currently MPUs are documented in the Technical Reference Manual of OMAPL138. IOPU documentation is not provided in the generic secure software package but may be obtained by getting in touch with your local TI contact.

Can I enable secure kernel APIs in BIOS environment?

Yes, Secure kernel is supported in DSP BIOS 5.x. One can enable this feature by adding the following line to the .tcf file in the project

bios.GBL.ENABLE_SK = true;

In addition to this, you will need to you need to include the C source of the secure kernel wrapper APIs to your build. These APIs exist in source form, and are assembly-based calls into Secure Kernel. The SK version of the DSP/BIOS libraries call into these C wrapper APIs, but the API definitions are not currently included in the DSP/BIOS product. The source is distributed only through an official TI contact.

Note: The bootloader needs to exit in secure kernel mode for these APIs to work as expected. This will be needed only in cases where you have a BIOS based secondary bootloader that loads the encrypted application image. This approach is not recommended especially since SYS BIOS 6.x does not support this functionality and the delays involved in enabling the functionality.

What is the preferred method of flashing a secure device?

The process for flashing a secure part is to use the secure loader to load the flashing utility or other 2nd level boot loader that will flash the device.

Example command to create secure AIS images:

 SecureHexAIS_OMAP-L138.exe -ini <ini file>.ini -otype binary -o <binary image>.bin <hello_world>.out

Example command to create secure AIS images:

 SecureHexAIS_OMAP-L138.exe -ini <ini file>.ini -otype binary -o <binary image>.bin <second_level_boot>.out  <boot load module 1>@0x<load address 1>…<boot load module n>@0x<load address n>

If you trust your manufacturer, you can also preflash the image in the manufacturing process and then bind the image to the device in a secure facility.

I am able to encrypt an application with SecureHexAIS_OMAP-L138.exe, flash it, and boot-up and run. Now I am trying to do the same thing, with the same application converted to a module using LoadModGen_OMAP-L138.exe. What should be the input file to LoadModGen_OMAP-L138?

There is a tool that can help strip out the binary blob from your executable that you can use as input to the LoadModGen_OMAP-L138 tool:

Code_Generation_Tools_XML_Processing_Scripts

Once you have installed the package, there is documentation in the overview.ppt and in the index.htm files in the install directory.

Also, the hex6x tool can be used to strip out binary blob in Post-build step:

"${CG_TOOL_ROOT}/bin/hex${CG_TOOL_SUFFIX}.exe" --ti_txt "${BuildArtifactFileName}" -o "${BuildArtifactFileBaseName}.txt" -order M -romwidth 16

This generates an ASCII text file with some simple address info.

What are IOPUs and how do I deal w/ them?

IOPUs exist when you exit the ROM bootloader with the secure kernel enabled. They will able be completely opened up when the Secure to Non-secure override sequence is run. See the additional documents on memory protection for more information: There are some HW protections in place on peripherals like the PSC when you are running after the ROM exits with SK enabled. You can open up the IOPU that protects the PSC:

  // IOPU 0 protects PSC0 and PLLC_0
  [IOPUCONFIG]
  IOPUSELECT = 0x000000FF
  MPPAVALUE  = 0xFFFFFFFF

  // IOPU 1 protects Timer64P0, Timer64P1, and RTC 
  [IOPUCONFIG]
  IOPUSELECT = 0x000100FF
  MPPAVALUE  = 0xFFFFFFFF

  // IOPU 3 protects GPIO, PSC1, and PLLC_1
  [IOPUCONFIG]
  IOPUSELECT = 0x000300FF
  MPPAVALUE  = 0xFFFFFFFF

Then you should be able to use code as is when running with secure kernel enabled.

What memory is off limits when I exit the ROM bootloader with secure kernel enabled?

When you exit SECUREWITHSK:

While the secure kernel is active, the 2nd 16 KB of L2 RAM (ie 0x0080_4000 to 0x0080_7FFF) is off limits. Also, when performing the function call: void SK_switchNonSec(entryAddr); the first 32 bytes of L2 RAM is (ie 0x0080_0000 to 0x0080_001F) off limits. After the completion of the function call: void SK_switchNonSec(entryAddr); then all of L2 is available for use.

How to do secure boot from NAND flash?

EVM board has SPI flash for secure booting, but how can I boot my custom secure board from NAND flash ?

We have to use "NAND_readPage" function to read unencrypted headers. We would face read/write ECC error due to updating the secure headers into flash (updating encrypted headers without doing block erase), we have to take a backup the whole block before updating with encrypted headers then we can erase the block and able to update the secure encrypted headers into the required block of NAND flash.

Note that we have to create the buffer with Uint8 for "NAND_readPage" function and need to cast to Uint32 for required headers assignment.