Documentation/arch/x86/shstk.rst

Source file repositories/reference/linux-study-clean/Documentation/arch/x86/shstk.rst

File Facts

System
Linux kernel
Corpus path
Documentation/arch/x86/shstk.rst
Extension
.rst
Size
7424 bytes
Lines
180
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

======================================================
Control-flow Enforcement Technology (CET) Shadow Stack
======================================================

CET Background
==============

Control-flow Enforcement Technology (CET) covers several related x86 processor
features that provide protection against control flow hijacking attacks. CET
can protect both applications and the kernel.

CET introduces shadow stack and indirect branch tracking (IBT). A shadow stack
is a secondary stack allocated from memory which cannot be directly modified by
applications. When executing a CALL instruction, the processor pushes the
return address to both the normal stack and the shadow stack. Upon
function return, the processor pops the shadow stack copy and compares it
to the normal stack copy. If the two differ, the processor raises a
control-protection fault. IBT verifies indirect CALL/JMP targets are intended
as marked by the compiler with 'ENDBR' opcodes. Not all CPU's have both Shadow
Stack and Indirect Branch Tracking. Today in the 64-bit kernel, only userspace
shadow stack and kernel IBT are supported.

Requirements to use Shadow Stack
================================

To use userspace shadow stack you need HW that supports it, a kernel
configured with it and userspace libraries compiled with it.

The kernel Kconfig option is X86_USER_SHADOW_STACK.  When compiled in, shadow
stacks can be disabled at runtime with the kernel parameter: nousershstk.

To build a user shadow stack enabled kernel, Binutils v2.29 or LLVM v6 or later
are required.

At run time, /proc/cpuinfo shows CET features if the processor supports
CET. "user_shstk" means that userspace shadow stack is supported on the current
kernel and HW.

Application Enabling
====================

An application's CET capability is marked in its ELF note and can be verified
from readelf/llvm-readelf output::

    readelf -n <application> | grep -a SHSTK
        properties: x86 feature: SHSTK

The kernel does not process these applications markers directly. Applications
or loaders must enable CET features using the interface described in section 4.
Typically this would be done in dynamic loader or static runtime objects, as is
the case in GLIBC.

Enabling arch_prctl()'s
=======================

Elf features should be enabled by the loader using the below arch_prctl's. They
are only supported in 64 bit user applications. These operate on the features
on a per-thread basis. The enablement status is inherited on clone, so if the
feature is enabled on the first thread, it will propagate to all the thread's
in an app.

arch_prctl(ARCH_SHSTK_ENABLE, unsigned long feature)
    Enable a single feature specified in 'feature'. Can only operate on
    one feature at a time.

arch_prctl(ARCH_SHSTK_DISABLE, unsigned long feature)
    Disable a single feature specified in 'feature'. Can only operate on
    one feature at a time.

Annotation

Implementation Notes