This wiki page demonstrates how to use the STM32CubeProgrammer command-line and graphical interface to set the readout protection (RDP) keys and levels on STM32C5 MCUs.
1. Introduction
The main goal of this article is to explain how to perform the provisioning of the regression password key, personalize the transition password key, and change the RDP level (increase or regression) using STM32CubeProgrammer[1]. For more details on STM32CubeProgrammer, refer to the user manual STM32CubeProgrammer software description[2].
The RDP level can be increased from level 0 to level 2 through option-byte programming. However, transitioning between RDP level 2 (L2 with boundary scan -> L2) and the regression from level 2 to level 0 require the related password keys. These password keys must be set before increasing the RDP to level 2.
For more details on RDP levels and level transitions, refer to the STM32C5 reference manual[3], available from st.com.
1.1. Prerequisites
- STM32CubeProgrammer, V2.22.0 or higher
- Up-to-date ST-LINKV3 (already included with Nucleo boards)
2. STM32C5 readout protection
The figure below shows the different RDP states and the possible level changes. Note that RDP level 1 is not available for STM32C5 products.
The transition from RDP level 2 is possible on this product if the related password key has been provisioned. The 128-bit OEMKEY password key allows the regression from RDP level 2 to RDP level 0 (fully erasing the flash memory). The 32-bit BSKEY password key allows the transition from "level 2 with boundary scan" to level 2.
The following rules apply to RDP level transitions:
- If RDP level 2 is set without provisioning the OEMKEY, the device remains locked in the L2 state.
- It is impossible to retrieve the regression OEMKEY in RDP level 2, so make sure to store this key safely and do not lose it.
- The provisioning of the OEMKEY or the personalization of the BSKEY can only be done in the RDP level 0 state.
- No OEMKEY is provisioned during the fabrication stage of the device, so a regression from RDV level 2 to level 0 is impossible at this point. Once an OEMKEY has been provisioned, it can be changed (the device must be set to RDP level 0), but it is impossible to remove it.
- The default BSKEY password key provisioned in the device is 0xAAAAAAAA.
3. Setting the BSKEY and OEMKEY password keys
STM32CubeProgrammer offers two ways to program the password key for transition and regression (refer to the previous figure):
- Using the command line.
- Using the graphical interface.
Refer to UM2237[2] for more details.
3.1. Setting the password keys with the command-line interface
- Launch a command prompt in the STM32CubeProgrammer directory (\STM32CubeProgrammer_revx.xx.x\bin). Remember, the device must be in RDP level 0.
- Enter the following commands in the command prompt:
- To set the OEMKEY password key (128 bits):
STM32_Programmer_CLI.exe -c port=swd mode=hotplug ap=1 -lockRDP2 0x11111111 0x22222222 0x33333333 0x44444444
(Replace 0x11111111 0x22222222 0x33333333 0x44444444 with the chosen key.) - To personalize the BSKEY password key (32 bits):
STM32_Programmer_CLI.exe -c port=swd mode=hotplug ap=1 -lockbs 0x11111111
(Replace 0x11111111 with the chosen key.)- This key is needed if the RDP level 2 with boundary scan state is used (refer to RM0522[3]).
- To set the OEMKEY password key (128 bits):
- Perform a power-on-reset by unplugging and replugging the USB cable.
3.2. Setting the password keys with the graphical interface
- Start STM32CubeProgrammer and connect to the device.
- Click on the "shield" icon and the STM32C5 product.
- To set the BSKEY:
- Enter the 32 bits (needed if level 2 with boundary scan is used).
- Click on "Set password".
- To set the OEMKEY:
- Enter the four sets of 32 bits.
- Click on "Set password" and then on "Apply lock RDP2".
- Perform a power-on-reset by unplugging and replugging the USB cable.
4. Increasing the RDP level (0 to 2)
When increasing the RDP level from 0 to 2, keep in mind the following:
- If the OEM key has not been provisioned, setting the device to RDP level 2 is definitive.
- If the RDP level 2 with boundary scan is set, the transition to RDP level 2 is only possible if the BSKEY was provisioned in RDP level 0.
4.1. Increasing the RDP level with the command-line interface
Launch a command prompt in the STM32CubeProgrammer directory (\STM32CubeProgrammer_revx.xx.x\bin).
Enter the following commands in the command prompt:
- RDP level 0 to level 2 with boundary scan (L2_wBS):
STM32_Programmer_CLI.exe -c port=swd -ob rdp_level=0xd1 -ob displ - RDP level 2 with boundary scan to level 2:
STM32_Programmer_CLI.exe -c port=swd mode=hotplug ap=1 -unlockbs 0x11111111
(Replace 0x11111111 with the BSKEY password key that was set in the previous stage.) - RDP level 0 to level 2:
STM32_Programmer_CLI.exe -c port=swd mode=hotplug ap=1 -ob RDP_LEVEL=0x72
(0x72 corresponds to RDP level 2; refer to the figure in section 2 or RM0522[3]). - Perform a power-on-reset by unplugging and replugging the USB cable.
4.2. Increasing the RDP level with the graphical interface
- Start STM32CubeProgrammer and connect to the device.
- Click on the "OB" icon.
- Select the value corresponding to level 2 (72) from the dropdown menu and click on "Apply".
For the transition from RDP level 2 with boundary scan to level 2, proceed as follows:
- Start STM32CubeProgrammer.
- Click on the "shield" icon.
- Enter the 32-bit BSKEY password, as shown in the figure below (0x11111111 in this example)
- Click on "Transition".
- Perform a power-on-reset by unplugging and replugging the USB cable.
5. Decreasing the RDP level (2 to 0)
As shown in the first figure of this wiki page, the OEMKEY allows a regression from both RDP levels 2 to RDP level 0. This procedure fully erases the flash memory.
5.1. Decreasing the RDP level with the command-line interface
Launch a command prompt in the STM32CubeProgrammer directory (\STM32CubeProgrammer_revx.xx.x\bin).
Enter the following commands in the command prompt:
- RDP2 -> RDP0:
STM32_Programmer_CLI.exe -c port=swd mode=hotplug ap=1 -unlockRDP2 0x11111111 0x22222222 0x33333333 0x44444444
(Replace 0x11111111 0x22222222 0x33333333 0x44444444 with the previously set 128-bit OEMKEY password key.) - Perform a power-on-reset by unplugging and replugging the USB cable before reconnecting STM32CubeProgrammer.
- Note that the entire flash memory has been erased.
5.2. Decreasing the RDP level with the graphical interface
For the transition from RDP level 2 with boundary scan or RDP level 2 to RDP level 0, proceed as follows:
- Start STM32CubeProgrammer.
- Click on the "shield" icon.
- Enter the 128-bit OEMKEY password (0x11111111 0x22222222 0x33333333 0x44444444 in this example).
- Click on "Unlock RDP2" and then "Apply Unlock RDP2".
- Perform a power-on-reset by unplugging and replugging the USB cable before reconnecting STM32CubeProgrammer.
- Note that the entire flash memory has been erased.
6. Appendix
Using STM32CubeProgrammer (command-line or graphical interface) some operations are implicitly executed.
For the development of a custom programming solution, refer to RM0522[3] for more details. A couple of these solutions are highlighted below.
6.1. OEMKEY validation
If the OEMKEY has been wrongly provisioned, the regression to RDP level 0 is not possible. It is important to apply the verification procedure described in the OEMKEY validation principle section of RM0522.
6.2. OEM key setting
The OEM key management section of RM0522 describes the steps to set the 128-bit OEMKEY. When the OEMLOCK is set, it cannot be set back to 0, meaning that the corresponding state explained in the OEM RDP unlocking methods table (RM0522) is no longer available.
6.3. BSKEY key setting
A default key is provisioned on the device during manufacturing (0xAAAAAAAA). The BS key management section of RM0522 demonstrates how to personalize the 32-bit BSKEY.
6.4. RDP level transition and regression
The RDP unlocking sequences section of RM0522 indicates the different steps to:
- Perform the transition from RDP level 2 with boundary scan to RDP level 2 (OEMKEY).
- Perform a regression for RDP level 2 or level 2 with boundary scan to RDP level 0 (BSKEY).
7. References