1 =======================================
2 Pointer authentication in AArch64 Linux
3 =======================================
4
5 Author: Mark Rutland <mark.rutland@arm.com>
6
7 Date: 2017-07-19
8
9 This document briefly describes the provision
10 functionality in AArch64 Linux.
11
12
13 Architecture overview
14 ---------------------
15
16 The ARMv8.3 Pointer Authentication extension a
17 used to mitigate certain classes of attack whe
18 the contents of some memory (e.g. the stack).
19
20 The extension uses a Pointer Authentication Co
21 whether pointers have been modified unexpected
22 a pointer, another value (such as the stack po
23 held in system registers.
24
25 The extension adds instructions to insert a va
26 and to verify/remove the PAC from a pointer. T
27 of high-order bits of the pointer, which varie
28 configured virtual address size and whether po
29
30 A subset of these instructions have been alloc
31 encoding space. In the absence of the extensio
32 these instructions behave as NOPs. Application
33 these instructions operate correctly regardles
34 extension.
35
36 The extension provides five separate keys to g
37 instruction addresses (APIAKey, APIBKey), two
38 (APDAKey, APDBKey), and one for generic authen
39
40
41 Basic support
42 -------------
43
44 When CONFIG_ARM64_PTR_AUTH is selected, and re
45 present, the kernel will assign random key val
46 exec*() time. The keys are shared by all threa
47 are preserved across fork().
48
49 Presence of address authentication functionali
50 HWCAP_PACA, and generic authentication functio
51
52 The number of bits that the PAC occupies in a
53 virtual address size configured by the kernel.
54 virtual address size of 48, the PAC is 7 bits
55
56 When ARM64_PTR_AUTH_KERNEL is selected, the ke
57 with HINT space pointer authentication instruc
58 function returns. Kernels built with this opti
59 with or without pointer authentication support
60
61 In addition to exec(), keys can also be reinit
62 using the PR_PAC_RESET_KEYS prctl. A bitmask o
63 PR_PAC_APIBKEY, PR_PAC_APDAKEY, PR_PAC_APDBKEY
64 specifies which keys are to be reinitialized;
65 keys".
66
67
68 Debugging
69 ---------
70
71 When CONFIG_ARM64_PTR_AUTH is selected, and HW
72 authentication is present, the kernel will exp
73 PAC bits in the NT_ARM_PAC_MASK regset (struct
74 userspace can acquire via PTRACE_GETREGSET.
75
76 The regset is exposed only when HWCAP_PACA is
77 exposed for data pointers and instruction poin
78 bits can vary between the two. Note that the m
79 addresses, and are not valid to apply to TTBR1
80 pointers).
81
82 Additionally, when CONFIG_CHECKPOINT_RESTORE i
83 will expose the NT_ARM_PACA_KEYS and NT_ARM_PA
84 user_pac_address_keys and struct user_pac_gene
85 used to get and set the keys for a thread.
86
87
88 Virtualization
89 --------------
90
91 Pointer authentication is enabled in KVM guest
92 initialised by passing flags KVM_ARM_VCPU_PTRA
93 requesting these two separate cpu features to
94 guest implementation works by enabling both fe
95 these userspace flags are checked before enabl
96 The separate userspace flag will allow to have
97 if support is added in the future to allow the
98 enabled independently of one another.
99
100 As Arm Architecture specifies that Pointer Aut
101 implemented along with the VHE feature so KVM
102 on VHE mode to be present.
103
104 Additionally, when these vcpu feature flags ar
105 filter out the Pointer Authentication system k
106 KVM_GET/SET_REG_* ioctls and mask those featur
107 register. Any attempt to use the Pointer Authe
108 result in an UNDEFINED exception being injecte
109
110
111 Enabling and disabling keys
112 ---------------------------
113
114 The prctl PR_PAC_SET_ENABLED_KEYS allows the u
115 PAC keys are enabled in a particular task. It
116 first being a bitmask of PR_PAC_APIAKEY, PR_PA
117 and PR_PAC_APDBKEY specifying which keys shall
118 and the second being a bitmask of the same bit
119 should be enabled or disabled. For example::
120
121 prctl(PR_PAC_SET_ENABLED_KEYS,
122 PR_PAC_APIAKEY | PR_PAC_APIBKEY | PR_P
123 PR_PAC_APIBKEY, 0, 0);
124
125 disables all keys except the IB key.
126
127 The main reason why this is useful is to enabl
128 instructions to sign and authenticate function
129 exposed outside of the function, while still a
130 the ABI to interoperate with legacy binaries t
131 pointers.
132
133 The idea is that a dynamic loader or early sta
134 prctl very early after establishing that a pro
135 but before executing any PAC instructions.
136
137 For compatibility with previous kernel version
138 IB, DA and DB enabled, and are reset to this s
139 via fork() and clone() inherit the key enabled
140
141 It is recommended to avoid disabling the IA ke
142 overhead than disabling any of the other keys.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.