1. General¶

• GCS is an architecture feature intended to provide greater protectionagainst return oriented programming (ROP) attacks and to simplify theimplementation of features that need to collect stack traces such asprofiling.

• When GCS is enabled a separate guarded control stack is maintained by thePE which is writeable only through specific GCS operations. Thisstores the call stack only, when a procedure call instruction isperformed the current PC is pushed onto the GCS and on RET theaddress in the LR is verified against that on the top of the GCS.

• When active the current GCS pointer is stored in the system registerGCSPR_EL0. This is readable by userspace but can only be updatedvia specific GCS instructions.

• The architecture provides instructions for switching between guardedcontrol stacks with checks to ensure that the new stack is a validtarget for switching.

• The functionality of GCS is similar to that provided by the x86 ShadowStack feature, due to sharing of userspace interfaces the ABI refers toshadow stacks rather than GCS.

• Support for GCS is reported to userspace via HWCAP_GCS in the aux vectorAT_HWCAP entry.

• GCS is enabled per thread. While there is support for disabling GCSat runtime this should be done with great care.

• GCS memory access faults are reported as normal memory access faults.

• GCS specific errors (those reported with EC 0x2d) will be reported asSIGSEGV with a si_code of SEGV_CPERR (control protection error).

• GCS is supported only for AArch64.

• On systems where GCS is supported GCSPR_EL0 is always readable by EL0regardless of the GCS configuration for the thread.

• The architecture supports enabling GCS without verifying that return valuesin LR match those in the GCS, the LR will be ignored. This is not supportedby Linux.

2. Enabling and disabling Guarded Control Stacks¶

• GCS is enabled and disabled for a thread via the PR_SET_SHADOW_STACK_STATUSprctl(), this takes a single flags argument specifying which GCS featuresshould be used.

• When set PR_SHADOW_STACK_ENABLE flag allocates a Guarded Control Stackand enables GCS for the thread, enabling the functionality controlled byGCSCRE0_EL1.{nTR, RVCHKEN, PCRSEL}.

• When set the PR_SHADOW_STACK_PUSH flag enables the functionality controlledby GCSCRE0_EL1.PUSHMEn, allowing explicit GCS pushes.

• When set the PR_SHADOW_STACK_WRITE flag enables the functionality controlledby GCSCRE0_EL1.STREn, allowing explicit stores to the Guarded Control Stack.

• Any unknown flags will cause PR_SET_SHADOW_STACK_STATUS to return -EINVAL.

• PR_LOCK_SHADOW_STACK_STATUS is passed a bitmask of features with the samevalues as used for PR_SET_SHADOW_STACK_STATUS. Any future changes to thestatus of the specified GCS mode bits will be rejected.

• PR_LOCK_SHADOW_STACK_STATUS allows any bit to be locked, this allowsuserspace to prevent changes to any future features.

• There is no support for a process to remove a lock that has been set forit.

• PR_SET_SHADOW_STACK_STATUS and PR_LOCK_SHADOW_STACK_STATUS affect only thethread that called them, any other running threads will be unaffected.

• New threads inherit the GCS configuration of the thread that created them.

• GCS is disabled onexec().

• The current GCS configuration for a thread may be read with thePR_GET_SHADOW_STACK_STATUSprctl(), this returns the same flags thatare passed to PR_SET_SHADOW_STACK_STATUS.

• If GCS is disabled for a thread after having previously been enabled thenthe stack will remain allocated for the lifetime of the thread. At presentany attempt to reenable GCS for the thread will be rejected, this may berevisited in future.

• It should be noted that since enabling GCS will result in GCS becomingactive immediately it is not normally possible to return from the functionthat invoked theprctl() that enabled GCS. It is expected that the normalusage will be that GCS is enabled very early in execution of a program.

3. Allocation of Guarded Control Stacks¶

• When GCS is enabled for a thread a new Guarded Control Stack will beallocated for it of half the standard stack size or 2 gigabytes,whichever is smaller.

• When a new thread is created by a thread which has GCS enabled then anew Guarded Control Stack will be allocated for the new thread withhalf the size of the standard stack.

• When a stack is allocated by enabling GCS or during thread creation thenthe top 8 bytes of the stack will be initialised to 0 and GCSPR_EL0 willbe set to point to the address of this 0 value, this can be used todetect the top of the stack.

• Additional Guarded Control Stacks can be allocated using themap_shadow_stack() system call.

• Stacks allocated usingmap_shadow_stack() can optionally have an end ofstack marker and cap placed at the top of the stack. If the flagSHADOW_STACK_SET_TOKEN is specified a cap will be placed on the stack,if SHADOW_STACK_SET_MARKER is not specified the cap will be the top 8bytes of the stack and if it is specified then the cap will be the next8 bytes. While specifying just SHADOW_STACK_SET_MARKER by itself isvalid since the marker is all bits 0 it has no observable effect.

• Stacks allocated usingmap_shadow_stack() must have a size which is amultiple of 8 bytes larger than 8 bytes and must be 8 bytes aligned.

• An address can be specified tomap_shadow_stack(), if one is provided thenit must be aligned to a page boundary.

• When a thread is freed the Guarded Control Stack initially allocated forthat thread will be freed. Note carefully that if the stack has beenswitched this may not be the stack currently in use by the thread.

4. Signal handling¶

• A new signal frame record gcs_context encodes the current GCS mode andpointer for the interrupted context on signal delivery. This will alwaysbe present on systems that support GCS.

• The record contains a flag field which reports the current GCS configurationfor the interrupted context as PR_GET_SHADOW_STACK_STATUS would.

• The signal handler is run with the same GCS configuration as the interruptedcontext.

• When GCS is enabled for the interrupted thread a signal handling specificGCS cap token will be written to the GCS, this is an architectural GCS capwith the token type (bits 0..11) all clear. The GCSPR_EL0 reported in thesignal frame will point to this cap token.

• The signal handler will use the same GCS as the interrupted context.

• When GCS is enabled on signal entry a frame with the address of the signalreturn handler will be pushed onto the GCS, allowing return from the signalhandler via RET as normal. This will not be reported in the gcs_context inthe signal frame.

5. Signal return¶

When returning from a signal handler:

• If there is a gcs_context record in the signal frame then the GCS flagsand GCSPR_EL0 will be restored from that context prior to furthervalidation.

• If there is no gcs_context record in the signal frame then the GCSconfiguration will be unchanged.

• If GCS is enabled on return from a signal handler then GCSPR_EL0 mustpoint to a valid GCS signal cap record, this will be popped from theGCS prior to signal return.

• If the GCS configuration is locked when returning from a signal then anyattempt to change the GCS configuration will be treated as an error. Thisis true even if GCS was not enabled prior to signal entry.

• GCS may be disabled via signal return but any attempt to enable GCS viasignal return will be rejected.

6. ptrace extensions¶

• A new regset NT_ARM_GCS is defined for use with PTRACE_GETREGSET andPTRACE_SETREGSET.

• The GCS mode, including enable and disable, may be configured via ptrace.If GCS is enabled via ptrace no new GCS will be allocated for the thread.

• Configuration via ptrace ignores locking of GCS mode bits.

7. ELF coredump extensions¶

• NT_ARM_GCS notes will be added to each coredump for each thread of thedumped process. The contents will be equivalent to the data that wouldhave been read if a PTRACE_GETREGSET of the corresponding type wereexecuted for each thread when the coredump was generated.

8. /proc extensions¶

• Guarded Control Stack pages will include “ss” in their VmFlags in/proc/<pid>/smaps.