| Gabor Toth | 07b5ebf | 2024-07-01 17:19:27 +0200 | [diff] [blame] | 1 | Supported Architectural Features |
| 2 | ================================ |
| 3 | |
| Gyorgy Szing | c6450a0 | 2024-10-28 10:44:29 +0100 | [diff] [blame] | 4 | .. _branch_protection: |
| 5 | |
| Gabor Toth | 07b5ebf | 2024-07-01 17:19:27 +0200 | [diff] [blame] | 6 | Branch Protection |
| 7 | ----------------- |
| 8 | |
| 9 | Branch protection covers two architecture features for mitigating Return Oriented Programming (ROP) and Jump Oriented |
| 10 | Programming (JOP) attacks. For generic overview of these features please see |
| 11 | `Providing protection for complex software`_. |
| 12 | |
| 13 | Branch Protection related hardware features can not be controlled from S-EL0 and to enable these co-operation with |
| 14 | components running at higher exception levels is needed. Please refer to the documentation of the these components for |
| 15 | information on how to enable these HW features. |
| 16 | |
| 17 | Pointer Authentication (FEAT_PAUTH) |
| 18 | ''''''''''''''''''''''''''''''''''' |
| 19 | |
| 20 | Pointer Authentication (PAC) is an ARMv8.3 feature where the return address of each function is signed. The signature is |
| 21 | calculated when the function is called and verified upon returning. This is to ensure the return address has not been |
| 22 | tampered with. |
| 23 | |
| 24 | Branch Target Identification (FEAT_BTI) |
| 25 | ''''''''''''''''''''''''''''''''''''''' |
| 26 | |
| 27 | Branch Target Identification (BTI) is an ARMv8.5 feature which is used to guard against the execution of instructions |
| 28 | that are not the intended target of an indirect branch. |
| 29 | |
| 30 | For raw-binary SPs the TS build system will will mark the executable regions with the BTI attribute in the SP manifest |
| 31 | file. The SPMC implementation running the SP is required to support this memory attribute, or has to unconditionally |
| 32 | enable BTI for all executable regions to get the feature working. |
| 33 | |
| 34 | Although GCC has BTI support since v9, no BTI enabled libraries are shipped with the current GNUARM releases. A possible |
| 35 | workaround is to compile from source as described in the `FAQ section of the OP-TEE documentation`_. |
| 36 | |
| 37 | Configuring Branch Protection in the TS build system |
| 38 | '''''''''''''''''''''''''''''''''''''''''''''''''''' |
| 39 | |
| 40 | The feature can be controlled using the ``BRANCH_PROTECTION`` variable. This can be set e.g. on the cmake command line |
| 41 | by passing ``-DBRANCH_PROTECTION=<value>``. The default value is ``unset``. Please refer to `GCC manual`_ for the |
| 42 | detailed description of the values. |
| 43 | |
| 44 | .. list-table:: Supported values of ``BRANCH_PROTECTION`` |
| 45 | :name: branch_protection_table |
| 46 | :header-rows: 1 |
| 47 | |
| 48 | * - Value |
| 49 | - GCC option |
| 50 | - FEAT_PAUTH |
| 51 | - FEAT_BTI |
| 52 | * - unset |
| 53 | - |
| 54 | - usually `N` (depends on how GCC is compiled) |
| 55 | - usually `N` (depends on how GCC is compiled) |
| 56 | * - 0 |
| 57 | - "none" |
| 58 | - N |
| 59 | - N |
| 60 | * - 1 |
| 61 | - "standard" |
| 62 | - Y |
| 63 | - Y |
| 64 | * - 2 |
| 65 | - "pac-ret" |
| 66 | - Y |
| 67 | - N |
| 68 | * - 3 |
| 69 | - "pac-ret+leaf" |
| 70 | - Y |
| 71 | - N |
| 72 | * - 4 |
| 73 | - "bti" |
| 74 | - N |
| 75 | - Y |
| 76 | |
| 77 | -------------- |
| 78 | |
| 79 | .. _`FAQ section of the OP-TEE documentation`: https://optee.readthedocs.io/en/stable/faq/faq.html#faq-gcc-bti |
| 80 | .. _`Providing protection for complex software` : https://developer.arm.com/documentation/102433/0200 |
| 81 | .. _`GCC Manual`: https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/AArch64-Options.html |
| 82 | |
| 83 | *Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.* |
| 84 | |
| 85 | SPDX-License-Identifier: BSD-3-Clause |