1=============================================== 2Guarded Control Stack support for AArch64 Linux 3=============================================== 4 5This document outlines briefly the interface provided to userspace by Linux in 6order to support use of the ARM Guarded Control Stack (GCS) feature. 7 8This is an outline of the most important features and issues only and not 9intended to be exhaustive. 10 11 12 131. General 14----------- 15 16* GCS is an architecture feature intended to provide greater protection 17 against return oriented programming (ROP) attacks and to simplify the 18 implementation of features that need to collect stack traces such as 19 profiling. 20 21* When GCS is enabled a separate guarded control stack is maintained by the 22 PE which is writeable only through specific GCS operations. This 23 stores the call stack only, when a procedure call instruction is 24 performed the current PC is pushed onto the GCS and on RET the 25 address in the LR is verified against that on the top of the GCS. 26 27* When active the current GCS pointer is stored in the system register 28 GCSPR_EL0. This is readable by userspace but can only be updated 29 via specific GCS instructions. 30 31* The architecture provides instructions for switching between guarded 32 control stacks with checks to ensure that the new stack is a valid 33 target for switching. 34 35* The functionality of GCS is similar to that provided by the x86 Shadow 36 Stack feature, due to sharing of userspace interfaces the ABI refers to 37 shadow stacks rather than GCS. 38 39* Support for GCS is reported to userspace via HWCAP_GCS in the aux vector 40 AT_HWCAP2 entry. 41 42* GCS is enabled per thread. While there is support for disabling GCS 43 at runtime this should be done with great care. 44 45* GCS memory access faults are reported as normal memory access faults. 46 47* GCS specific errors (those reported with EC 0x2d) will be reported as 48 SIGSEGV with a si_code of SEGV_CPERR (control protection error). 49 50* GCS is supported only for AArch64. 51 52* On systems where GCS is supported GCSPR_EL0 is always readable by EL0 53 regardless of the GCS configuration for the thread. 54 55* The architecture supports enabling GCS without verifying that return values 56 in LR match those in the GCS, the LR will be ignored. This is not supported 57 by Linux. 58 59 60 612. Enabling and disabling Guarded Control Stacks 62------------------------------------------------- 63 64* GCS is enabled and disabled for a thread via the PR_SET_SHADOW_STACK_STATUS 65 prctl(), this takes a single flags argument specifying which GCS features 66 should be used. 67 68* When set PR_SHADOW_STACK_ENABLE flag allocates a Guarded Control Stack 69 and enables GCS for the thread, enabling the functionality controlled by 70 GCSCRE0_EL1.{nTR, RVCHKEN, PCRSEL}. 71 72* When set the PR_SHADOW_STACK_PUSH flag enables the functionality controlled 73 by GCSCRE0_EL1.PUSHMEn, allowing explicit GCS pushes. 74 75* When set the PR_SHADOW_STACK_WRITE flag enables the functionality controlled 76 by GCSCRE0_EL1.STREn, allowing explicit stores to the Guarded Control Stack. 77 78* Any unknown flags will cause PR_SET_SHADOW_STACK_STATUS to return -EINVAL. 79 80* PR_LOCK_SHADOW_STACK_STATUS is passed a bitmask of features with the same 81 values as used for PR_SET_SHADOW_STACK_STATUS. Any future changes to the 82 status of the specified GCS mode bits will be rejected. 83 84* PR_LOCK_SHADOW_STACK_STATUS allows any bit to be locked, this allows 85 userspace to prevent changes to any future features. 86 87* There is no support for a process to remove a lock that has been set for 88 it. 89 90* PR_SET_SHADOW_STACK_STATUS and PR_LOCK_SHADOW_STACK_STATUS affect only the 91 thread that called them, any other running threads will be unaffected. 92 93* New threads inherit the GCS configuration of the thread that created them. 94 95* GCS is disabled on exec(). 96 97* The current GCS configuration for a thread may be read with the 98 PR_GET_SHADOW_STACK_STATUS prctl(), this returns the same flags that 99 are passed to PR_SET_SHADOW_STACK_STATUS. 100 101* If GCS is disabled for a thread after having previously been enabled then 102 the stack will remain allocated for the lifetime of the thread. At present 103 any attempt to reenable GCS for the thread will be rejected, this may be 104 revisited in future. 105 106* It should be noted that since enabling GCS will result in GCS becoming 107 active immediately it is not normally possible to return from the function 108 that invoked the prctl() that enabled GCS. It is expected that the normal 109 usage will be that GCS is enabled very early in execution of a program. 110 111 112 1133. Allocation of Guarded Control Stacks 114---------------------------------------- 115 116* When GCS is enabled for a thread a new Guarded Control Stack will be 117 allocated for it of half the standard stack size or 2 gigabytes, 118 whichever is smaller. 119 120* When a new thread is created by a thread which has GCS enabled then a 121 new Guarded Control Stack will be allocated for the new thread with 122 half the size of the standard stack. 123 124* When a stack is allocated by enabling GCS or during thread creation then 125 the top 8 bytes of the stack will be initialised to 0 and GCSPR_EL0 will 126 be set to point to the address of this 0 value, this can be used to 127 detect the top of the stack. 128 129* Additional Guarded Control Stacks can be allocated using the 130 map_shadow_stack() system call. 131 132* Stacks allocated using map_shadow_stack() can optionally have an end of 133 stack marker and cap placed at the top of the stack. If the flag 134 SHADOW_STACK_SET_TOKEN is specified a cap will be placed on the stack, 135 if SHADOW_STACK_SET_MARKER is not specified the cap will be the top 8 136 bytes of the stack and if it is specified then the cap will be the next 137 8 bytes. While specifying just SHADOW_STACK_SET_MARKER by itself is 138 valid since the marker is all bits 0 it has no observable effect. 139 140* Stacks allocated using map_shadow_stack() must have a size which is a 141 multiple of 8 bytes larger than 8 bytes and must be 8 bytes aligned. 142 143* An address can be specified to map_shadow_stack(), if one is provided then 144 it must be aligned to a page boundary. 145 146* When a thread is freed the Guarded Control Stack initially allocated for 147 that thread will be freed. Note carefully that if the stack has been 148 switched this may not be the stack currently in use by the thread. 149 150 1514. Signal handling 152-------------------- 153 154* A new signal frame record gcs_context encodes the current GCS mode and 155 pointer for the interrupted context on signal delivery. This will always 156 be present on systems that support GCS. 157 158* The record contains a flag field which reports the current GCS configuration 159 for the interrupted context as PR_GET_SHADOW_STACK_STATUS would. 160 161* The signal handler is run with the same GCS configuration as the interrupted 162 context. 163 164* When GCS is enabled for the interrupted thread a signal handling specific 165 GCS cap token will be written to the GCS, this is an architectural GCS cap 166 with the token type (bits 0..11) all clear. The GCSPR_EL0 reported in the 167 signal frame will point to this cap token. 168 169* The signal handler will use the same GCS as the interrupted context. 170 171* When GCS is enabled on signal entry a frame with the address of the signal 172 return handler will be pushed onto the GCS, allowing return from the signal 173 handler via RET as normal. This will not be reported in the gcs_context in 174 the signal frame. 175 176 1775. Signal return 178----------------- 179 180When returning from a signal handler: 181 182* If there is a gcs_context record in the signal frame then the GCS flags 183 and GCSPR_EL0 will be restored from that context prior to further 184 validation. 185 186* If there is no gcs_context record in the signal frame then the GCS 187 configuration will be unchanged. 188 189* If GCS is enabled on return from a signal handler then GCSPR_EL0 must 190 point to a valid GCS signal cap record, this will be popped from the 191 GCS prior to signal return. 192 193* If the GCS configuration is locked when returning from a signal then any 194 attempt to change the GCS configuration will be treated as an error. This 195 is true even if GCS was not enabled prior to signal entry. 196 197* GCS may be disabled via signal return but any attempt to enable GCS via 198 signal return will be rejected. 199 200 2016. ptrace extensions 202--------------------- 203 204* A new regset NT_ARM_GCS is defined for use with PTRACE_GETREGSET and 205 PTRACE_SETREGSET. 206 207* The GCS mode, including enable and disable, may be configured via ptrace. 208 If GCS is enabled via ptrace no new GCS will be allocated for the thread. 209 210* Configuration via ptrace ignores locking of GCS mode bits. 211 212 2137. ELF coredump extensions 214--------------------------- 215 216* NT_ARM_GCS notes will be added to each coredump for each thread of the 217 dumped process. The contents will be equivalent to the data that would 218 have been read if a PTRACE_GETREGSET of the corresponding type were 219 executed for each thread when the coredump was generated. 220 221 222 2238. /proc extensions 224-------------------- 225 226* Guarded Control Stack pages will include "ss" in their VmFlags in 227 /proc/<pid>/smaps. 228