linux-kernel - Re: [PATCH v23 2/8] Documentation: userspace-api: Add shadow stack API documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <e1ebe42c-8ea4-4f56-a017-610c8885f4f2@infradead.org>
Date: Thu, 18 Dec 2025 10:55:42 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Mark Brown <broonie@...nel.org>,
 "Rick P. Edgecombe" <rick.p.edgecombe@...el.com>,
 Deepak Gupta <debug@...osinc.com>, "H.J. Lu" <hjl.tools@...il.com>,
 Florian Weimer <fweimer@...hat.com>, Thomas Gleixner <tglx@...utronix.de>,
 Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
 Dave Hansen <dave.hansen@...ux.intel.com>, x86@...nel.org,
 "H. Peter Anvin" <hpa@...or.com>, Peter Zijlstra <peterz@...radead.org>,
 Juri Lelli <juri.lelli@...hat.com>,
 Vincent Guittot <vincent.guittot@...aro.org>,
 Dietmar Eggemann <dietmar.eggemann@....com>,
 Steven Rostedt <rostedt@...dmis.org>, Ben Segall <bsegall@...gle.com>,
 Mel Gorman <mgorman@...e.de>, Valentin Schneider <vschneid@...hat.com>,
 Christian Brauner <brauner@...nel.org>, Shuah Khan <shuah@...nel.org>
Cc: linux-kernel@...r.kernel.org, Catalin Marinas <catalin.marinas@....com>,
 Will Deacon <will@...nel.org>, jannh@...gle.com,
 Andrew Morton <akpm@...ux-foundation.org>,
 Yury Khrustalev <yury.khrustalev@....com>,
 Adhemerval Zanella Netto <adhemerval.zanella@...aro.org>,
 Wilco Dijkstra <wilco.dijkstra@....com>, CarlosO'Donell
 <codonell@...hat.com>, Rich Felker <dalias@...c.org>,
 linux-kselftest@...r.kernel.org, linux-api@...r.kernel.org,
 Kees Cook <kees@...nel.org>, Shuah Khan <skhan@...uxfoundation.org>
Subject: Re: [PATCH v23 2/8] Documentation: userspace-api: Add shadow stack
 API documentation

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@....com>
> Reviewed-by: Kees Cook <kees@...nel.org>
> Tested-by: Kees Cook <kees@...nel.org>
> Acked-by: Shuah Khan <skhan@...uxfoundation.org>
> Acked-by: Yury Khrustalev <yury.khrustalev@....com>
> Reviewed-by: Deepak Gupta <debug@...osinc.com>
> Tested-by: Rick Edgecombe <rick.p.edgecombe@...el.com>
> Signed-off-by: Mark Brown <broonie@...nel.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.
> 

-- 
~Randy