1Supported Architectural Features
2================================
3
4.. _branch_protection:
5
6Branch Protection
7-----------------
8
9Branch protection covers two architecture features for mitigating Return Oriented Programming (ROP) and Jump Oriented
10Programming (JOP) attacks. For generic overview of these features please see
11`Providing protection for complex software`_.
12
13Branch Protection related hardware features can not be controlled from S-EL0 and to enable these co-operation with
14components running at higher exception levels is needed. Please refer to the documentation of the these components for
15information on how to enable these HW features.
16
17Pointer Authentication (FEAT_PAUTH)
18'''''''''''''''''''''''''''''''''''
19
20Pointer Authentication (PAC) is an ARMv8.3 feature where the return address of each function is signed. The signature is
21calculated when the function is called and verified upon returning. This is to ensure the return address has not been
22tampered with.
23
24Branch Target Identification (FEAT_BTI)
25'''''''''''''''''''''''''''''''''''''''
26
27Branch Target Identification (BTI) is an ARMv8.5 feature which is used to guard against the execution of instructions
28that are not the intended target of an indirect branch.
29
30For raw-binary SPs the TS build system will will mark the executable regions with the BTI attribute in the SP manifest
31file. The SPMC implementation running the SP is required to support this memory attribute, or has to unconditionally
32enable BTI for all executable regions to get the feature working.
33
34Although GCC has BTI support since v9, no BTI enabled libraries are shipped with the current GNUARM releases. A possible
35workaround is to compile from source as described in the `FAQ section of the OP-TEE documentation`_.
36
37Configuring Branch Protection in the TS build system
38''''''''''''''''''''''''''''''''''''''''''''''''''''
39
40The feature can be controlled using the ``BRANCH_PROTECTION`` variable. This can be set e.g. on the cmake command line
41by passing ``-DBRANCH_PROTECTION=<value>``. The default value is ``unset``. Please refer to `GCC manual`_ for the
42detailed 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
85SPDX-License-Identifier: BSD-3-Clause
86