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