Implementing debug authentication on STM32H5 using CLI tools

Ruchit N · ‎2024-01-10

Introduction

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.

Summary

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:

Create a provisioning file (.obk file) containing the hash of the debug authentication password to be used while provisioning.
Generating and programming firmware on the STM32H5 MCU
Move product state to PROVISIONING.
Provision to the MCU with the .obk file.
Move the product state to CLOSED to close all the unauthorized debug accesses.
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

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

Environment Setup

Hardware:

Nucleo board NUCLEO-H563ZI or discovery board STM32H573I-DK

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

Software:

STM32CubeProgrammer v2.14.0 or above
STM32TrustedPackageCreator v2.14.0 or above (included in the STM32CubeProgrammer install)
STM32CubeIDE v2.13.1 or above
STM32CubeH5 software package v1.1.1 or above

Introduction

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.

Open the GPIO_IOToggle or any other desired project in STM32CubeIDE or any other preferred IDE.
Build the project.

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:

..\en.stm32cubeh5-vx-x-x\STM32Cube_FW_H5_Vx.x.x\Projects\NUCLEO-H563ZI\ROT_Provisioning\DA\Config\DA_ConfigWithPassword.xml

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.

References:

SToma · ‎2024-04-04

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.

Regards,

Slavomir T.

minchingho_span · ‎2024-07-18

Hi, I have accidentally set the option byte PRODUCT_STATE=0x17 and the device is locked and shows the following when I do DA discover

10:58:30 : STM32CubeProgrammer API v2.17.0 | Windows-64Bits 
10:58:34 : UR connection mode is defined with the HWrst reset mode
10:58:34 : ST-LINK SN  : 0006001B4741500120383733
10:58:34 : ST-LINK FW  : V3J15M6
10:58:34 : Board       : NUCLEO-H563ZI
10:58:34 : Voltage     : 3.28V
10:58:34 : Error: ST-LINK error (DEV_CONNECT_ERR)
10:58:48 : Start STLinkUpgrade...
10:59:10 : UR connection mode is defined with the HWrst reset mode
10:59:10 : ST-LINK SN  : 0006001B4741500120383733
10:59:10 : ST-LINK FW  : V3J15M6
10:59:10 : Board       : NUCLEO-H563ZI
10:59:10 : Voltage     : 3.28V
10:59:10 : Error: ST-LINK error (DEV_CONNECT_ERR)
10:59:22 : Start Debug Authentication Sequence
10:59:22 : SDMOpen                       :   602 : open       : SDM API v1.0
10:59:22 : SDMOpen                       :   603 : open       : SDM Library version v1.1.0
10:59:22 : open_comms                    :   495 : open       : Asserting target reset
10:59:22 : open_comms                    :   499 : open       : Writing magic number
10:59:22 : open_comms                    :   509 : open       : De-asserting target reset
10:59:22 : open_comms                    :   561 : open       : Communication with the target established successfully
10:59:22 : discovery: target ID.......................:0x484
10:59:22 : discovery: SoC ID..........................:0x00000000_00000000_00000000_00000000
10:59:22 : discovery: SDA version.....................:2.1.0
10:59:22 : discovery: Vendor ID.......................:STMicroelectronics
10:59:22 : discovery: PSA lifecycle...................:ST_LIFECYCLE_PROVISIONING
10:59:22 : discovery: PSA auth version................:1.0
10:59:22 : discovery: ST HDPL1 status.................:0xffffffff
10:59:22 : discovery: ST HDPL2 status.................:0xffffffff
10:59:22 : discovery: ST HDPL3 status.................:0xffffffff
10:59:22 : discovery: Token Formats...................:0x200
10:59:22 : discovery: Certificate Formats.............:0x201
10:59:22 : discovery: cryptosystems...................:ST Password
10:59:22 : discovery: ST provisioning integrity status:0xf5f5f5f5
10:59:22 : discovery: permission if authorized...........:Full Regression
11:02:40 : UR connection mode is defined with the HWrst reset mode
11:02:40 : ST-LINK SN  : 0006001B4741500120383733
11:02:40 : ST-LINK FW  : V3J15M6
11:02:40 : Board       : NUCLEO-H563ZI
11:02:40 : Voltage     : 3.28V
11:02:40 : Error: ST-LINK error (DEV_CONNECT_ERR)
11:02:55 : Error: Connection to target must be established before performing this operation.
11:03:08 : Start Debug Authentication Sequence
11:03:08 : SDMOpen                       :   602 : open       : SDM API v1.0
11:03:08 : SDMOpen                       :   603 : open       : SDM Library version v1.1.0
11:03:08 : open_comms                    :   495 : open       : Asserting target reset
11:03:08 : open_comms                    :   499 : open       : Writing magic number
11:03:08 : open_comms                    :   509 : open       : De-asserting target reset
11:03:08 : open_comms                    :   561 : open       : Communication with the target established successfully
11:03:08 : discovery: target ID.......................:0x484
11:03:08 : discovery: SoC ID..........................:0x00000000_00000000_00000000_00000000
11:03:08 : discovery: SDA version.....................:2.1.0
11:03:08 : discovery: Vendor ID.......................:STMicroelectronics
11:03:08 : discovery: PSA lifecycle...................:ST_LIFECYCLE_PROVISIONING
11:03:08 : discovery: PSA auth version................:1.0
11:03:08 : discovery: ST HDPL1 status.................:0xffffffff
11:03:08 : discovery: ST HDPL2 status.................:0xffffffff
11:03:08 : discovery: ST HDPL3 status.................:0xffffffff
11:03:08 : discovery: Token Formats...................:0x200
11:03:08 : discovery: Certificate Formats.............:0x201
11:03:08 : discovery: cryptosystems...................:ST Password
11:03:08 : discovery: ST provisioning integrity status:0xf5f5f5f5
11:03:08 : discovery: permission if authorized...........:Full Regression
11:07:08 : UR connection mode is defined with the HWrst reset mode
11:07:08 : ST-LINK SN  : 0006001B4741500120383733
11:07:08 : ST-LINK FW  : V3J15M6
11:07:08 : Board       : NUCLEO-H563ZI
11:07:08 : Voltage     : 3.28V
11:07:08 : Error: Cannot connect to access port 1!  If you are trying to connect to a device with TrustZone enabled please try to connect with HotPlug mode.  If you are trying to connect to a device which supports Debug Authentication with certificate or password, please open your device using it.
11:07:12 : UR connection mode is defined with the HWrst reset mode
11:07:12 : ST-LINK SN  : 0006001B4741500120383733
11:07:12 : ST-LINK FW  : V3J15M6
11:07:12 : Board       : NUCLEO-H563ZI
11:07:12 : Voltage     : 3.28V
11:07:12 : Error: Cannot connect to access port 1!  If you are trying to connect to a device with TrustZone enabled please try to connect with HotPlug mode.  If you are trying to connect to a device which supports Debug Authentication with certificate or password, please open your device using it.
11:07:18 : Start Debug Authentication Sequence
11:07:18 : SDMOpen                       :   602 : open       : SDM API v1.0
11:07:18 : SDMOpen                       :   603 : open       : SDM Library version v1.1.0
11:07:18 : open_comms                    :   495 : open       : Asserting target reset
11:07:18 : open_comms                    :   499 : open       : Writing magic number
11:07:18 : open_comms                    :   509 : open       : De-asserting target reset
11:07:18 : open_comms                    :   561 : open       : Communication with the target established successfully
11:07:18 : discovery: target ID.......................:0x484
11:07:18 : discovery: SoC ID..........................:0x00000000_00000000_00000000_00000000
11:07:18 : discovery: SDA version.....................:2.1.0
11:07:18 : discovery: Vendor ID.......................:STMicroelectronics
11:07:18 : discovery: PSA lifecycle...................:ST_LIFECYCLE_PROVISIONING
11:07:18 : discovery: PSA auth version................:1.0
11:07:18 : discovery: ST HDPL1 status.................:0xffffffff
11:07:18 : discovery: ST HDPL2 status.................:0xffffffff
11:07:18 : discovery: ST HDPL3 status.................:0xffffffff
11:07:18 : discovery: Token Formats...................:0x200
11:07:18 : discovery: Certificate Formats.............:0x201
11:07:18 : discovery: cryptosystems...................:ST Password
11:07:18 : discovery: ST provisioning integrity status:0xf5f5f5f5
11:07:18 : discovery: permission if authorized...........:Full Regression

I have not provide any obk or password. How can I unlock a device from this state? We have several devices in a state like this. It will be super useful if we can recover from this.