1.3.6.4 Bootloader SHA Binary Generation Script Help

Downloading the host script

To clone or download these host tools from Github, go to the main page of this repository and then click Clone button to clone this repo or download as zip file. This content can also be download using MCC content manager.

Path of the tool within the repository is tools/btl_sha_bin_gen.py.

Setting up the Host PC

  • The Script is compatible with Python 3.x and higher

Description

  • This script should be used to generate a binary with 32 Byte SHA-256 embedded in it

  • It takes a binary as an input and generates a SHA-256 Hex Digest on the binary file for the size mentioned and embeds the generated SHA-256 value at the end and creates a new binary file

  • This script is mostly applicable for generating a bootloader binary with SHA-256 at the end of bootloader region for trustZone Devices when Secure boot feature is enabled through Fuse

  • The Secure boot feature is enabled by setting the BOOTOPT bit of BOCOR Row for trustZone devices

    Note: Only BOOTOPT = 1 (SHA-256) is supported by script.

  • If BOOTOPT is set to 1 in BOCOR Row fuse bit (0xFFE81001), then at reset the BOOTROM code generates a SHA-256 on the Bootloader region (BOOTPROT) and compares with SHA-256 value written at last 32 Bytes of BOOTPROT region. If there is a mismatch then device will not Bootup

  • If the above check fails, then bootloader be must re-programmed using the debugger or programmer utility

Memory Layout

  • The SHA-256 digest is computed on the whole BOOTPROT region, which is composed by the Secure Flash (BOOT region) and the Non-Secure Callable Flash (BOOT region)

  • The digest reference value for this area is stored at the end of the Secure Flash (BOOT region), just before the Non-Secure Callable Flash (BOOT region)

    • The BNSC region is optional and can be zero
    Note: The last 32 Bytes where the SHA-256 is stored are not included in the computation.

  • SHA-256 = ((Secure Flash Boot Region - 32 Bytes) + BNSC)

Usage Examples

  • Generate the bootloader binary from MPLAB X for bootloader project by disabling fuse settings and enabling the post build script

  • Ensure that the user sends the device configuration file which has BOOTOPT set to 1 along with the generated bootloader sha binary

Below is the syntax to show help menu for the script:

python <harmony3_path>/bootloader/tools/btl_sha_bin_gen.py --help

Below is the syntax and an example on how to generate a bootloader binary with SHA-256 and No BNSC region:

python <harmony3_path>/bootloader/tools/btl_dev_cfg_gen.py -v -d <device_name> -b <BOOTPROT_size_in_bytes> -n <BNSC_size_in_bytes> -f <Bootloader_binary_path> -o <ouput_binary_path>
python btl_sha_bin_gen.py -v -d pic32cm -b 2048 -f <harmony3_path>/bootloader_apps_uart/apps/trustZone/bootloader/Secure/firmware/pic32cm_ls60_cpro_Secure.X/dist/pic32cm_ls60_cpro/production/pic32cm_ls60_cpro_Secure.X.production.bin -o btl_sha.bin