diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt index 864e61dcd..4d3f9ce8c 100644 --- a/configs/AM62AX/AM62AX_linux_toc.txt +++ b/configs/AM62AX/AM62AX_linux_toc.txt @@ -97,6 +97,7 @@ linux/Foundational_Components/Power_Management/pm_debug linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot +linux/Foundational_Components/System_Security/Memory_Firewalls linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62LX/AM62LX_linux_toc.txt b/configs/AM62LX/AM62LX_linux_toc.txt index 8fddf4553..77c1cedca 100644 --- a/configs/AM62LX/AM62LX_linux_toc.txt +++ b/configs/AM62LX/AM62LX_linux_toc.txt @@ -83,6 +83,7 @@ linux/Foundational_Components/Power_Management/pm_am62lx_debug linux/Foundational_Components/System_Security/Security_overview #linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot +linux/Foundational_Components/System_Security/Memory_Firewalls linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt index 8a674fc8b..19fbc36ee 100644 --- a/configs/AM62PX/AM62PX_linux_toc.txt +++ b/configs/AM62PX/AM62PX_linux_toc.txt @@ -102,6 +102,7 @@ linux/Foundational_Components/Power_Management/pm_debug linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot +linux/Foundational_Components/System_Security/Memory_Firewalls linux/Foundational_Components_Kernel_Users_Guide linux/Foundational_Components_Kernel_LTP-DDT_Validation diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt index 4afac2be7..adccc62e0 100644 --- a/configs/AM62X/AM62X_linux_toc.txt +++ b/configs/AM62X/AM62X_linux_toc.txt @@ -99,6 +99,7 @@ linux/Foundational_Components/Power_Management/pm_debug linux/Foundational_Components/System_Security/Security_overview linux/Foundational_Components/System_Security/SELinux linux/Foundational_Components/System_Security/Auth_boot +linux/Foundational_Components/System_Security/Memory_Firewalls linux/Foundational_Components_PRU_Subsystem linux/Foundational_Components/PRU-ICSS-Linux-Drivers diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt index 162546a25..493e99c6f 100644 --- a/configs/AM64X/AM64X_linux_toc.txt +++ b/configs/AM64X/AM64X_linux_toc.txt @@ -84,6 +84,7 @@ linux/Foundational_Components_Kernel_LTP-DDT_Validation linux/Foundational_Components_Kernel_FAQs linux/Foundational_Components_Security linux/Foundational_Components/System_Security/Security_overview +linux/Foundational_Components/System_Security/Memory_Firewalls linux/Foundational_Components_Machine_Learning linux/Foundational_Components/Machine_Learning/arm_compute_library linux/Foundational_Components/Machine_Learning/armnn diff --git a/source/linux/Foundational_Components/System_Security/Memory_Firewalls.rst b/source/linux/Foundational_Components/System_Security/Memory_Firewalls.rst new file mode 100644 index 000000000..f3bb5fb7f --- /dev/null +++ b/source/linux/Foundational_Components/System_Security/Memory_Firewalls.rst @@ -0,0 +1,119 @@ +.. _memory-firewalls: + +################ +Memory Firewalls +################ + +******** +Overview +******** + +TI System-on-Chips (SoCs) use hardware-backed firewalls to enforce +access control. Texas Instruments Foundational Security (TIFS) +configures these firewalls to restrict the components that can access +specific regions of device-mapped memory. Other components such as +Open Portable Trusted Execution Environment (OP-TEE), Arm Trusted +Firmware (ATF), Linux, U-Boot, and user-space programs can request TIFS +to configure firewalls on their behalf. + +Firewalls can restrict access based on: + +* **Core**: A53, R5, M4 +* **Privilege level**: privileged or non-privileged +* **Security state**: secure or insecure + +For example, TIFS might configure a firewall to prevent Linux (running +on A53) from accessing a memory region reserved for the secure world. + +For more information about firewalls, see the Technical Reference +Manual (TRM) for the specific SoC, the +`TISCI Firewall API `__, +and the +`TIFS Firewall FAQ `__. + +**************************************** +What Happens During a Firewall Violation +**************************************** + +When software attempts an unauthorized access to a memory region that +a firewall protects, the firewall blocks the access and triggers an +exception. The outcome depends on the type of access: + +* **Read access**: The firewall blocks the read. The system continues + running. +* **Write access**: The firewall blocks the write and crashes the + Linux kernel. The system halts. + +The kernel crash on write violations stops the offending software +immediately, preventing further unauthorized access attempts. + +TIFS logs information about every firewall exception. The rest of this +document explains how to trigger exceptions, enable TIFS logs, access +them, and interpret them. + +******************************* +Triggering a Firewall Exception +******************************* + +To test firewall behavior, use ``k3conf`` to read from or write to a +protected memory region. + +Triggering a read exception: + +.. code-block:: console + + k3conf read [] + +Triggering a write exception (this will crash the kernel): + +.. code-block:: console + + k3conf write + +Replace ```` with the address of a firewall-protected region, +```` with the number of bytes to read, and ```` with the +value to write. + +****************** +Enabling TIFS Logs +****************** + +TIFS does not output logs by default. Enabling TIFS logging requires +modifying U-Boot source code, recompiling it, and transferring the new +binaries to the boot partition. + +Modify U-Boot Configuration +=========================== + +Open :file:`board/ti//board-cfg.yaml` in the U-Boot source +tree. Locate ``trace_dst_enables`` and ``trace_src_enables``, which +U-Boot sets to ``0x0`` by default. Change these values as follows: + +* ``trace_dst_enables``: change from ``0x0`` to ``0xD`` +* ``trace_src_enables``: change from ``0x0`` to ``0x3F`` + +Build and Deploy U-Boot +======================= + +After making these changes, compile U-Boot and transfer the resulting +binaries to the board's boot partition. See +:ref:`u-boot-build-guide-build-k3` for build instructions. + +******************* +Accessing TIFS Logs +******************* + +TIFS outputs logs to a separate serial port from the Linux console. +If the Linux command line is accessible through :file:`/dev/ttyUSB0`, TIFS logs +are typically accessible through :file:`/dev/ttyUSB1`. However, the exact device +assignment depends on the hardware setup and the order in which the +host enumerates USB devices. + +Open the TIFS serial port with a terminal emulator to view the logs. + +********************** +Interpreting TIFS Logs +********************** + +For information about interpreting firewall exception logs, see the +`TIFS Firewall FAQ `__. diff --git a/source/linux/Foundational_Components/System_Security/Security_overview.rst b/source/linux/Foundational_Components/System_Security/Security_overview.rst index 578505d03..14867038f 100644 --- a/source/linux/Foundational_Components/System_Security/Security_overview.rst +++ b/source/linux/Foundational_Components/System_Security/Security_overview.rst @@ -61,6 +61,10 @@ The following table lists some of the key Security Features: | | Trusted Execution Environment that enables isolated | :ref:`foundational-components-optee` | | | execution of security-sensitive applications and services | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ + | **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` | + | | security boundaries | | + +-------------------------+-----------------------------------------------------------+--------------------------------------+ + .. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62PX', 'AM62AX') @@ -83,6 +87,9 @@ The following table lists some of the key Security Features: | | Trusted Execution Environment that enables isolated | :ref:`foundational-components-optee` | | | execution of security-sensitive applications and services | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ + | **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` | + | | security boundaries | | + +-------------------------+-----------------------------------------------------------+--------------------------------------+ .. ifconfig:: CONFIG_part_variant not in ('AM62X', 'AM62PX', 'AM62AX', 'AM62LX') @@ -99,4 +106,7 @@ The following table lists some of the key Security Features: | | Trusted Execution Environment that enables isolated | :ref:`foundational-components-optee` | | | execution of security-sensitive applications and services | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ + | **Memory Firewalls** | Prevents unauthorized access through hardware-enforced | :ref:`memory-firewalls` | + | | security boundaries | | + +-------------------------+-----------------------------------------------------------+--------------------------------------+ diff --git a/source/linux/Foundational_Components_Security.rst b/source/linux/Foundational_Components_Security.rst index 15a267e1e..904f03020 100644 --- a/source/linux/Foundational_Components_Security.rst +++ b/source/linux/Foundational_Components_Security.rst @@ -12,3 +12,4 @@ Security Foundational_Components_Secure_Boot Foundational_Components/System_Security/SELinux Foundational_Components/System_Security/Auth_boot + Foundational_Components/System_Security/Memory_Firewalls