1.2.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

btl_sha_bin_gen_memory_layou

  • 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)

btl_sha_bin_gen

Usage Examples

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

  • Make sure you send the device configuration file which has BOOTOPT set to 1 along with thegenerated 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
btl_sha_bin_gen_help_menu

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
btl_sha_bin_gen_output