Showing results for 
Search instead for 
Did you mean: 

Implementing debug authentication on STM32H5 using CLI tools

Ruchit N
ST Employee


Debug authentication is a critical security feature of the system considering that with a debugger the user can access a large part of the system. To control a reopening of the debug port, the device imposes a debug authentication protocol.

Debug authentication controls debug opening and regressions. It can be used during development, manufacturing and for field return.


The article describes the debug authentication process on STM32H5 using STM32 CLI tools. It showcases the possibility of command-line interface (CLI) implementation for the process, which can be used in the automated production environment. The process can be used to integrate the commands in the production automation scripts to lock and unlock the debug ports of the STM32 device.

The process goes through six steps at the automated production environment as listed below:

  1. Create a provisioning file (.obk file) containing the hash of the debug authentication password to be used while provisioning.
  2. Generating and programming firmware on the STM32H5 MCU
  3. Move product state to PROVISIONING.
  4. Provision to the MCU with the .obk file.
  5. Move the product state to CLOSED to close all the unauthorized debug accesses.
  6. Regress it back to the original state that is, OPEN. This illustrates the device being returned from the field because of some issue.

The final step allows you to recover the device but with the flash mass erased. This also resets the option bytes.


Prerequisites and tools

For this article, we are using NUCLEO-H563ZI. The process is similar for other STM32H5 products.

Required Tools

  1. STM32CubeProgrammer: The STM32CubeProgrammer CLI tool is included with the standard installation.
  2. STM32TrustedPackageCreator_CLI: The tool is installed along with the STM32CubeProgrammer. Make sure to check the option during installation.


Environment Setup


Note: For this demo, we are using the NUCLEO-H563ZI.



The debug authentication controls the debug port or JTAG dedicated access point (ap0) by securely locking it or opening it back using regressions. It is in accordance with the secure protocol defined by Arm that is, Arm PSA ADAC v1.0. It can be used during the development, manufacturing and for field return analysis of the MCU.

The debug authentication is supported on both TrustZone® (TZ) enabled and disabled devices. In the case when TZ is disabled, the usage of a password is the only possible way of regressions. While in the case when TZ is enabled, cryptographic certificates can be used for opening the debug ports.


Debug authentication step-by-step

In this section, we go through the steps of provisioning the MCU with a set password using STM32TrustedPackageCreator and STM32CubeProgrammer CLI tools. At the end, we regress the board out of the CLOSED product state using the same CLI tools to demonstrate the complete authentication process. The same flow can be used in the production environment. Furthermore, these CLI commands can be integrated with the production automation environment.

Before starting the debug authentication (DA) steps, we need to build the application binary. For demonstration, we will use the GPIO_IOToggle example provided in the STM32CubeH5 software package.

  1. Open the GPIO_IOToggle or any other desired project in STM32CubeIDE or any other preferred IDE.
  2. Build the project.
  1. The .out or .elf file is created in the Debug folder in the root directory.

The application file is used in the later steps.

Create a folder structure

To align with the STM32CubeProgrammer and STM32 TrustedPackageCreator CLI tools’ compatibility, we create a folder structure as shown below:


Make sure that the file path remains as short as possible. For this demo, we are creating it at the ‘C:\H5\’ location.

After creating the folder, copy the DA_ConfigWithPassword.xml file from the STM32CubeH5 firmware package from the path below, and paste to ‘H5\Config’ folder:


Similarly, copy the previously created .out or .elf file and paste it to the ‘H5\Binary’ folder.

The following steps require the CLI tools. To use the tools, windows command prompt needs to be opened from the tools file location. Alternatively, the same path must be included in the system’s environment variable. The typical install path looks like this:

C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin

The following steps are required for the debug authentication process:

Step 1: Create the provisioning file (.obk file)

Use the CLI command below to generate the provisioning file using the path to the .xml file.

STM32TrustedPackageCreator_CLI.exe –obk <path to .xml file>

The command generates the password.bin and DA_ConfigWithPassword.obk file by default in the \binary folder, relative to the .xml file’s location in the .config file.

The command should run successfully as shown below. The successful execution logs show the location where the files are generated.


Here, the .xml file can be edited to update the password as desired. But, for this demonstration we use the file as is.

Step 2: Program the application binary

For this step, we use the STM32CubeProgrammer CLI tool. It is used to connect the utility to the board in hotplug mode and pass the file path to the application binary file. Use the command below:

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -d <file path to the application binary> -v

The command should successfully run as shown below, and it should run the application code on the hardware.


Reset the board after the success message to observe the LED blinking.

Step 3: Move to the PROVISIONING state.

Using the STM32CubeProgrammer CLI tools, we set the production state to 0x17 in the option byte configuration using the command below:

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -ob PRODUCT_STATE=0x17


Step 4: Provisioning the .obk file

We use the STM32CubeProgrammer CLI tool to provision the previously created .obk file. We leverage the ‘-sdp’ command to start the OBKey provisioning using the .obk file path as shown in the screen capture below.

Use the command:

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -sdp <.obk complete file path>


The logs show that the secure data provisioning has been completed successfully by provisioning the .obk file with the included password.

Step 5: Move to the CLOSED state.

As we are done with the provisioning stage, we can now move the device to the CLOSED state. After this step is executed successfully, the device will no longer be accessible using its debug port. This means that after this step, control of the debugger connection with the device is blocked.

It must be noted that the application is not affected. It is able to read or write to the flash (provided there is no WRP or RDP set). Hence, if the application is designed to perform in-application programming, the debug authentication will not limit that.

From this stage, the device can only be recovered by performing the regression. It will involve mass erasing the entire flash, which we will see in the next step.

We use the command below to set the PRODUCT_STATE to 0x72 (CLOSED)

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -ob PRODUCT_STATE=0x72

The command should run and end up with the error as shown below:


The error is expected as it shows that the device was successfully moved to the “CLOSED” state and debugger access was lost. Hence, after this step you cannot regain the debugger access of the device without regression.

This step concludes the process to lock the debug port using the commands.

Regression can be required in a product life cycle when hardware is returned from the field for service. In such cases, the factory can regress the board to recover the device and program it with the firmware again. It is assumed that the provisioning password is the factory’s responsibility to keep it a secret.

Step 6: Regress back to the OPEN state

The regression step can be divided into two phases when using the CLI tools. The first phase requires discovering the device and the second phase include the regression process by passing the password file to open the device.

Phase 1: Discovery

To “Discover” the device, we use the command below. Setting "debugauth" to "2" allows discovery and fetches the necessary details and state of the MCU.

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG debugauth=2


As shown in the image above, the PSA life cycle is set to ST_LIFECYCLE_CLOSED. This confirms that the device is in the closed state and can be regressed out using the debug authentication. After verifying this, we can enter into the second phase of the process.

Phase 2: Regression

We use the “debugauth=1” command to provision the password binary as in the command below:

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG debugauth=1


As shown in the image, the tools prompt you to enter the path to the password file (password.bin by default in this case). Once that is done, the tool shows the “Debug Authentication Success” message.


After this stage, the flash will be mass erased. You will not see your application firmware running anymore. In this case, we will not see the user LED blinking anymore.

Now, we can access the MCU’s debug port again. We can verify it by checking the current product state, which is set to OPEN. You can use the command below to do the same:

STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -ob displ

All these steps sum up the entire process of the debug authentication for STM32H5 with TrustZone® disabled. This process can be used as a reference to be integrated with the production environment. Furthermore, to have it automated for mass production which might not be possible for the GUI based tool.



  1. STM32CubeProgrammer
  2. STM32Cube_FW_H5_V1.0.0
  3. Introduction to Debug Authentication for STM32H5 MCUs
  4. RM0481 STM32H5x3/562 Reference Manual
  5. UM2237 STM32CubeProgrammer software description
  6. UM2238 STM32 Trusted Package Creator tool software description
  7. AN5054 Secure programming using STM32CubeProgrammer
  8. AN2606 STM32 microcontroller system memory boot mode
Associate III

Hello @Ruchit N ,


thanks for tutorial. Where i can find troubleshooting part?  After step #5 i am not able to connect to my STM32H573VIT6 device anymore. Any attempt ends up with:


c:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin>STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG debugauth=2
                       STM32CubeProgrammer v2.16.0

Start Debug Authentication Sequence

Open SDM Lib
No device found by ST-LinkError:
Debug Authentication: Discovery Failed



What can cause this behavior? I have a bare device, not a STM32H573i-DK, and my device had FLASH_OTPBLR programmed to 0x00000009. That's differences against tutorial.


Edit: problem solved - /NRST pin wrong connection .


Thank you.


Slavomir T.

Version history
Last update:
‎2024-06-10 02:33 AM
Updated by: