The MCUboot Port does not provide any interfaces to the user. Consult the MCUboot documentation at https://mcu-tools.github.io/mcuboot/ for further information.
Configuration
Build Time Configurations for MCUboot
The following build time configurations are defined in mcu-tools/include/mcuboot_config/mcuboot_config.h:
Configuration
Options
Default
Description
General
Custom mcuboot_config.h
Manual Entry
Add a path to your custom mcuboot_config.h file. It can be used to override some or all of the configurations defined here, and to define additional configurations.
Upgrade Mode
Swap
Overwrite Only
Overwrite Only Fast
Direct XIP
Overwrite Only
Swap supports A/B image swapping with rollback. Other modes with simpler code path, which only supports overwriting the existing image with the update image (Overwrite Only) or running the newest image directly from its flash partition (Direct XIP), are also available.
Validate Primary Image
Enabled
Disabled
Enabled
Always check the signature of the image in the primary slot before booting, even if no upgrade was performed. This is recommended if the boot time penalty is acceptable.
Downgrade Prevention (Overwrite Only)
Enabled
Disabled
Disabled
Prevent downgrades by enforcing incrementing version numbers. When this option is set, any upgrade must have greater major version or greater minor version with equal major version. This mechanism only protects against some attacks against version downgrades (for example, a JTAG could be used to write an older version).
Number of Images Per Application
1
2 (TrustZone)
1
Number of separately updateable images.
Watchdog Feed
Manual Entry
This function might be implemented if the OS / HW watchdog is enabled while doing a swap upgrade and the time it takes for a swapping is long enough to cause an unwanted reset. If implementing this, the OS main.c must also enable the watchdog (if required)!
Measured Boot
Enabled
Disabled
Disabled
Copies the boot data into the secure RAM, intended to be used by the secure App.
Data Sharing
Enabled
Disabled
Disabled
Copies the user data into the secure RAM, intended to be used by the secure App.
Signing and Encryption Options
Signing and Encryption Options > TrustZone
Boot Record (Image 2)
String length must be 12 characters or less.
Create CBOR encoded boot record TLV for Image 2. Represents the role of the software component (e.g. CoFM for coprocessor firmware). [max. 12 characters]
Custom (Image 2)
Manual Entry
--confirm
Add any custom options to pass to imgtool.py here. --pad places a trailer on the image that indicates that the image should be considered an upgrade. Writing this image in the secondary slot will then cause the bootloader to upgrade to it. --confirm marks the image as confirmed, which causes the upgrade to be permanent.
Signature Type
None
ECDSA P-256
RSA 2048
RSA 3072
ECDSA P-256
Configure the signature type.
Boot Record
String length must be 12 characters or less.
Create CBOR encoded boot record TLV. Represents the role of the software component (e.g. CoFM for coprocessor firmware). [max. 12 characters]
Custom
Manual Entry
--confirm
Add any custom options to pass to imgtool.py here. --pad places a trailer on the image that indicates that the image should be considered an upgrade. Writing this image in the secondary slot will then cause the bootloader to upgrade to it. --confirm marks the image as confirmed, which causes the upgrade to be permanent.
Python
Manual Entry
python
Name of the python command to use. Default is python, but can be updated to python3 for Linux or an absolute path if needed.
Encryption Scheme
ECIES-P256
RSA-OAEP (RSA 2048 only)
Encryption Disabled
Encryption Disabled
Choose the encryption scheme.
Flash Layout
Flash Layout > TrustZone
Non-Secure Callable Region Size (Bytes)
Value must be an integer multiple of the 1024.
0x0
Size of the Non-Secure Callable region of the Secure image.
Non-Secure Flash Area Size (Bytes) (TrustZone Non-Secure)
Value must be an integer multiple of the largest erase size on the mcu.
0x0
Size of the Non-Secure region. This must be non-zero for all TrustZone projects to ensure memory is partitioned correctly, even if the Secure and Non-Secure regions are treated as a single image. If the Non-Secure region can be updated separately, this size must account for the header and trailer.
Non-Secure Callable RAM Region Size (Bytes)
Value must be an integer multiple of the 1024.
0x0
Size of the Non-Secure Callable RAM region of the Secure image.
Non-Secure RAM Region Size (Bytes) (TrustZone Non-Secure)
Value must be an integer multiple of the 8192.
0x0
Size of the Non-Secure RAM region. This must be non-zero for all TrustZone projects to ensure memory is partitioned correctly, even if the Secure and Non-Secure regions are treated as a single image.
Image 2 Header Size (Bytes)
Value must be an integer multiple of 0x80 (alignment required by VTOR).
0x200
Size of the flash reserved for the application image header for Image 2.
Bootloader Flash Area Size (Bytes)
Value must be an integer multiple of the largest erase size on the mcu.
0x20000
Size of the flash reserved for the bootloader.
Image 1 Header Size (Bytes)
Value must be an integer multiple of 0x80 (alignment required by VTOR).
0x200
Size of the flash reserved for the application image header. Must meet minimum VTOR alignment requirements for the core (0x100 for Cortex-M23, 0x200 for Cortex-M4 and Cortex-M33).
Image 1 Flash Area Size (Bytes)
Value must be an integer multiple of the largest erase size on the mcu.
0x20000
Size of the application image 1, including the header and trailer. For TrustZone projects, enter the combined size of the Secure and Non-Secure Callable regions if the Non-Secure image can be updated separately, or enter the size of the entire image slot if Secure, Non-Secure Callable, and Non-Secure regions are updated as a single image.
Scratch Flash Area Size (Bytes)
Value must be an integer multiple of the largest erase size on the mcu.
0x0
Size of the scratch area. Only required for swap update method.
Data Sharing
Maximum Measured Boot Record Size (Bytes)
Value must be an integer.
0x64
Maximum size of the boot record.
Shared Data Size (Bytes)
Value must be an integer.
0x380
Size of the shared RAM area. Required for Measured Boot.
Shared Data Address
Value must be an integer
0x20000000
Shared RAM start address. Required for Measured Boot.
Clock Configuration
This module does not use peripheral clocks.
For best performance it is recommended to use the fastest clock settings supported by the device in order to reduce boot times.
The bootloader must not disable the MOCO prior to calling the application. If the bootloader disables the MOCO, then operation cannot be guaranteed.
Pin Configuration
This module does not use I/O pins.
Usage Notes
Getting Started: Creating an MCUboot Project
Start by creating a new project in e² studio or RASC. If the MCU supports TrustZone, select a Flat project. The bootloader resides entirely in Secure memory, but it is considered a flat project because it does not provide any Non-Secure Callable functions. On the Stacks tab, add New > Bootloader > MCUboot. Resolve any constraint errors and edit configurations as desired. Add either the example keys or generate your own key. The MCUboot key generation tool is provided at ra/mcu-tools/MCUboot/scripts/imgtool.py and documented at https://github.com/mcu-tools/mcuboot/blob/master/docs/imgtool.md. Install the following required python packages to use imgtool.py: https://github.com/mcu-tools/mcuboot/blob/master/scripts/requirements.txt.
In src/hal_entry.c, drag in Developer Assistance > HAL/Common > MCUboot > Quick Setup > Call Quick Setup. Add a call to mcuboot_quick_setup() in the application and make any desired updates.
Note
MCUboot will contain either the verification public key or its hash. During production it is necessary to permanently lock the flash region where MCUboot is programmed to prevent the keys or the code from being modified.
Getting Started: Signing Tool Prerequisite
To use the MCUboot signing tool, ensure you have Python 3.x installed on your system. Then install the Python packages required for the signing tool with the following command (modifying the path as needed depending on current directory):
Getting Started: Converting a Project to an MCUboot Image
MCUboot application images must execute from the image slot defined by the MCUboot project. They are also limited to a single downloadable flash region. All of this is handled by specifying a BootloaderDataFile in the FSP Configuration tool.
Any existing project can be converted to an MCUboot image.
If the project was created with a version prior to FSP v3.0.0, update the linker script to the v3.0.0 version before using it as an MCUboot application image.
Right click the project to convert in e² studio or RASC and select Properties.
Open C/C++ Build and select Build Variables.
Click Add...
For Variable Name, enter BootloaderDataFile. For Type, select File. Browse to the *.bld file created alongside the *.elf file for the associated MCUboot project.
Click OK, then Apply and Close.
To convert a TrustZone image, follow the steps above for both the Secure project and the Non-Secure project.
MCUboot application images must also be signed to work with MCUboot. At a minimum, this involves adding a SHA and MCUboot specific constant data called boot magic in the image trailer.
Signing can be done on the as a post-build step in e² studio. To sign the image as a post-build step:
If Linux is used to develop the application image, change the MCUboot property Signing > Python to python3.
Build the bootloader project to generate the *.bld file. Make sure to build the bootloader project on the same computer as the application image to ensure the path to the signing script is correct.
Define environment variables in the Properties of the application image project in e² studio.
Right click the application image project, and select Properties.
Select C/C++ Build > Environment on the left.
Click Add...
Define the following environment variables one at a time:
MCUBOOT_IMAGE_VERSION: Set to the version of the application image.
MCUBOOT_IMAGE_SIGNING_KEY: Set the path to the key used for signing. If signing is not required, do not set this variable. If example keys are used, set MCUBOOT_IMAGE_SIGNING_KEY as follows (replace <boot_project> with the bootloader project path):
MCUBOOT_IMAGE_ENC_KEY: Set the path to the key used for encryption. If encryption is not required, do not set this variable. If example keys are used, set MCUBOOT_IMAGE_ENC_KEY as follows (replace <boot_project> with the bootloader project path):
MCUBOOT_APP_BIN_CONVERTER: Optional. Set to path to objcopy, arm-none-eabi-objcopy, fromelf, or ielftool. Not required if one of these tools is on the path.
Build the project.
The signed image is output next to the application <project>.elf file with the name <project>bin.signed.
Getting Started: Download and Debug
For projects that do not use TrustZone, debug the MCUboot project using the default configuration. Before running, load the signed image to the address specified in the signing comment in ra_cfg/mcu-tools/include/mcuboot_config/mcuboot_config.h. This can be done with the Load Ancillary File button when debugging in e² studio. Upgrade images can be loaded to the upgrade image slots using the same method.
Note
e² studio projects targeting RA8 devices that do not use TrustZone must disable the "Set TrustZone secure/non-secure boundaries" setting (Debug Configurations > Debugger > Connection Settings > TrustZone > Set TrustZone secure/non-secure boundaries).
For TrustZone projects, debug using the Secure project to ensure the IDAU is partitioned correctly when debugging in e² studio. Make the following modifications before debugging in e² studio:
In the Debug Configurations for your project, on the Startup tab, click Add... to add the MCUboot project *.elf file (Image and Symbols), and optionally the Non-Secure project *.elf file.
For the Secure and Non-Secure project *.elf file, load Symbols Only.
After starting to debug, load the signed Secure image and the signed Non-Secure image into the addresses specified in the signing comment in ra_cfg/mcu-tools/include/mcuboot_config/mcuboot_config.h. This can be done with the Load Ancillary File button when debugging in e² studio. Upgrade images can be loaded to the upgrade image slots using the same method.
Confirming Upgrade in Swap Mode
In Swap Mode operation, if the upgrade image is signed with the –pad option, MCUboot will install that image as a temporary update where if nothing else is done, a reboot will cause MCUboot to revert to the image version that was swapped out during the upgrade. In order for the updated image to prevent this reversion and make the update permanent, the boot_set_confirmed() must be called from the application.
To avail this capability in the application image, from the Stacks tab, add New > Bootloader > MCUboot Image Utilities (Swap Mode). Resolve any constraint errors and edit configurations as desired.
In src/hal_entry.c, drag in Developer Assistance > HAL/Common > MCUboot Image Utilities > Quick Setup > Confirm Primary Image. Add a call to boot_set_confirmed() in the application and confirm the image in the primary slot.
XIP Mode operation
XIP mode is enabled selecting "Direct XIP" as the Upgrade Mode option in the configurator or by defining "MCUBOOT_DIRECT_XIP" in the mcuboot config file. The linker script defines the symbol "XIP_SECONDARY_SLOT_IMAGE" by default to 0. To link an application to the secondar slot in XIP mode, set XIP_SECONDARY_SLOT_IMAGE to 1 in the application linker script. Direct XIP mode does not support TrustZone projects.
Dual Bank operation
MCUboot can be used with Dual bank mode to leverage the advantages of dual bank flash operation. When Dual Bank mode is enabled, only the XIP upgrade mode can be used.
Note
Unlike in normal XIP Mode operation, the linker script symbol "XIP_SECONDARY_SLOT_IMAGE" must be undefined in Dual Bank mode. An example flash layout in this configuration for a 1 MB is shown below. Note that there are 2 copies of the bootloader, one in Bank 0 and another in Bank 1.
MCUboot Dual Bank layout for 1 MB Memory
For this example layout, the following files are generated when Dual Bank mode with XIP is enabled:
Bootloader Project: srec file linked to address 0 and includes the OFS region.
Application Project (Primary): signed bin file linked to address 0x20000.
Application Project (Secondary): signed bin file linked to address 0x20000.
In Dual Bank mode, the available flash memory is split into two halves and referred to as Bank 0 and 1. In this example Bank 0 would span from address 0x0 - 0x7FFFF and Bank 1 from 0x200000 - 0x27FFFF. In Linear mode, it is possible to program the Bank 1 area by programming to 0x80000 - 0xFFFFF.
Programming in Dual Bank Mode
The bootloader must be duplicated in Dual Bank mode. Bank 0 can be programmed using the srec file generated from the MCUboot project; this will also program the OFS region which contains the dual bank enable bit, so it must either be programmed last if each file is programmed independently. Another option is to combine all images: MCUboot in Bank 0, primary image, MCUboot in Bank 1 (no OFS), and secondary image (optional). To program MCUboot to Bank 1, offset MCUboot by half the flash size and cut off the OFS region (0x0100A100 to address 0x0100A2FF on CM33 MCUs that support dual bank). Using srec-cat for a 1 MB flash MCU (0x80000 flash per bank), an example command to create the bootloader image for Bank 1: "srec_cat MCUboot_dualbank.srec -crop 0 0x80000 -offset 0x80000 -o MCUboot_dualbank_offset.srec". The application project for Bank 1 can be similarly offset using srec_cat: "srec_cat app1.bin.signed -binary -offset 0xA0000 -o app1_offset.srec", where 0xA0000 is 0x80000 (half the flash) + 0x20000 (MCUboot size). The signed binary file for Bank 0 can be converted to srec format using srec_cat: "srec_cat app0.bin.signed -binary -offset 0x20000 -o app0.srec"
To combine all the files into one srec file, use "srec_cat MCUboot_dualbank.srec MCUboot_dualbank_offset.srec app0.srec app1_offset.srec -o combined_srec".
External Memory Support
QSPI support for secondary image storage can be enabled in the configurator. The bootloader expects the QSPI memory to be pre-configured by user code in the bootloader for read/write operation. The bootloader code operates under the assumption that the user has configured the QSPI in Extended-SPI mode and that R_QSPI_Open() has been called prior to invoking boot_go();. For example, on the EK_RA6M4 which has the MX25L25645G QSPI flash, after adding the QSPI module to the project, calling the following snippet will configure the QSPI for read/write operation:
For a more detailed example on how to initialize the QSPI device, refer to the QSPI module. The QSPI sector size must be the same as that of the MCU internal flash (BSP_FEATURE_FLASH_HP_CF_REGION1_BLOCK_SIZE) for swap mode operation.
MCUboot Memory Map
For single image projects with no external memory support, the default memory map looks like:
MCUboot Memory Map
For projects with 2 separately updateable images (used for TrustZone applications where the Secure and Non-Secure images can be updated separately), the default memory map with no external memory support looks like:
MCUboot Memory Map (TrustZone)
For single image projects with QSPI, the default memory map looks like:
MCUboot Memory Map with QSPI
MCUboot verification options
MCUboot in FSP supports the following secure image verification options
Hash verification only (SHA256).
Hash and signature verification (ECDSA-P256, RSA-2048 and RSA-3072).
Hash, signature verification and image encryption (ECIES-P256 and RSA-OAEP-2048 with AES-128).
Hash and image encryption only.
MCUboot also supports signature verification using EdDSA-25519 and image encryption using AES-KW-128 and AES-KW-256 but those are currently not supported in FSP.
Notes
When encryption is enabled, MCUboot requires the image in the primary slot to be unencrypted. Only the image loaded in the secondary slot can be encrypted.
MCUboot Crypto Stack Options
The following crypto stacks can be used with MCUboot in FSP:
MbedTLS, which is hardware accelerated on all RA devices. On the RA2 which has an AES engine only, ECC/RSA/SHA operations are in software.
TinyCrypt (S/W Only) can be used with all devices.
TinyCrypt (H/W Accelerated) has AES operations accelerated for the RA2 family only. When using MCUboot without encryption there is no difference between using this or the S/W only version.
SCE9 Protected Mode on devices that have the SCE9 (eg: RA6M4, RA4M3, RA4M2)
MbedTLS provides the best performance for MCUBoot signature verification on the RA6 and RA4 devices but has a much larger code footprint compared to TinyCrypt. For RA2 devices TinyCrypt is the best option.
MCUboot boot time
The time from Reset to executing the application will depend on how quickly MCUboot finishes execution. This is dependent on a variety of factors including
The crypto algorithms chosen for image verification and whether hardware acceleration is enabled. Hardware accelerated SHA256 will be the fastest while encryption enabled modes will be the slowest.
The operating clock speeds.
Whether flash programming was required.
Reducing boot time on SCE9 devices
On devices that have the SCE9, it is possible to reduce the time taken for EC-P256 signature verification by setting the Initialization property for the SCE9 module to only initialize the crypto primitives required for EC-P256 verification. Note that this feature is only supported for EC-P256 currently. Enabling it for any other algorithm will cause a runtime failure.
Using SCE9 Protected Mode Crypto Stack
Using this crypto stack with MCUBoot provides additional security by ensuring that any keys that are used were securely provisioned for the specific device. The Application Note "Installing and Updating Secure Keys for RA Family" (R11AN0496) provides detailed steps on how to go about installing these keys. Since the section "Preparing Keys for Installation and Update Using RFP" document currently only provides information on how to install an AES key, this section will provide information on how to install an ECC public key. These steps can be used to install the public keys used for image verification or the keys used for image encryption.
Note
When using the SCE9 Protected Mode Stack with MCUboot it is required that the public keys in the format described in the "MCUboot Example Keys" module in the stack is also provided in the project.
Installing public keys used for signature verification
Generate an ECC key pair. There are various ways to do this but you can use openSSL to do so: "openssl ecparam -name secp256k1 -genkey -noout -out my_ecc_secp256k1_key.pem".
Once the key is generated, in order to install the public key using RFP (Renesas Flash Programmer) the user needs to have their own UFPK (User Factory Programming Key) and W-UFPK (Wrapped User Factory Programming Key). Refer to R11AN0496 on how to obtain these keys.
Once the UFPK and W-UFPK are available, we need to extract the public key from the pem file. The public key can be viewed by using "openssl ec -noout -text -in my_ecc_secp256k1_key.pem". Note that when the ECC public key is printed out this way, it will contain a 0x04 ASN.1 prefix at the start, which should be discarded.
Use the rfp-util.exe utility from the RFP installation folder to wrap the public key using the UFPK and W-UFPK into a format that can be installed by RFP and the factory bootloader on the MCU.
Use RFP as described in R11AN0496 to install the key to the location of mcuboot_sce9_key section.
These are examples that install the default keys provided with MCUboot in ra/mcu-tools/MCUboot/. The examples assume that UFPK and W-UFPK are already available.
//Print out the EC-P256 Public Key using openSSL
C:\ openssl ec -noout -text -in root-ec-p256.pem
read EC key
Private-Key: (256 bit)
priv:
d7:98:d5:2f:83:01:24:3b:d3:54:2b:7e:55:ed:4c:
74:61:19:00:b0:f9:50:5a:82:4f:e1:e8:ec:06:3b:
cf:f1
pub:
04:2a:cb:40:3c:e8:fe:ed:5b:a4:49:95:a1:a9:1d:
ae:e8:db:be:19:37:cd:14:fb:2f:24:57:37:e5:95:
39:88:d9:94:b9:d6:5a:eb:d7:cd:d5:30:8a:d6:fe:
48:b2:4a:6a:81:0e:e5:f0:7d:8b:68:34:cc:3a:6a:
fc:53:8e:fa:c1
ASN1 OID: prime256v1
NIST CURVE: P-256
//Use the public key (ignore the 0x04 ASN.1 prefix) in the RFP command line to convert the public key into an installable format
// From the bootloader map file determine the address of mcuboot_sce9_key section
Use RFP to install "ECC_pub_install.rkey" as described in "Installing and Updating Secure Keys for RA Family" (R11AN0496) to the address where the mcuboot_sce9_key section is located.
//Use the public key in the RFP command line to convert the public key into an installable format. Note that for RSA, the public modulus has to be concatenated to the public exponent (typically 65537 in 32 bits 00010001 as shown in the asn1parse output above) and then padded with 4 words of 0.
// From the bootloader map file determine the address of mcuboot_sce9_key section
Use RFP to install "RSA_pub_install.rkey" as described in "Installing and Updating Secure Keys for RA Family" (R11AN0496) to the address where the mcuboot_sce9_key section is located.
//Use the public key in the RFP command line to convert the public key into an installable format. Note that for RSA, the public modulus has to be concatenated to the public exponent (typically 65537 in 32 bits 00010001 as shown in the asn1parse output above) and then padded with 4 words of 0.
// From the bootloader map file determine the address of mcuboot_sce9_key section
Use RFP to install "RSA_3072_pub_install.rkey" as described in "Installing and Updating Secure Keys for RA Family" (R11AN0496) to the address where the mcuboot_sce9_key section is located.
Examples
Basic Example
This is an example of using MCUboot in an application.
