/**
@page 1_Image_BFU / Boot and Firmware Update Demo Application
@verbatim
******************** (C) COPYRIGHT 2017 STMicroelectronics *******************
* @file readme.txt
* @brief This application shows Boot and Firmware Update example.
******************************************************************************
*
* Copyright (c) 2017 STMicroelectronics. All rights reserved.
*
* This software component is licensed by ST under Ultimate Liberty license
* SLA0044, the "License"; You may not use this file except in compliance with
* the License. You may obtain a copy of the License at:
* www.st.com/SLA0044
*
******************************************************************************
@endverbatim
@par Application Description
The Boot (B) and Firmware Update (FU) solution allows the update
of the STM32 microcontroller built-in program with new firmware versions, adding
new features and correcting potential issues. The update process is performed in
a secure way to prevent unauthorized updates.
In addition, Secure Boot (Root of Trust services) checks and activates the STM32
security mechanisms (if any), and checks the authenticity and integrity of user application
code before every execution to ensure that invalid or malicious code cannot be run.
The Firmware Update application receives the encrypted firmware image, decrypts
it, then checks the authenticity and integrity of the code before installing it.
The key management services provide cryptographic services to the user
application through the pkcs11 APIs (KEY ID based APIs). User application keys are stored
and can be updated in a secure way (authenticity check, data decryption and data integrity check).
This example handles 1 firmware image with 1 single slot in FLASH allowing to
maximize the user application size.
As a consequence, some features are not available:
* download a new firmware image from the application
* resume firmware update procedure in case of power off during installation
To be easily tailorable to 128 Kbytes footprint, SFU_DEBUG_MODE compilation switch is disabled.
As a consequence there is no print on terminal during SBSFU execution.
For more details, refer to UM2262 "Getting started with SBSFU - software expansion for STM32Cube"
available from the STMicroelectronics microcontroller website www.st.com.
@par Keywords
Security, SBSFU, MPU
@par Directory contents
- 1_Image_BFU/Core/Src/main.c Main application file
- 1_Image_BFU/Core/Src/stm32wlxx_hal_msp.c HAL MSP module
- 1_Image_BFU/Core/Src/stm32wlxx_it.c STM32 interrupt handlers
- 1_Image_BFU/Core/Inc/app_hw.h Hardware definition for application
- 1_Image_BFU/Core/Inc/main.h Header file for main.c
- 1_Image_BFU/Core/Inc/stm32wlxx_hal_conf.h HAL configuration file
- 1_Image_BFU/Core/Inc/stm32wlxx_it.h Header file for stm32wlxx_it.c
- 1_Image_BFU/Core/Inc/stm32wlxx_nucleo_conf.h BSP configuration file
- 1_Image_BFU/BFU/App/sfu_boot.c Secure Boot (SB): entry/exit points and state machine
- 1_Image_BFU/BFU/App/sfu_com_loader.c SBSFU communication module: local loader part
- 1_Image_BFU/BFU/App/sfu_com_trace.c SBSFU communication module: trace part
- 1_Image_BFU/BFU/App/sfu_error.c SBSFU errors management
- 1_Image_BFU/BFU/App/sfu_fwimg_common.c SBSFU image handling: common functionalities/services
- 1_Image_BFU/BFU/App/sfu_interface_crypto_scheme.c Crypto scheme implementation based on KMS API
- 1_Image_BFU/BFU/App/sfu_kms.c Key management service blob importation handling
- 1_Image_BFU/BFU/App/sfu_loader.c SBSFU Local Loader
- 1_Image_BFU/BFU/App/sfu_new_image.c SBSFU image handling: manage the new firmware image storage and installation
- 1_Image_BFU/BFU/App/sfu_test.c SBSFU security protection automatic test
- 1_Image_BFU/BFU/App/app_sfu.h Software configuration of SBSFU application
- 1_Image_BFU/BFU/App/sfu_boot.h Header file for sfu_boot.c
- 1_Image_BFU/BFU/App/sfu_com_loader.h Header file for sfu_com_loader.c
- 1_Image_BFU/BFU/App/sfu_com_trace.h Header file for sfu_com_trace.c
- 1_Image_BFU/BFU/App/sfu_def.h General definition for SBSFU application
- 1_Image_BFU/BFU/App/sfu_error.h Header file for sfu_error.c file
- 1_Image_BFU/BFU/App/sfu_fsm_states.h SBSFU FSM states definitions
- 1_Image_BFU/BFU/App/sfu_fwimg_internal.h Internal definitions for firmware image handling (sfu_fwimg_core.c and sfu_fwimg_services.c)
- 1_Image_BFU/BFU/App/sfu_fwimg_regions.h FLASH regions definitions for image handling
- 1_Image_BFU/BFU/App/sfu_fwimg_services.h Header file for sfu_fwimg_services.c
- 1_Image_BFU/BFU/App/sfu_interface_crypto_scheme.h Header file for sfu_interface_crypto_scheme.h
- 1_Image_BFU/BFU/App/sfu_kms.h Header file for sfu_kms.c
- 1_Image_BFU/BFU/App/sfu_loader.h Header file for sfu_loader.c
- 1_Image_BFU/BFU/App/sfu_new_image.h Header file for sfu_new_image.c
- 1_Image_BFU/BFU/App/sfu_test.h Header file for sfu_test.c
- 1_Image_BFU/BFU/App/sfu_trace.h Header file for sfu_trace.c
- 1_Image_BFU/BFU/Target/sfu_low_level.c SBSFU general low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_flash.c SBSFU flash low level interface (wrapper)
- 1_Image_BFU/BFU/Target/sfu_low_level_flash_int.c SBSFU internal flash low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_flash_ext.c SBSFU external flash low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_security.c SBSFU security low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level.h Header file for general low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_flash.h Header file for flash low level interface (wrapper)
- 1_Image_BFU/BFU/Target/sfu_low_level_flash_int.h Header file for internal flash low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_flash_ext.h Header file for external flash low level interface
- 1_Image_BFU/BFU/Target/sfu_low_level_security.h Header file for security low level interface
@par Hardware and Software environment
- This example runs on STM32WL55xx devices.
- This example has been tested with NUCLEO-WL55JC RevC board and can be
easily tailored to any other supported device and development board.
- An up-to-date version of ST-LINK firmware is required. Upgrading ST-LINK firmware
is a feature provided by STM32Cube programmer available on www.st.com.
- This example is linked with SE_Core binary generated by Secure Engine Core binary generation project.
- This example needs a terminal emulator.
- Microsoft Windows has a limitation whereby paths to files and directories cannot
be longer than 256 characters. Paths to files exceeding that limits cause tools (e.g. compilers,
shell scripts) to fail reading from or writing to such files.
As a workaround, it is advised to use the subst.exe command from within a command prompt to set
up a local drive out of an existing directory on the hard drive, such as:
C:\> subst X: <PATH_TO_CUBEFW>\Firmware
@par How to use it ?
Several steps to run BFU application :
1. Compile projects in the following order. This is mandatory as each project requests some objects
generated by the compilation of the previous one:
- 1_Image_SECoreBin (see also SECoreBin/readme.txt)
- 1_Image_BFU
- 1_Image_UserApp (see also UserApp/readme.txt)
2. Before loading BFU image into the target, please ensure with STM32CubeProgrammer available on www.st.com that
the following are valid for the device:
- RDP Level 0
- Write Protection disabled on all FLASH pages
- Chip has been erased
3. Use a terminal emulator (Tera Term for example, open source free software terminal emulator
that can be downloaded from https://osdn.net/projects/ttssh2/) for UART connection with the board.
Support of YMODEM protocol is required. Serial port configuration should be :
- Baud rate = 115200
- Data = 8 bits
- Parity = none
- Stop = 1 bit
- Flow control = none
4. Load BFU image into target memory with your preferred toolchain or STM32CubeProgammer.
5. Once the BFU software is downloaded, power cycle the board (unplug/plug USB cable) : the BFU
application starts and configures the security mechanisms if some of them are enabled.
6. [If RDP is enabled] Power cycle the board a second time (unplug/plug the USB cable): the BFU application starts with
the configured securities turned on and the Tera Term connection is possible.
Caution: Make sure to use an up-to-date version of ST-LINK firmware else BFU may not start.
7. At startup (Power On or Reset button pushed) :
- Green LED blinks every 3 seconds when a local download is waited.
- Green LED blinks every 250 ms in case of error in option bytes configuration.
- 'C' is displayed when BFU is ready for a firmware image download. To be easily tailorable to 128 Kbytes footprint,
SFU_DEBUG_MODE compilation switch is disabled. As a consequence there is no print on terminal during
BFU execution.
8. Send the user encrypted firmware file (\1_Image\1_Image_UserApp\Binary\UserApp.sfb) with Tera Term
by using menu "File > Transfer > YMODEM > Send..."
Note1 : Press User push-button (B1) at reset to force a local download if an application is already installed.
Note2 : The following steps enable the protections disabled by default:
- Comment "SECBOOT_DISABLE_SECURITY_IPS" in app_sfu.h. This will enable RDP, WRP, DAP, DMA, IWDG protections
as well as attack surface reduction with MPU.
- As TAMPER detection can be very sensitive, the protection remains disabled by default.
Uncomment "SFU_TAMPER_PROTECT_ENABLE" in app_sfu.h to enable it.
- In Linker_Common, update the mapping by:
- Renaming "mapping_fwimg.icf" to "mapping_fwimg_no_sec.icf".
- Renaming "mapping_sbsfu.icf" to "mapping_sbsfu_no_sec.icf".
- Renaming "mapping_fwimg_sec.icf" to "mapping_fwimg.icf".
- Renaming "mapping_sbsfu_sec.icf" to "mapping_sbsfu.icf".
These features achieve an attack surface reduction but will not make it possible to protect secrets.
Note3 : for Linux users Minicom can be used but to do so you need to compile the SBSFU project with the MINICOM_YMODEM switch enabled (app_sfu.h)
* <h3><center>© COPYRIGHT STMicroelectronics</center></h3>
*/
747d4e27df