Tamper configuration: Difference between revisions

Latest revision as of 16:32, 25 July 2024↑

Applicable for

STM32MP13x lines, STM32MP15x lines, Unknown MPU

1. Overview↑

The STM32 MPUs embed a tamper detection management system.

The tamper management and configuration functions have been added to the OP-TEE secure OS to protect against external attacks when the system is running. The tamper management is also present in the TF-A BL2 because tamper events can occur when the SoC is in low-power or power-off modes.

When a tamper event occurs, the platform's secrets are erased or blocked. The automatic erase mode of all secrets can be configured for some tampers. It is enabled by default but can be turned off (see TAMP device tree configuration) if the user application needs to control erase operations. The platform secrets access is blocked when erase is on-going.

Except for STM32MP15x lines , the tampers can be configured in 2 modes:

Confirmed mode: immediate erase of secrets on tamper detection, including backup registers erase
Potential mode: Some of the secrets are instead locked following a tamper detection until a software action.

On STM32MP15x lines , the secrets will be erased.

To learn more about which secrets are erased or blocked in which modes, refer to the TAMP interconnection in the TAMP chapter of the SoC reference manual.

Information

Because STMicroelectronics cannot provide generic sequences on how to handle tampers, someone wishing to use tampers is expected to customize the tampers interrupt handler sequence. The default behavior when a tamper event occurs is a system reset when running. When the tamper is in confirmed mode, the appropriate secret erase sequence is also performed by the hardware. Whereas in potential mode, the secrets are blocked but not erased until the handler sequence is performed. The files to custom are TF-A BL2 platform setup (when a tamper event happens when the SoC is in retention mode) and OP-TEE tamper driver for runtime management

1.1. Internal tampers↑

The table below represents the list of the supported internal tampers.

	STM32MP13x lines	STM32MP15x lines	STM32MP25 unknown microprocessor device
Backup voltage domain monitoring	✓	✓	✓
Temperature monitoring	✓	✓	✓
LSE monitoring	✓	✓	✓
HSE monitoring	✓	✓	✓
RTC calendar overflow	✓	✓	✓
Monotonic counter (1) overflow	✓	✓	✓
JTAG/SWD access	✓	✓	✓
Cryptographic IPs fault (SAES or CRYP or PKA or TRNG)	✓		✓
Monotonic counter 2 overflow	✓		✓
IWDG reset when tamper flag is set	✓		IWDG1/2/5✓
ADC2 analog watchdog monitoring 1	✓
ADC2 analog watchdog monitoring 2	✓
ADC2 analog watchdog monitoring 3	✓
VDDCORE monitoring under/over voltage			✓
LPSRAM1 CRC fail (same signal as IWDG5 reset)			✓

1.2. External tampers↑

External tampers can be defined on all MPUs:

3 on STM32MP15x lines
8 on STM32MP13x lines
8 on STM32MP25 unknown microprocessor device

The external tampers can be configured as passive (they detect a level or an edge on one pin) or as active (2 pins have to be linked together, and the TAMP hardware regularly sends a random level on the OUT pin, then reads IN pins and raises the tamper flag if the values mismatch). Note that the number of mismatch before a tamper event is raised can be configured.

2. Software configuration↑

2.1. Default internal tampers configuration↑

Be aware that some of the internal tampers require other feature to be functional(LSE/HSE monitoring, voltage monitoring). Refer to the TAMP chapter of the SoC reference manual to learn more on this subject.

Warning

Because it monitors the LSE oscillator used for the retention domain, a LSE monitoring internal tamper event must be followed by either a reset of the backup domain or a custom sequence. For the latter, please modify the code in TF-A BL2 platform setup and OP-TEE tamper driver

For STM32MP13x lines :

By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the TAMP common property list

For STM32MP15x lines :

By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the TAMP common property list

For STM32MP25 unknown microprocessor device:

By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the TAMP common property list

2.2. Default external tampers configuration↑

For STMicroelectronics boards and except for STM32MP15x lines platforms, the TAMP button is default supported to generate tamper events. This is done in the board device tree file. See: Board device tree configuration

@@ Line 1: / Line 1: @@
 <noinclude>{{ApplicableFor
-|MPUs list=STM32MP13x, STM32MP15x
+|MPUs list=STM32MP13x, STM32MP15x, STM32MP25x
-|MPUs checklist=STM32MP13x, STM32MP15x
+|MPUs checklist=STM32MP13x, STM32MP15x, STM32MP25x
 }}</noinclude>
 == Overview ==
-The STM32 MPUs embed tamper detection management system.
+The STM32 MPUs embed a tamper detection management system.
-The tamper management and configuration functions have been added to the secure OS to select and detect events to protect against external attacks.
+The tamper management and configuration functions have been added to the [[STM32 MPU OP-TEE_overview|OP-TEE]] secure OS to protect against external attacks when the system is running. The tamper management is also present in the [[TF-A overview|TF-A]] BL2 because tamper events can occur when the SoC is in low-power or power-off modes.
-On a tamper event, secrets are erased or blocked.
+When a tamper event occurs, the platform's secrets are erased or blocked.
+The automatic erase mode of all secrets can be configured for some tampers. It is enabled by default but can be turned off (see [[TAMP device tree configuration]]) if the user application needs to control erase operations. The platform secrets access is blocked when erase is on-going.
-The backup registers and backup SRAM (configurable on {{MicroprocessorDevice | device=13}}) are considered as secrets.
+Except for {{MicroprocessorDevice | device=15}}, the tampers can be configured in 2 modes:
+* Confirmed mode: immediate erase of secrets on tamper detection, including backup registers erase
+* Potential mode: Some of the secrets are instead locked following a tamper detection until a software action.
-On {{MicroprocessorDevice | device=13}}, the security level has been increased and the following preripheral have been added to the secret list:
+On {{MicroprocessorDevice | device=15}}, the secrets will be erased.
-* [[STM32MP13_SRAM_internal_memory|SRAM3]]
-* [[SAES_internal_peripheral|SAES]]
-* [[HASH_internal_peripheral|HASH]]
-* [[PKA_internal_peripheral|PKA]]
-* [[BSEC_internal_peripheral|BSEC]]
-The automatic erase mode can be configured for any tampers (internal and external). It is enabled by default but can be turned off (NOERASE) if the user application needs to control erase operations. If disabled the backup registers, [[STM32MP13_SRAM_internal_memory|SRAM3]], and RHUK (root hardware unique key) in [[BSEC_internal_peripheral|BSEC]] are locked (no read nor write are possible until event acknowledged), and [[SAES_internal_peripheral|SAES]], [[HASH_internal_peripheral|HASH]] peripherals and [[PKA_internal_peripheral|PKA]] SRAM are always erased.
+To learn more about which secrets are erased or blocked in which modes, refer to the TAMP interconnection in the TAMP chapter of the [[STM32 MPU resources#Reference manuals|SoC reference manual]].
+{{Info | Because STMicroelectronics cannot provide generic sequences on how to handle tampers, someone wishing to use tampers is expected to customize the tampers interrupt handler sequence. The default behavior when a tamper event occurs is a system reset when running. When the tamper is in confirmed mode, the appropriate secret erase sequence is also performed by the hardware. Whereas in potential mode, the secrets are blocked but not erased until the handler sequence is performed. The files to custom are  {{CodeSource | TF-A | plat/st/stm32mp1/bl2_plat_setup.c | TF-A BL2 platform setup}} (when a tamper event happens when the SoC is in retention mode) and {{CodeSource | OP-TEE_OS | core/drivers/stm32_tamp.c | OP-TEE tamper driver}} for runtime management }}
 === Internal tampers ===
@@ Line 29: / Line 29: @@
 ! scope="col" | {{MicroprocessorDevice | device=13}}
 ! scope="col" | {{MicroprocessorDevice | device=15}}
+! scope="col" | {{MicroprocessorDevice | device=25}}
 |-
 ! scope="row" | Backup voltage domain monitoring
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | Temperature monitoring
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | LSE monitoring
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | HSE monitoring
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | RTC calendar overflow
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | Monotonic counter (1) overflow
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 | <span title="internal tamper available" style="font-size:21px">✓</span>
@@ Line 56: / Line 63: @@
 ! scope="row" | JTAG/SWD access
 | <span title="internal tamper available" style="font-size:21px">✓</span>
-|
+| <span title="internal tamper available" style="font-size:21px">✓</span>
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | Cryptographic IPs fault (SAES or CRYP or PKA or TRNG)
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | Monotonic counter 2 overflow
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 |-
 ! scope="row" | IWDG reset when tamper flag is set
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |
+| <span title="internal tamper available" style="font-size:21px">IWDG1/2/5✓</span>
 |-
 ! scope="row" | ADC2 analog watchdog monitoring 1
 | <span title="internal tamper available" style="font-size:21px">✓</span>
+|
 |
 |-
 ! scope="row" | ADC2 analog watchdog monitoring 2
 | <span title="internal tamper available" style="font-size:21px">✓</span>
+|
 |
 |-
@@ Line 81: / Line 94: @@
 | <span title="internal tamper available" style="font-size:21px">✓</span>
 |
+|
+|-
+! scope="row" | VDDCORE monitoring under/over voltage
+|
+|
+| <span title="internal tamper available" style="font-size:21px">✓</span>
+|-
+! scope="row" | LPSRAM1 CRC fail (same signal as IWDG5 reset)
+|
+|
+| <span title="internal tamper available" style="font-size:21px">✓</span>
 |}
 === External tampers ===
-external tampers on {{MicroprocessorDevice | device=15}} and 8 on  {{MicroprocessorDevice | device=13}} can be defined.
+External tampers can be defined on all MPUs:
+* 3 on {{MicroprocessorDevice | device=15}}
+* 8 on {{MicroprocessorDevice | device=13}}
+* 8 on {{MicroprocessorDevice | device=25}}
 The external tampers can be configured as passive (they detect a level or an edge on one pin) or as active (2 pins have to be linked together, and the TAMP hardware regularly sends a random level on the OUT pin, then reads IN pins and raises the tamper flag if the values mismatch). Note that the number of mismatch before a tamper event is raised can be configured.
 == Software configuration ==
-The tamper driver only exists in [[OP-TEE_overview|OP-TEE]]. <br>
+=== Default internal tampers configuration ===
+Be aware that some of the internal tampers require other feature to be functional(LSE/HSE monitoring, voltage monitoring). Refer to the TAMP chapter of the [[STM32 MPU resources#Reference manuals|SoC reference manual]] to learn more on this subject.
-External tampers have to be configured in [[TAMP device tree configuration| device tree]].
-Internal and external tampers have to be activated in {{CodeSource|OP-TEE_OS|core/arch/arm/plat-stm32mp1/main.c|main configuration file}}.
-The device tree enables the TAMP IP and configures the external tamper (active, passive, level, and so on).
-The {{CodeSource|OP-TEE_OS|core/arch/arm/plat-stm32mp1/main.c|main.c}} activates the desired TAMPER_ID, in ERASE or NOERASE mode and defines which is the callback in case of an event. An external TAMPER can be activated only if the corresponding TAMPER_ID is enabled in the device tree.
-Example :
-<pre>
-static uint32_t int_tamp1_callback(int id) {
-	MSG("Backup domain voltage threshold monitoring tamper event occurs");
-	/* ... */
-	/* specific application event management */
-	/* ... */
-	return TAMP_CB_ACK_AND_RESET;
-}
-stm32_tamp_activate(INT_TAMP1, TAMP_ERASE, tamp1_callback);
-</pre>
-The value returned by the callback defines if the driver acknowledges the event, and resets the board.
-If the event is configured as NOERASE, the callback may check:
-* in case of true positive: erase manually secret (with stm32_tamp_erase_secret()) and returns TAMP_CB_ACK_AND_RESET
-* in case of false positive: returns TAMP_CB_ACK (it unlocks the secret IPs).
-The {{CodeSource|OP-TEE_OS|core/arch/arm/plat-stm32mp1/main.c|main.c}} configures the permission access of the TAMP register (privileged mode, secure mode), and it shows if the backup SRAM is included in the secret IPs list.
+{{Warning | Because it monitors the LSE oscillator used for the retention domain, a LSE monitoring internal tamper event must be followed by either a reset of the backup domain or a custom sequence. For the latter, please modify the code in {{CodeSource | TF-A | plat/st/stm32mp1/bl2_plat_setup.c | TF-A BL2 platform setup}} and {{CodeSource | OP-TEE_OS | core/drivers/stm32_tamp.c | OP-TEE tamper driver}} }}
-=== Default internal tampers configuration ===
 For {{MicroprocessorDevice | device=13}}:
-* By default, only internal tampers 1, 2, 3 , 4, 7, 12 and 13 are enabled, configured as ERASE, and the callback resets the board.
+* By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the [[TAMP device tree configuration#Common TAMP node append | TAMP common property list]]
 For {{MicroprocessorDevice | device=15}}:
-*By default, only internal tampers 1, 2, 3 , 4 are enabled, configure as ERASE, and the callback will reset the board.
+* By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the [[TAMP device tree configuration#Common TAMP node append | TAMP common property list]]
+For {{MicroprocessorDevice | device=25}}:
+* By default, there is no internal tamper enabled. If you wish to enable one or more of them, please refer to the [[TAMP device tree configuration#Common TAMP node append | TAMP common property list]]
-=== External tampers ===
+=== Default external tampers configuration ===
-On the {{Board | type=135F-DK | name=short}}, a tamper button is connected to the external tamper 2. It is default enable in the device tree.  Pressing the TAMP button raises the EXT_TAMP2 event, erases all secrets and resets the board.
+For STMicroelectronics boards and except for {{MicroprocessorDevice | device=15}} platforms, the TAMP button is default supported to generate tamper events. This is done in the board device tree file. See: [[TAMP device tree configuration#DT configuration (board level) | Board device tree configuration]]