How to start with DA access on STM32H7RS

How to start with DA access on STM32H7S

Literature

• Wiki pages:
  • STiRoT STM32H7S How to intro article.
  • STiRoT_for_STM32H7RS article
  • How to start with OEMiRoT on STM32H7S article.
  • How to start with STiRoT on STM32H7S article.
  • Debug Authentication for STM32H7RS article.
• UM2237 STM32CubeProgrammer software description
• UM2238 STM32 trusted package creator (TPC) tool software description
• AN5054 Secure programming using STM32CubeProgrammer
• ANxxx Getting started with STiRoT for STM32H7S MCUs

Introduction

Through this practical example you will learn:

• How to perform a debug authentication and reopen the debugger.
• How to read the installed user application firmware using the STM32CubeProgrammer
• How to attach an IDE on a running target and execute step by step, the secure user application
• How to access to bootloader from a closed device to download a new image in the download slot
• How to perform a regression to retrieve an empty board.

Prerequisites

• Hardware
  • STM32H7S discovery board: the STM32H7S devices have all the available security features, including the HW crypto accelerator (the HW cryptographic acceleration is not support for STM327R devices).
    
  • Discovery MB1736- STM32H7S (need USBC cable)

• Required tools
  • STM32Cube_FW_H7RS_V1.0.0RC3 or later
  • STM32CubeProgrammer_rev0.0.7-H7RS-B01 or more recent (with trusted package creator (TPC) selected at installation).
  • IAR Embedded Workbench^® rev 9.20.1 or later.
  • IAR Patch EWARMv9_STM32H7R-Sxx_V0.10.0 or later
  • Tera Term / Putty or equivalent terminal emulator.

Information

The TPC installed together with CubeProgrammer in the bin folder located in default STM32CubeProgrammer path : C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin You can pin this tool to the taskbar to simplify the "STiRoT Getting started" process :

• STM32Cube Firmware
  • Download the STM32Cube_FW_H7RS Cube firmware (advise is to place it close form the C: in order to avoid long windows paths)
  • A directory STM32H7S78-DK is included in "STM32Cube_FW_H7RS\Projects"
    

• Open the env.bat file

• If the STM32CubeProgrammer has not been installed in the default folder:C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer, the customized installation path needs to be updated.
• Update the COM port to be aligned with your COM port number.

File:env.bat General setting.png

• Use the Windows device manager to find out your COM port number, as shown in figure below

1. Debug Opening - STiRoT usecase

1.1. Prerequisites

Perform STiRoT example with CERTIFICATE configuration until 2.4 STiRoT application execution.

1.2. Debug Opening procedure

• Open STM32CubeProgrammer
• Select the shield
• Click on "Discover" -> the product state "Closed" is displayed
• Browse the paths for the root key and the certificate, as indicated in the figure below.
• Click on continue -> the permission window is open
• Select "Level 2 Intrusive Debug" (the STiRoT application is execute in HDPL2, see Secure Boot for STM32H7RS article)
• Click Execute -> A Debug Authentication Success message is displayed.

• The debugger is open and the content of the flash can be readout, as shown in figure below

The debugger will stay open until the next hardware reset.

• Disconnect STM32CubeProgrammer

1.3. IAR connection, step by step user application execution

• Launch IAR
• Select Project -> Attach to Running Target (see figure below) (the STM32CubeProgrammer must be disconnected first)

Some trials you can do are indicated in the figure below

1. Set a break point
2. Click on "break"
3. Click on "Reset"
4. Try out some step by step executions
5. Click on "Go" -> the execution will stop at the break point.

2. Download a new image from a Closed device - STiRoT usecase

The following description shows how to start bootloader to download a new image in the download slot thanks yo Forced download feature.
At reset if a new image is detected in the download slot a firmware update will be done
At the date of writing this article, the GUI graphical interface is not yet functional to use Forced download feature.

The following example shows how to proceed using the debug authentication script and loanch bootloader through command line.

2.1. Prerequisites

To follow the procedure described bellow the device must be provisioned in closed state with STiRoT.
If you followed the paragraph Debug opening for STiRoT usecase, your device must be in closed state. Please disconnect and reconnect your board with the USB cable to be sure your device is not in debug opening mode.

If you didn't follow the debug opening part of this wiki, please perform STiRoT example with CERTIFICATE configuration until 2.4 STiRoT application execution in order to set the product state in closed state.

2.2. Firmware modification

Make some modifications of the STiRoT_Appli and rebuild all the file ->an encrypted image is created through postbuild command.

For example you can make this proposed modification in main.c file and rebuild the project :

If applicable: close IAR or Disconnect STM32CubeProgrammer

2.3. Debug Authentification

• Unplug/ replug the Discovery board USB cable to make a hardawre reset. If the debugger was open, it will be closed again.
• Launch the dbg_auth.bat script

• Type "e" to select the Forced Download. (See the permission set during the certificate generation, DA setting using TPC)
• The script will indicate an error. Ignore it, this will be fixed in later script version

2.4. New application code image download

• In a command prompt: execute the command indicated below
• Depending on your PC administrator rights, you need to run it from the STM32CubeProgrammer installation directory: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer_revx.x.x-H7RS-xxx\bin
• Command to execute:

STM32_Programmer_CLI.exe -c port=COM'''xx''' br=921600  -elbl "ExternalLoader\MX66UW1G45G_STM32H7S78-DK_XSPIM1-SFIx.stldr" -d C:\Users\'''xxxxx'''\STM32Cube_FW_H7RS_V'''x.x.x'''\Projects\STM32H7S78-DK\Applications\ROT\STiROT_Appli\Binary\appli_enc_sign.hex

Note:the xxx needs to be adapted for your configuration.

• The new image of the application code is downloaded in the external flash donwload area defined during the STiRoT configuration defined previously.
• At next reset the STiRoT will detect that a new firmware needs to be installed and perform automatically the installation (this is transparent for a user).

2.5. New installed application code execution

• Launch the Teraterm (or equivalent)
• Reminder:
  • File => New connection
  • The COM port number should be the same as indicated by your Windows device manager and also written in the env.bat file (see Prerequisites chapter)
  • Setup => Serial port -> update to 115200 (and see the figure below for other configurations) -> New Setting
• Press the reset button (black button of the discovery board)
• The new STiRoT application is executed as shown in the figure below

2.6. Full regression using graphic interface

Previously the regression script has been used.
Following an example showing how to proceed using the graphic interface of STM32CubeProgrammer.

• Close Teraterm
• Start STM32CubeProgrammer
• Select the shield
• Click on "Discover" -> the product state "Closed" is displayed
• Browse the paths for the root key and the certificate, as indicated in the figure below.
• Click on continue -> the permission window is open
• Select Full Regression
• Click Execute -> A Debug Authentication Success message is displayed.

• Using STM32CubeProgrammer, you can verify that the flash is empty and that the device is back in "Open" state.

Note: it's a good habit to make a full regression after completing trials. Reminder that it's important if you have regenerated the root key, to not loose this key in ordrer to be able to make a regression or a debugger opening.

3. Debug Opening - OEMiRoT usecase

For a device in closed state the debugger is no open and you have an error message if you try to connect STM32CubeProgrammer.
To open the debug it is mandatory that the device has been provisioned in closed state with Certificate Debug Authentication.

Warning

If the device has been provisioned with Password Debug Authentication, only a full regression is possible and a debug opening is not allowed.

Information

Only the owner of the key and certificate can open the debugger.

3.1. Prerequisites

Please follow OEMiRoT example with CERTIFICATE configuration until 2.7 OEMiRoT application execution. Don't perform a full regression, the device must be in closed state.

3.2. Debug Opening procedure

• Open STM32CubeProgrammer
• Select the shield
• Click on "Discover" -> the product state "Closed" is displayed
• Browse the paths for the root key and the certificate, as indicated in the figure below.
• Click on continue -> the permission window is open
• Select "Level 3 Intrusive Debug"

Information

For the OEMiRoT example the application code is in HDPL3, see Secure Boot for STM32H7RS article. A debug opening in level 2 or in level 3 will make the secure application visible.

• Click Execute -> A Debug Authentication Success message is displayed.

• The debugger is open and the content of the flash can be readout, as shown in figure below

Information

The memory mapping of the code is detailed in Project.map located in: Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\EWARM\STM32H7S78-DK\List

The debugger will stay open until the next hardware reset.

• Disconnect STM32CubeProgrammer

Warning

! Don’t power ON / OFF the board, it closes the debugger.

3.3. IAR connection, step by step user application execution

To attach an IDE:

• Disconnect STM32CubeProgrammer.
  

Warning

! Don’t power ON / OFF the board, it closes the debugger.

• Open the Project.eww located in the EWARM.
• Select: Project -> Attach to running target.
• Open the main.c.
• Set a break point, run the program in the debugger
• Reset the board (black button) and the execution will stop at this point.
• Select: View->Memory-> Memory1 and enter the flash address => The nonsecure code is visible @ 0x70000400.

4. Download a new image from a closed device - OEMiRoT usecase

The following description shows how to access to bootloader from a closed device in order to download a new image. After a reset a firmware update will be generated.
Forced download feature allows to access to secure bootloader.
At the date of writing this article, the GUI graphical interface is not yet functional to use Forced download feature.

The following example shows how to proceed using the debug authentication script and download new image through command line.

4.1. Prerequisites

To follow the procedure described bellow the device must be provisioned in closed state with OEMiRoT.
If you followed the paragraph Debug opening for OEMiRoT usecase, your device must be in closed state. Please disconnect and reconnect your board with the USB cable to be sure your device is not in debug opening mode.

If you didn't follow the debug opening part of this wiki, please perform OEMiRoT example with CERTIFICATE configuration until 2.7 OEMiRoT application execution. Don't perform a full regression, the device must be in closed state.

4.2. Firmware modification

Make some modifications of the OEMiRoT_Appli and rebuild all the file ->an encrypted image is created through postbuild command.

For example you can make this proposed modification in main.c file and rebuild the project :

If applicable: close IAR or Disconnect STM32CubeProgrammer

4.3. Debug Authentification

• Unplug/ replug the Discovery board USB cable to make a hardawre reset. If the debugger was open, it will be closed again.
• Launch the dbg_auth.bat script

• Type "e" to select the Forced Download. (See the permission set during the certificate generation, DA setting using TPC)
• The script will indicate an error. Ignore it, this will be fixed in later script version

4.4. New application code image download

• In a command prompt: execute the command indicated below
• Depending on your PC administrator rights, you need to run it from the STM32CubeProgrammer installation directory: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer_revx.x.x-H7RS-xxx\bin
• Command to execute:

STM32_Programmer_CLI.exe -c port=COMxx br=921600  -elbl "ExternalLoader\MX66UW1G45G_STM32H7S78-DK_XSPIM1-SFIx.stldr" -d C:\Users\'''xxxxx'''\STM32Cube_FW_H7RS_Vx.x.x\Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex

Note:the xxx needs to be adapted for your configuration.

• The new image of the application code is downloaded in the external flash donwload area defined during the OEMiRoT configuration defined previously.
• At next reset the OEMiRoT will detect that a new firmware needs to be installed and perform automatically the installation (this is transparent for a user).

4.5. New installed application code execution

• Launch the Teraterm (or equivalent)
• Reminder:
  • File => New connection
  • The COM port number should be the same as indicated by your Windows device manager and also written in the env.bat file (see Prerequisites chapter)
  • Setup => Serial port -> update to 115200 (and see the figure below for other configurations) -> New Setting
• Press the reset button (black button of the discovery board)
• The new STiRoT application is executed as shown in the figure below

4.6. Full regression using graphic interface

Previously the regression script has been used.
Following an example showing how to proceed using the graphic interface of STM32CubeProgrammer.

• Close Teraterm
• Start STM32CubeProgrammer
• Select the shield
• Click on "Discover" -> the product state "Closed" is displayed
• Browse the paths for the root key and the certificate, as indicated in the figure below.
• Click on continue -> the permission window is open
• Select Full Regression
• Click Execute -> A Debug Authentication Success message is displayed.

• Using STM32CubeProgrammer, you can verify that the flash is empty and that the device is back in "Open" state.

Note: it's a good habit to make a full regression after completing trials. Reminder that it's important if you have regenerated the root key, to not loose this key in ordrer to be able to make a regression or a debugger opening.