This article explores the methods of safeguarding your code from unauthorized external access in the STM32H5 series. It delves into the new "Product State" feature, which functions similar to the readout protection (RDP) feature available in other STM32 series, providing a robust layer of security.
Introduction
Hello developer, and welcome to this article. If you are working on an application using the STM32H5 microcontroller series and are in need of resources to safeguard your code from external access, you have come to the right place. So, grab your coffee, get comfortable in your chair, and enjoy the read.
The STM32H5 series has significantly transformed device life cycle management to accommodate the latest enhancements in security features. With these updates, the traditional readout protection (RDP) feature found in other STM32 series is now the product State feature. For those familiar with using RDP, you may find that the product state offers equivalent states to the legacy RDP system. Below are the new states available for this MCU series.
Product State:
- Open: This is the development state where there is no protection. Users have the freedom to debug, test, and develop their application without restrictions.
- Provisioning: In this state, keys and secure firmware are installed, and option bytes are set.
- TZ-Closed: At this stage, security is enforced, and developers can only work within the nonsecure domain.
- Closed: The final product state where debug access is disabled, securing the MCU and its program memory from external access.
- Locked: Similar to the closed state, but with the added condition that regression is not possible.
Upon examining these states, we can ascertain that the open state corresponds to RDP level 0, while the locked state is equivalent to RDP level 2. Although there is no direct equivalent to RDP level 1, the closed state combines the advantages of level 2. Blocking debug access with the benefits of level 1, which allows regression to the level 0 (Open) state.
The TZ-Closed state pertains to TrustZone® applications, which is not the primary focus of this article. However, the steps outlined here may still be beneficial for those working with TZ (TrustZone®) applications.
The image below presents a simplified chart with the available paths and possible ways to perform a regression:
To perform a regression from the closed state, a debug authentication process should be done. This process requires a password key that should be stored within the microcontroller for non-TZ applications. It is critical to provision a password before transitioning to the close state, failure to do so results in the permanent loss of debug access, making regression unfeasible.
- This article outlines the procedure for:
- Generating a password
- Securing it within the MCU
- Effectively enabling the product state to ensure protection equivalent to that of the traditional readout protection (RDP), as well as the regression to the open state
Continue to the following section for a detailed step-by-step guide on the implementation.
Development
We start by showing how to create your password to be provisioned to perform a debug authentication in STM32H5. For this step, you need to have the STM32TrustedPackageCreator software installed on your computer. This software is provided in the same installer of the STM32CubeProgrammer, which can be downloaded from the following link:
During the installation of STM32CubeProgrammer, check the corresponding checkbox to install the STM32 trusted package creator:
Once you have installed the tool, double-click the shortcut created in your desktop to open the software. In the opened window, navigate to the security menu, then open OBkey:
In this menu, we should provide an XML file with the key and some parameters of our implementation. Since the purpose of this is just to show how to do an implementation like the RDP feature, we do not explore the parameters in detail. For further details, refer to the appendix a of UM2238 - STM32 Trusted Package Creator tool software description.
To facilitate the implementation of this resource, you can use the XML template available within the STM32CubeH5 package, under the following path:
STM32Cube_FW_H5_V1.2.0\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config
Navigate to the specified path and open the DA_ConfigWithPassword.xml file with your preferred text editor. Once the file is open, set the DoEncryption parameter to 0 to disable the feature. Then, update the value field in the password section with your chosen password:
After doing that, you can save and close the file and go back to the STM32 trusted package creator software. Now, import this XML file and your password must appear in the field below:
The next step is to select an output path to store the generated key files. For that, click [Select Path], determine the path, and finally click the [Generate OBkey] button. After that, two files will be generated:
The .obk file holds the password intended for provisioning to the STM32H5, while the .bin file also contains the password, which in this instance is used to perform debug authentication.
Once we have generated our password to provision and authenticate a debug session in the STM32, let us change the product state of the STM32H5 to protect our device.
First, flash the image firmware into the microcontroller using your preferred toolchain. After that, open the STM32CubeProgrammer, connect to the MCU, navigate to the [Option Byte] menu, and open the [Product State] drop down menu:
Change the PRODUCT_STATE option to 17, then press [Apply]. A window appears asking if the default DA-Config should be applied, press [NO].
By doing this, the MCU enters provisioning mode, and the STM32CubeProgrammer drops the connection to the microcontroller. To reestablish the connection with the microcontroller, change the connection mode to hot plug and reconnect to the target:
After connecting to the microcontroller, navigate to the [Secure Programming Menu], then open the [Provisioning] tab. In this menu, you should import the .obk file then click the [Start Provisioning button]. Once the process is completed, a confirmation menu is shown:
Now, we have the password provisioned in this MCU. Next, we can move forward and change the Product State to Closed, value 72, under the Option Bytes menu:
Following this step, the STM32CubeProgrammer once again loses connection to the microcontroller as it enters a protected state. This state effectively blocks external access through the debug port similar to RDP level 2 protection, yet it still allows for the possibility of regression!
To perform a regression and recover the debug access to the microcontroller, connect the debugger to your computer and to the target MCU. Then open the STM32CubeProgrammer, navigate to the [Secure Programming] menu, and open the [Debug Authentication] menu.
In this new window, click the [Discover] button, and if the target is connected to your computer, the table shows the status of the product and some additional information. Click on [Browse] and import the .bin file generated before with the password to perform a debug authentication. After that, click [Full Regression] and wait for the process to complete:
When the process finishes, click [OK].
After this process the debug access to the microcontroller is recovered and it returns to the open state:
Now you know how to protect your code on the STM32H5, as well as to provision a password to perform a regression and get access back to the microcontroller!
The above additional steps are required to protect memory and code in STM32H5 microcontrollers, potentially complicating production line processes. To streamline this procedure and simplify factory implementation, the STM32CubeProgrammer CLI (command-line interface) enables the creation of scripts that can execute all necessary steps with just a single or a couple of clicks.
The STM32CubeProgrammer CLI forms part of a comprehensive ecosystem designed to manage automated programming workflows. Moreover, it facilitates integration with other platforms, including Python, enhancing its versatility in various development environments. For further information related to the STM32CubeProgrammer CLI, refer to the STM32CubeProgrammer documentation:
In the next section will be shown on how to create a script to perform all the steps presented in this article, to be executed by the STM32CubeProgrammer.
For the first step, open your preferred text editor and add the following code:
-c port=swd mode=normal reset=swrst
-d C:\Users\botelhod\STM32CubeIDE\usb\usbd_composite_h563\Debug\usbd_composite_h563.elf
-ob PRODUCT_STATE=0x17
--scriptdisconnect
-c port=swd mode=hotplug reset=swrst
-sdp C:\Users\botelhod\Desktop\DA_ConfigWithPassword.obk
-ob PRODUCT_STATE=0x72
The script opens SWD connection by the -c command. Then it downloads an .elf file given by the command -d followed by the image path. After that, it changes the PRODUCT_STATE to the provisioning state by issuing the -ob command. And finally, disconnects (--scriptdisconnect).
In the next step, the script starts a new connection, but now using the hot plug mode. Then it provisions the password by the -sdp and finally changes the product state to the closed state, doing all the steps presented in this tutorial.
To proceed with the execution of this script by using the STM32CubeProgrammer, save the code with the .prg extension. Remember to update the lines that contain the path to the .elf and .obk files in the script to the right paths on your own machine.
Then open your terminal (like CMD, if using MS Windows), and navigate to the STM32CubeProgrammer installation folder. It can be done by issuing the following command:
Cd C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin
Just remember to update the command to refer the proper installation path on your computer. Once the terminal is in the STM32CubeProgrammer installation path, call the tool with the following command:
STM32_Programmer_CLI -script c:\script.prg
Change the “c:\script.prg” string to the path where you have saved your script and then execute it!
Conclusion
And with that, we conclude our exploration. You now have the necessary knowledge to implement readout protection on the STM32H5 series microcontrollers using the product state, acting as a legacy RDP.
An important point to highlight is that this feature can offer the same level of protection as an RDP Level 2. It blocks access to the microcontroller through the debug port, while maintaining the ability to regress to an unprotected level, where access is resumed. This allows applications to not only protect their code against reading, but also against unwanted modifications since a password that was recorded in the microcontroller is necessary to carry out a regression process.
If you have any questions or difficulties with the implementation, do not hesitate to contact our support via ST Community or Online Support.
Hope you enjoyed the article and that it has contributed to your knowledge base and our best wishes for your developments!
Related links
Here are some useful links that contain material that was used to build this article and can be helpful in your developments:
Security features on STM32H5 MCUs: ST Wiki
Introduction to Manufacturing for STM32H5: ST Wiki
How to start with DA on STM32H5: ST Wiki
STM32H5 Online Training - STMicroelectronics
STM32 Trusted Package Creator tool software description - User manual
