From: Mark Brown <broonie@kernel.org>
To: Catalin Marinas <catalin.marinas@arm.com>,
Will Deacon <will@kernel.org>, Jonathan Corbet <corbet@lwn.net>,
Andrew Morton <akpm@linux-foundation.org>,
Marc Zyngier <maz@kernel.org>,
Oliver Upton <oliver.upton@linux.dev>,
James Morse <james.morse@arm.com>,
Suzuki K Poulose <suzuki.poulose@arm.com>,
Arnd Bergmann <arnd@arndb.de>, Oleg Nesterov <oleg@redhat.com>,
Eric Biederman <ebiederm@xmission.com>,
Kees Cook <keescook@chromium.org>, Shuah Khan <shuah@kernel.org>,
"Rick P. Edgecombe" <rick.p.edgecombe@intel.com>,
Deepak Gupta <debug@rivosinc.com>,
Ard Biesheuvel <ardb@kernel.org>,
Szabolcs Nagy <Szabolcs.Nagy@arm.com>
Cc: "H.J. Lu" <hjl.tools@gmail.com>,
Paul Walmsley <paul.walmsley@sifive.com>,
Palmer Dabbelt <palmer@dabbelt.com>,
Albert Ou <aou@eecs.berkeley.edu>,
Florian Weimer <fweimer@redhat.com>,
Christian Brauner <brauner@kernel.org>,
Thiago Jung Bauermann <thiago.bauermann@linaro.org>,
linux-arm-kernel@lists.infradead.org, linux-doc@vger.kernel.org,
kvmarm@lists.linux.dev, linux-fsdevel@vger.kernel.org,
linux-arch@vger.kernel.org, linux-mm@kvack.org,
linux-kselftest@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-riscv@lists.infradead.org, Mark Brown <broonie@kernel.org>
Subject: [PATCH v8 05/38] arm64/gcs: Document the ABI for Guarded Control Stacks
Date: Sat, 03 Feb 2024 12:25:31 +0000 [thread overview]
Message-ID: <20240203-arm64-gcs-v8-5-c9fec77673ef@kernel.org> (raw)
In-Reply-To: <20240203-arm64-gcs-v8-0-c9fec77673ef@kernel.org>
Add some documentation of the userspace ABI for Guarded Control Stacks.
Signed-off-by: Mark Brown <broonie@kernel.org>
---
Documentation/arch/arm64/gcs.rst | 233 +++++++++++++++++++++++++++++++++++++
Documentation/arch/arm64/index.rst | 1 +
2 files changed, 234 insertions(+)
diff --git a/Documentation/arch/arm64/gcs.rst b/Documentation/arch/arm64/gcs.rst
new file mode 100644
index 000000000000..c45c0326836a
--- /dev/null
+++ b/Documentation/arch/arm64/gcs.rst
@@ -0,0 +1,233 @@
+===============================================
+Guarded Control Stack support for AArch64 Linux
+===============================================
+
+This document outlines briefly the interface provided to userspace by Linux in
+order to support use of the ARM Guarded Control Stack (GCS) feature.
+
+This is an outline of the most important features and issues only and not
+intended to be exhaustive.
+
+
+
+1. General
+-----------
+
+* GCS is an architecture feature intended to provide greater protection
+ against return oriented programming (ROP) attacks and to simplify the
+ implementation of features that need to collect stack traces such as
+ profiling.
+
+* When GCS is enabled a separate guarded control stack is maintained by the
+ PE which is writeable only through specific GCS operations. This
+ stores the call stack only, when a procedure call instruction is
+ performed the current PC is pushed onto the GCS and on RET the
+ address in the LR is verified against that on the top of the GCS.
+
+* When active current GCS pointer is stored in the system register
+ GCSPR_EL0. This is readable by userspace but can only be updated
+ via specific GCS instructions.
+
+* The architecture provides instructions for switching between guarded
+ control stacks with checks to ensure that the new stack is a valid
+ target for switching.
+
+* The functionality of GCS is similar to that provided by the x86 Shadow
+ Stack feature, due to sharing of userspace interfaces the ABI refers to
+ shadow stacks rather than GCS.
+
+* Support for GCS is reported to userspace via HWCAP2_GCS in the aux vector
+ AT_HWCAP2 entry.
+
+* GCS is enabled per thread. While there is support for disabling GCS
+ at 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 as
+ SIGSEGV 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 EL0
+ regardless of the GCS configuration for the thread.
+
+* The architecture supports enabling GCS without verifying that return values
+ in LR match those in the GCS, the LR will be ignored. This is not supported
+ by Linux.
+
+* EL0 GCS entries with bit 63 set are reserved for use, one such use is defined
+ below for signals and should be ignored when parsing the stack if not
+ understood.
+
+
+2. Enabling and disabling Guarded Control Stacks
+-------------------------------------------------
+
+* GCS is enabled and disabled for a thread via the PR_SET_SHADOW_STACK_STATUS
+ prctl(), this takes a single flags argument specifying which GCS features
+ should be used.
+
+* When set PR_SHADOW_STACK_ENABLE flag allocates a Guarded Control Stack
+ and enables GCS for the thread, enabling the functionality controlled by
+ GCSCRE0_EL1.{nTR, RVCHKEN, PCRSEL}.
+
+* When set the PR_SHADOW_STACK_PUSH flag enables the functionality controlled
+ by GCSCRE0_EL1.PUSHMEn, allowing explicit GCS pushes.
+
+* When set the PR_SHADOW_STACK_WRITE flag enables the functionality controlled
+ by 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 same
+ values as used for PR_SET_SHADOW_STACK_STATUS. Any future changes to the
+ status of the specified GCS mode bits will be rejected.
+
+* PR_LOCK_SHADOW_STACK_STATUS allows any bit to be locked, this allows
+ userspace to prevent changes to any future features.
+
+* There is no support for a process to remove a lock that has been set for
+ it.
+
+* PR_SET_SHADOW_STACK_STATUS and PR_LOCK_SHADOW_STACK_STATUS affect only the
+ thread 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 on exec().
+
+* The current GCS configuration for a thread may be read with the
+ PR_GET_SHADOW_STACK_STATUS prctl(), this returns the same flags that
+ are passed to PR_SET_SHADOW_STACK_STATUS.
+
+* If GCS is disabled for a thread after having previously been enabled then
+ the stack will remain allocated for the lifetime of the thread. At present
+ any attempt to reenable GCS for the thread will be rejected, this may be
+ revisited in future.
+
+* It should be noted that since enabling GCS will result in GCS becoming
+ active immediately it is not normally possible to return from the function
+ that invoked the prctl() that enabled GCS. It is expected that the normal
+ usage 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 be
+ allocated for it of size RLIMIT_STACK or 4 gigabytes, whichever is
+ smaller.
+
+* When a new thread is created by a thread which has GCS enabled then a
+ new Guarded Control Stack will be allocated for the new thread with
+ half the size of the standard stack.
+
+* When a stack is allocated by enabling GCS or during thread creation then
+ the top 8 bytes of the stack will be initialised to 0 and GCSPR_EL0 will
+ be set to point to the address of this 0 value, this can be used to
+ detect the top of the stack.
+
+* Additional Guarded Control Stacks can be allocated using the
+ map_shadow_stack() system call.
+
+* Stacks allocated using map_shadow_stack() can optionally have an end of
+ stack marker and cap placed at the top of the stack. If the flag
+ SHADOW_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 8
+ bytes of the stack and if it is specified then the cap will be the next
+ 8 bytes. While specifying just SHADOW_STACK_SET_MARKER by itself is
+ valid since the marker is all bits 0 it has no observable effect.
+
+* Stacks allocated using map_shadow_stack() must have a size which is a
+ multiple of 8 bytes larger than 8 bytes and must be 8 bytes aligned.
+
+* An address can be specified to map_shadow_stack(), if one is provided then
+ it must be aligned to a page boundary.
+
+* When a thread is freed the Guarded Control Stack initially allocated for
+ that thread will be freed. Note carefully that if the stack has been
+ switched 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 and
+ pointer for the interrupted context on signal delivery. This will always
+ be present on systems that support GCS.
+
+* The record contains a flag field which reports the current GCS configuration
+ for the interrupted context as PR_GET_SHADOW_STACK_STATUS would.
+
+* The signal handler is run with the same GCS configuration as the interrupted
+ context.
+
+* When GCS is enabled for the interrupted thread a signal handling specific
+ GCS cap token will be written to the GCS, this is an architectural GCS cap
+ token with bit 63 set and the token type (bits 0..11) all clear. The
+ GCSPR_EL0 reported in the signal 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 signal
+ return handler will be pushed onto the GCS, allowing return from the signal
+ handler via RET as normal. This will not be reported in the gcs_context in
+ the 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 flags
+ and GCSPR_EL0 will be restored from that context prior to further
+ validation.
+
+* If there is no gcs_context record in the signal frame then the GCS
+ configuration will be unchanged.
+
+* If GCS is enabled on return from a signal handler then GCSPR_EL0 must
+ point to a valid GCS signal cap record, this will be popped from the
+ GCS prior to signal return.
+
+* If the GCS configuration is locked when returning from a signal then any
+ attempt to change the GCS configuration will be treated as an error. This
+ is true even if GCS was not enabled prior to signal entry.
+
+* GCS may be disabled via signal return but any attempt to enable GCS via
+ signal return will be rejected.
+
+
+6. ptrace extensions
+---------------------
+
+* A new regset NT_ARM_GCS is defined for use with PTRACE_GETREGSET and
+ PTRACE_SETREGSET.
+
+* Due to the complexity surrounding allocation and deallocation of stacks and
+ lack of practical application it is not possible to enable GCS via ptrace.
+ GCS may be disabled via the ptrace interface.
+
+* Other GCS modes may be configured via ptrace.
+
+* 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 the
+ dumped process. The contents will be equivalent to the data that would
+ have been read if a PTRACE_GETREGSET of the corresponding type were
+ executed 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.
diff --git a/Documentation/arch/arm64/index.rst b/Documentation/arch/arm64/index.rst
index d08e924204bf..dcf3ee3eb8c0 100644
--- a/Documentation/arch/arm64/index.rst
+++ b/Documentation/arch/arm64/index.rst
@@ -14,6 +14,7 @@ ARM64 Architecture
booting
cpu-feature-registers
elf_hwcaps
+ gcs
hugetlbpage
kdump
legacy_instructions
--
2.30.2
next prev parent reply other threads:[~2024-02-03 12:29 UTC|newest]
Thread overview: 90+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-02-03 12:25 [PATCH v8 00/38] arm64/gcs: Provide support for GCS in userspace Mark Brown
2024-02-03 12:25 ` [PATCH v8 01/38] arm64/mm: Restructure arch_validate_flags() for extensibility Mark Brown
2024-02-03 12:25 ` [PATCH v8 02/38] prctl: arch-agnostic prctl for shadow stack Mark Brown
2024-02-03 12:25 ` [PATCH v8 03/38] mman: Add map_shadow_stack() flags Mark Brown
2024-02-03 12:25 ` [PATCH v8 04/38] arm64: Document boot requirements for Guarded Control Stacks Mark Brown
2024-02-03 12:25 ` Mark Brown [this message]
2024-02-03 12:25 ` [PATCH v8 06/38] arm64/sysreg: Add definitions for architected GCS caps Mark Brown
2024-02-03 12:25 ` [PATCH v8 07/38] arm64/gcs: Add manual encodings of GCS instructions Mark Brown
2024-02-03 12:25 ` [PATCH v8 08/38] arm64/gcs: Provide put_user_gcs() Mark Brown
2024-02-03 12:25 ` [PATCH v8 09/38] arm64/cpufeature: Runtime detection of Guarded Control Stack (GCS) Mark Brown
2024-02-03 12:25 ` [PATCH v8 10/38] arm64/mm: Allocate PIE slots for EL0 guarded control stack Mark Brown
2024-02-03 12:25 ` [PATCH v8 11/38] mm: Define VM_SHADOW_STACK for arm64 when we support GCS Mark Brown
2024-02-03 12:25 ` [PATCH v8 12/38] arm64/mm: Map pages for guarded control stack Mark Brown
2024-02-03 12:25 ` [PATCH v8 13/38] KVM: arm64: Manage GCS registers for guests Mark Brown
2024-02-05 9:46 ` Marc Zyngier
2024-02-05 12:35 ` Mark Brown
2024-02-05 15:34 ` Marc Zyngier
2024-02-05 16:58 ` Mark Brown
2024-02-03 12:25 ` [PATCH v8 14/38] arm64/gcs: Allow GCS usage at EL0 and EL1 Mark Brown
2024-02-03 12:25 ` [PATCH v8 15/38] arm64/idreg: Add overrride for GCS Mark Brown
2024-02-03 12:25 ` [PATCH v8 16/38] arm64/hwcap: Add hwcap " Mark Brown
2024-02-03 12:25 ` [PATCH v8 17/38] arm64/traps: Handle GCS exceptions Mark Brown
2024-02-03 12:25 ` [PATCH v8 18/38] arm64/mm: Handle GCS data aborts Mark Brown
2024-02-03 12:25 ` [PATCH v8 19/38] arm64/gcs: Context switch GCS state for EL0 Mark Brown
2024-02-03 12:25 ` [PATCH v8 20/38] arm64/gcs: Ensure that new threads have a GCS Mark Brown
2024-02-20 2:02 ` Thiago Jung Bauermann
2024-02-21 18:16 ` Mark Brown
2024-02-03 12:25 ` [PATCH v8 21/38] arm64/gcs: Implement shadow stack prctl() interface Mark Brown
2024-02-03 12:25 ` [PATCH v8 22/38] arm64/mm: Implement map_shadow_stack() Mark Brown
2024-02-03 12:25 ` [PATCH v8 23/38] arm64/signal: Set up and restore the GCS context for signal handlers Mark Brown
2024-02-20 2:03 ` Thiago Jung Bauermann
2024-02-03 12:25 ` [PATCH v8 24/38] arm64/signal: Expose GCS state in signal frames Mark Brown
2024-02-03 12:25 ` [PATCH v8 25/38] arm64/ptrace: Expose GCS via ptrace and core files Mark Brown
2024-02-03 12:25 ` [PATCH v8 26/38] arm64: Add Kconfig for Guarded Control Stack (GCS) Mark Brown
2024-02-03 12:25 ` [PATCH v8 27/38] kselftest/arm64: Verify the GCS hwcap Mark Brown
2024-02-03 12:25 ` [PATCH v8 28/38] kselftest/arm64: Add GCS as a detected feature in the signal tests Mark Brown
2024-02-03 12:25 ` [PATCH v8 29/38] kselftest/arm64: Add framework support for GCS to signal handling tests Mark Brown
2024-02-03 12:25 ` [PATCH v8 30/38] kselftest/arm64: Allow signals tests to specify an expected si_code Mark Brown
2024-02-03 12:25 ` [PATCH v8 31/38] kselftest/arm64: Always run signals tests with GCS enabled Mark Brown
2024-02-03 12:25 ` [PATCH v8 32/38] kselftest/arm64: Add very basic GCS test program Mark Brown
2024-02-03 12:25 ` [PATCH v8 33/38] kselftest/arm64: Add a GCS test program built with the system libc Mark Brown
2024-02-20 2:15 ` Thiago Jung Bauermann
2024-02-21 19:20 ` Mark Brown
2024-02-22 19:11 ` Mark Brown
2024-02-23 2:24 ` Thiago Jung Bauermann
2024-02-27 16:14 ` Mark Brown
2024-02-27 19:08 ` Thiago Jung Bauermann
2024-02-29 21:45 ` Mark Brown
2024-02-29 22:13 ` Thiago Jung Bauermann
2024-02-03 12:26 ` [PATCH v8 34/38] kselftest/arm64: Add test coverage for GCS mode locking Mark Brown
2024-02-03 12:26 ` [PATCH v8 35/38] selftests/arm64: Add GCS signal tests Mark Brown
2024-02-20 2:17 ` Thiago Jung Bauermann
2024-02-03 12:26 ` [PATCH v8 36/38] kselftest/arm64: Add a GCS stress test Mark Brown
2024-02-03 12:26 ` [PATCH v8 37/38] kselftest/arm64: Enable GCS for the FP stress tests Mark Brown
2024-02-03 12:26 ` [PATCH v8 38/38] kselftest: Provide shadow stack enable helpers for arm64 Mark Brown
2024-02-20 2:00 ` [PATCH v8 00/38] arm64/gcs: Provide support for GCS in userspace Thiago Jung Bauermann
2024-02-20 16:36 ` Stefan O'Rear
2024-02-20 18:41 ` Edgecombe, Rick P
2024-02-20 18:57 ` [musl] " Rich Felker
2024-02-20 23:30 ` Edgecombe, Rick P
2024-02-20 23:54 ` dalias
2024-02-21 0:35 ` Edgecombe, Rick P
2024-02-21 0:44 ` Mark Brown
2024-02-21 1:27 ` dalias
2024-02-21 2:11 ` Edgecombe, Rick P
2024-02-21 4:18 ` Edgecombe, Rick P
2024-02-21 13:53 ` Mark Brown
2024-02-21 14:58 ` dalias
2024-02-21 17:36 ` Mark Brown
2024-02-21 17:57 ` dalias
2024-02-21 18:12 ` Edgecombe, Rick P
2024-02-21 18:30 ` dalias
2024-02-21 18:53 ` Edgecombe, Rick P
2024-02-21 19:06 ` dalias
2024-02-21 19:22 ` Edgecombe, Rick P
2024-02-21 20:18 ` H.J. Lu
2024-02-21 20:25 ` H.J. Lu
2024-02-21 21:12 ` H.J. Lu
2024-02-21 20:18 ` dalias
2024-02-22 13:57 ` Mark Brown
2024-02-21 18:32 ` Mark Brown
2024-02-21 19:10 ` dalias
2024-03-02 14:57 ` Szabolcs Nagy
2024-03-02 15:05 ` H.J. Lu
2024-03-14 14:03 ` Mark Brown
2024-02-20 23:59 ` Stefan O'Rear
2024-02-21 0:40 ` Mark Brown
2024-02-21 4:30 ` Edgecombe, Rick P
2024-02-20 20:14 ` Mark Brown
2024-02-20 23:30 ` Edgecombe, Rick P
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240203-arm64-gcs-v8-5-c9fec77673ef@kernel.org \
--to=broonie@kernel.org \
--cc=Szabolcs.Nagy@arm.com \
--cc=akpm@linux-foundation.org \
--cc=aou@eecs.berkeley.edu \
--cc=ardb@kernel.org \
--cc=arnd@arndb.de \
--cc=brauner@kernel.org \
--cc=catalin.marinas@arm.com \
--cc=corbet@lwn.net \
--cc=debug@rivosinc.com \
--cc=ebiederm@xmission.com \
--cc=fweimer@redhat.com \
--cc=hjl.tools@gmail.com \
--cc=james.morse@arm.com \
--cc=keescook@chromium.org \
--cc=kvmarm@lists.linux.dev \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linux-riscv@lists.infradead.org \
--cc=maz@kernel.org \
--cc=oleg@redhat.com \
--cc=oliver.upton@linux.dev \
--cc=palmer@dabbelt.com \
--cc=paul.walmsley@sifive.com \
--cc=rick.p.edgecombe@intel.com \
--cc=shuah@kernel.org \
--cc=suzuki.poulose@arm.com \
--cc=thiago.bauermann@linaro.org \
--cc=will@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).