OP-TEE Firewall Framework

Applicable for

STM32MP13x lines STM32MP15x lines STM32MP23x lines STM32MP25x lines

1. Framework purpose[edit | edit source]

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

2. Firewall controllers[edit | edit source]

On STM32MP1 series, the firewall controllers are the ETZPC for peripherals and internal RAMs protection, GPIO for pin control protection and the TZC400 for the DDR memory protection.

On STM32MP2 series, the firewall controllers are GPIO for pin control protection, the RISABs for internal RAMS protection, the RISAFs for external memories protection, and the RIFSC for peripherals and LPSRAMs protection.

3. Framework usage[edit | edit source]

This framework can be used to:

Check a device or memory firewall's 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 to query a current firewall access rights configuration and to query 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's possible to forge firewall queries by hand, the device tree support is mandatory to use this framework.

4. Framework APIs[edit | edit source]

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

5. Configuration[edit | edit source]

5.1. Build configuration[edit | edit source]

The firewall framework is embedded when CFG_DRIVERS_FIREWALL=y

5.2. Device tree configuration[edit | edit source]

Devices are linked with their firewall controller thanks to the "access-controllers" property. This property does not represent the configuration to apply. It rather defines the reference to the firewall controller that controls the access rights to the resource represented by the node the property is located in. Therefore "access-controllers" properties are defined in the SoC DTSI files for each device and shouldn't be modified. It is possible to give each entry a name 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 update of access rights are described with the "access-controllers-conf-xxx" property. It is a set of one or more firewall controller phandle with their relative arguments. The number of arguments depends on the firewall controller and is implementation dependent. Example below:

&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 should be extracted from DT and applied using dedicated firewall configuration APIs

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

6. How to debug[edit | edit source]

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

7. Source code location[edit | edit source]

Firewall framework:

8. References[edit | edit source]

Template:ToBeReviewedByTW