On 12/18/25 12:10 AM, Mark Brown wrote:
There are a number of architectures with shadow stack features which we are presenting to userspace with as consistent an API as we can (though there are some architecture specifics). Especially given that there are some important considerations for userspace code interacting directly with the feature let's provide some documentation covering the common aspects.
Reviewed-by: Catalin Marinas catalin.marinas@arm.com Reviewed-by: Kees Cook kees@kernel.org Tested-by: Kees Cook kees@kernel.org Acked-by: Shuah Khan skhan@linuxfoundation.org Acked-by: Yury Khrustalev yury.khrustalev@arm.com Reviewed-by: Deepak Gupta debug@rivosinc.com Tested-by: Rick Edgecombe rick.p.edgecombe@intel.com Signed-off-by: Mark Brown broonie@kernel.org
Documentation/userspace-api/index.rst | 1 + Documentation/userspace-api/shadow_stack.rst | 44 ++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+)
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 8a61ac4c1bf1..64b0099ee161 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -63,6 +63,7 @@ Everything else ELF liveupdate netlink/index
- shadow_stack sysfs-platform_profile vduse futex2
diff --git a/Documentation/userspace-api/shadow_stack.rst b/Documentation/userspace-api/shadow_stack.rst new file mode 100644 index 000000000000..42617d0470ba --- /dev/null +++ b/Documentation/userspace-api/shadow_stack.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0
+============= +Shadow Stacks +=============
+Introduction +============
+Several architectures have features which provide backward edge +control flow protection through a hardware maintained stack, only +writable by userspace through very limited operations. This feature +is referred to as shadow stacks on Linux, on x86 it is part of Intel +Control Enforcement Technology (CET), on arm64 it is Guarded Control +Stacks feature (FEAT_GCS) and for RISC-V it is the Zicfiss extension. +It is expected that this feature will normally be managed by the +system dynamic linker and libc in ways broadly transparent to +application code, this document covers interfaces and considerations.
+Enabling +========
+Shadow stacks default to disabled when a userspace process is +executed, they can be enabled for the current thread with a syscall:
- For x86 the ARCH_SHSTK_ENABLE arch_prctl()
- For other architectures the PR_SET_SHADOW_STACK_ENABLE prctl()
+It is expected that this will normally be done by the dynamic linker. +Any new threads created by a thread with shadow stacks enabled will +themselves have shadow stacks enabled.
+Enablement considerations +=========================
+- Returning from the function that enables shadow stacks without first
- disabling them will cause a shadow stack exception. This includes
- any syscall wrapper or other library functions, the syscall will need
- to be inlined.
+- A lock feature allows userspace to prevent disabling of shadow stacks. +- Those that change the stack context like longjmp() or use of ucontext
Those <what>? maybe syscalls, library calls, specific functon calls?
- changes on signal return will need support from libc.