OP-TEE Firewall Framework

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

---

1. Framework purpose

The OP-TEE firewall framework allows the user to grant and check access rights and reconfigure the firewall settings of devices and memory. It serves as a link between devices and their firewall controller.

2. Firewall controllers

For the STM32MP1 series, the firewall controllers are the ETZPC for peripheral and internal RAM protection, GPIO for pin control protection, and the TZC400 for DDR memory protection.

For the STM32MP2 series, the firewall controllers are GPIO for pin control protection, the RISABs for internal RAMS protection, the RISAFs for external memory protection, and the RIFSC for peripheral and LPSRAM protection.

3. Framework usage

This framework can be used to:

• Check a device or memory firewall configuration for an entity.
• Grant access to OP-TEE for a device or a memory, if accessible.
• Dynamically update the firewall configuration.

The firewall framework allows the user to query the current access right configuration of the firewall and the loading of new access right settings. A firewall query contains a reference to the firewall controller to reach and arguments that are implementation-dependent. A firewall configuration is a set of one or more queries.

Information

The OP-TEE firewall framework uses information in the device tree configuration. While it is possible to forge firewall queries manually, the device tree support is mandatory to use this framework.

4. Framework APIs

A firewall controller driver must be registered to the firewall framework as a controller through firewall APIs .
Device drivers must interact with firewall controllers through firewall device APIs .

5. Configuration

5.1. Build configuration

The firewall framework is embedded when CFG_DRIVERS_FIREWALL=y.

5.2. Device tree configuration

Devices are linked to their firewall controller with the "access-controllers" property. This property does not represent the configuration to apply. It defines the reference to the firewall controller that controls the access rights to the resource represented by the node the property is located in.

"access-controllers" properties are defined in the SoC DTSI files for each device and must not be modified. It is possible to name each entry with the "access-controllers-names" property.

ltdc: display-controller@48010000 {
     compatible = "st,stm32-ltdc";
     reg = <0x48010000 0x400>;
     interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>,
                  <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>;
     clocks = <&rcc CK_BUS_LTDC>, <&rcc CK_KER_LTDC>;
     clock-names = "bus", "lcd";
     resets = <&rcc LTDC_R>;
     status = "disabled";
     access-controllers = <&rifsc STM32MP25_RIFSC_LTDC_CMN_ID>;
     access-controller-names = "cmn"; 
     
     l1l2 {
          access-controllers = <&rifsc STM32MP25_RIFSC_LTDC_L0L1_ID>;
          access-controller-names = "l1l2";
     };
     l3 {
          access-controllers = <&rifsc STM32MP25_RIFSC_LTDC_L2_ID>;
          access-controller-names = "l3";
     };
     rot {
          access-controllers = <&rifsc STM32MP25_RIFSC_LTDC_ROT_ID>;
          access-controller-names = "rot";
     };
};

Firewall configurations for dynamic updating of access rights are described with the "access-controllers-conf-xxx" property. It is a set of one or more firewall controller phandles with their relative arguments. The number of arguments depends on the firewall controller and is implementation-dependent. For example:

&ltdc {
     access-controllers-conf-nsec = <&rifsc RIFPROT(STM32MP25_RIFSC_LTDC_CMN_ID, RIF_UNUSED, RIF_UNLOCK, RIF_NSEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)>,
                                    <&rifsc RIFPROT(STM32MP25_RIFSC_LTDC_L2_ID, RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)>,
                                    <&rifsc RIMUPROT(RIMU_ID(12), RIF_CID4, RIF_SEC, RIF_PRIV, RIF_CIDSEL_M)>;
     access-controllers-conf-sec = <&rifsc RIFPROT(STM32MP25_RIFSC_LTDC_CMN_ID, RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)>,
                                   <&rifsc RIFPROT(STM32MP25_RIFSC_LTDC_L2_ID, RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)>,
                                   <&rifsc RIMUPROT(RIMU_ID(12), RIF_CID4, RIF_SEC, RIF_PRIV, RIF_CIDSEL_M)>;
};

Information

Firewall configuration must be extracted from DT and applied using dedicated firewall configuration APIs

Another usage example is the signed remote processor firmware loading using OP-TEE. Refer to the How to protect the coprocessor firmware wiki page.

6. How to debug

Refer to the How to debug OP-TEE wiki article.

7. Source code location

Firewall framework:

• core/drivers/firewall/firewall.c
• core/include/drivers/firewall.h
• core/include/drivers/firewall_device.h

Open portable trusted execution environment

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Doubledata rate (memory domain)

Generic interrupt controller

Serial peripheral interface

LCD TFT display controller (STM32 specific)

Resource Isolation Framework Security Controller - NEW

Resource Isolation Framework

Resource Isolation Master Unit - NEW

Device tree