src/third_party/llvm-project/clang/docs/ShadowCallStack.rst - cobalt - Git at Google

 ===============
 ShadowCallStack
 ===============

 .. contents::
    :local:

 Introduction
 ============

 ShadowCallStack is an **experimental** instrumentation pass, currently only
 implemented for x86_64 and aarch64, that protects programs against return
 address overwrites (e.g. stack buffer overflows.) It works by saving a
 function's return address to a separately allocated 'shadow call stack'
 in the function prolog and checking the return address on the stack against
 the shadow call stack in the function epilog.

 Comparison
 ----------

 To optimize for memory consumption and cache locality, the shadow call stack
 stores an index followed by an array of return addresses. This is in contrast
 to other schemes, like :doc:`SafeStack`, that mirror the entire stack and
 trade-off consuming more memory for shorter function prologs and epilogs with
 fewer memory accesses. Similarly, `Return Flow Guard`_ consumes more memory with
 shorter function prologs and epilogs than ShadowCallStack but suffers from the
 same race conditions (see `Security`_). Intel `Control-flow Enforcement Technology`_
 (CET) is a proposed hardware extension that would add native support to
 use a shadow stack to store/check return addresses at call/return time. It
 would not suffer from race conditions at calls and returns and not incur the
 overhead of function instrumentation, but it does require operating system
 support.

 .. _`Return Flow Guard`: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
 .. _`Control-flow Enforcement Technology`: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf

 Compatibility
 -------------

 ShadowCallStack currently only supports x86_64 and aarch64. A runtime is not
 currently provided in compiler-rt so one must be provided by the compiled
 application.

 On aarch64, the instrumentation makes use of the platform register ``x18``.
 On some platforms, ``x18`` is reserved, and on others, it is designated as
 a scratch register.  This generally means that any code that may run on the
 same thread as code compiled with ShadowCallStack must either target one
 of the platforms whose ABI reserves ``x18`` (currently Darwin, Fuchsia and
 Windows) or be compiled with the flag ``-ffixed-x18``.

 Security
 ========

 ShadowCallStack is intended to be a stronger alternative to
 ``-fstack-protector``. It protects from non-linear overflows and arbitrary
 memory writes to the return address slot; however, similarly to
 ``-fstack-protector`` this protection suffers from race conditions because of
 the call-return semantics on x86_64. There is a short race between the call
 instruction and the first instruction in the function that reads the return
 address where an attacker could overwrite the return address and bypass
 ShadowCallStack. Similarly, there is a time-of-check-to-time-of-use race in the
 function epilog where an attacker could overwrite the return address after it
 has been checked and before it has been returned to. Modifying the call-return
 semantics to fix this on x86_64 would incur an unacceptable performance overhead
 due to return branch prediction.

 The instrumentation makes use of the ``gs`` segment register on x86_64,
 or the ``x18`` register on aarch64, to reference the shadow call stack
 meaning that references to the shadow call stack do not have to be stored in
 memory. This makes it possible to implement a runtime that avoids exposing
 the address of the shadow call stack to attackers that can read arbitrary
 memory. However, attackers could still try to exploit side channels exposed
 by the operating system `[1]`_ `[2]`_ or processor `[3]`_ to discover the
 address of the shadow call stack.

 .. _`[1]`: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
 .. _`[2]`: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
 .. _`[3]`: https://www.vusec.net/projects/anc/

 On x86_64, leaf functions are optimized to store the return address in a
 free register and avoid writing to the shadow call stack if a register is
 available. Very short leaf functions are uninstrumented if their execution
 is judged to be shorter than the race condition window intrinsic to the
 instrumentation.

 On aarch64, the architecture's call and return instructions (``bl`` and
 ``ret``) operate on a register rather than the stack, which means that
 leaf functions are generally protected from return address overwrites even
 without ShadowCallStack. It also means that ShadowCallStack on aarch64 is not
 vulnerable to the same types of time-of-check-to-time-of-use races as x86_64.

 Usage
 =====

 To enable ShadowCallStack, just pass the ``-fsanitize=shadow-call-stack``
 flag to both compile and link command lines. On aarch64, you also need to pass
 ``-ffixed-x18`` unless your target already reserves ``x18``.

 Low-level API
 -------------

 ``__has_feature(shadow_call_stack)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 In some cases one may need to execute different code depending on whether
 ShadowCallStack is enabled. The macro ``__has_feature(shadow_call_stack)`` can
 be used for this purpose.

 .. code-block:: c

     #if defined(__has_feature)
     #  if __has_feature(shadow_call_stack)
     // code that builds only under ShadowCallStack
     #  endif
     #endif

 ``__attribute__((no_sanitize("shadow-call-stack")))``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Use ``__attribute__((no_sanitize("shadow-call-stack")))`` on a function
 declaration to specify that the shadow call stack instrumentation should not be
 applied to that function, even if enabled globally.

 Example
 =======

 The following example code:

 .. code-block:: c++

     int foo() {
       return bar() + 1;
     }

 Generates the following x86_64 assembly when compiled with ``-O2``:

 .. code-block:: gas

     push   %rax
     callq  bar
     add    $0x1,%eax
     pop    %rcx
     retq

 or the following aarch64 assembly:

 .. code-block:: none

     stp     x29, x30, [sp, #-16]!
     mov     x29, sp
     bl      bar
     add     w0, w0, #1
     ldp     x29, x30, [sp], #16
     ret


 Adding ``-fsanitize=shadow-call-stack`` would output the following x86_64
 assembly:

 .. code-block:: gas

     mov    (%rsp),%r10
     xor    %r11,%r11
     addq   $0x8,%gs:(%r11)
     mov    %gs:(%r11),%r11
     mov    %r10,%gs:(%r11)
     push   %rax
     callq  bar
     add    $0x1,%eax
     pop    %rcx
     xor    %r11,%r11
     mov    %gs:(%r11),%r10
     mov    %gs:(%r10),%r10
     subq   $0x8,%gs:(%r11)
     cmp    %r10,(%rsp)
     jne    trap
     retq

     trap:
     ud2

 or the following aarch64 assembly:

 .. code-block:: none

     str     x30, [x18], #8
     stp     x29, x30, [sp, #-16]!
     mov     x29, sp
     bl      bar
     add     w0, w0, #1
     ldp     x29, x30, [sp], #16
     ldr     x30, [x18, #-8]!
     ret
	===============
	ShadowCallStack
	===============

	.. contents::
	:local:

	Introduction
	============

	ShadowCallStack is an experimental instrumentation pass, currently only
	implemented for x86_64 and aarch64, that protects programs against return
	address overwrites (e.g. stack buffer overflows.) It works by saving a
	function's return address to a separately allocated 'shadow call stack'
	in the function prolog and checking the return address on the stack against
	the shadow call stack in the function epilog.

	Comparison
	----------

	To optimize for memory consumption and cache locality, the shadow call stack
	stores an index followed by an array of return addresses. This is in contrast
	to other schemes, like :doc:`SafeStack`, that mirror the entire stack and
	trade-off consuming more memory for shorter function prologs and epilogs with
	fewer memory accesses. Similarly, `Return Flow Guard`_ consumes more memory with
	shorter function prologs and epilogs than ShadowCallStack but suffers from the
	same race conditions (see `Security`_). Intel `Control-flow Enforcement Technology`_
	(CET) is a proposed hardware extension that would add native support to
	use a shadow stack to store/check return addresses at call/return time. It
	would not suffer from race conditions at calls and returns and not incur the
	overhead of function instrumentation, but it does require operating system
	support.

	.. _`Return Flow Guard`: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
	.. _`Control-flow Enforcement Technology`: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf

	Compatibility
	-------------

	ShadowCallStack currently only supports x86_64 and aarch64. A runtime is not
	currently provided in compiler-rt so one must be provided by the compiled
	application.

	On aarch64, the instrumentation makes use of the platform register ``x18``.
	On some platforms, ``x18`` is reserved, and on others, it is designated as
	a scratch register. This generally means that any code that may run on the
	same thread as code compiled with ShadowCallStack must either target one
	of the platforms whose ABI reserves ``x18`` (currently Darwin, Fuchsia and
	Windows) or be compiled with the flag ``-ffixed-x18``.

	Security
	========

	ShadowCallStack is intended to be a stronger alternative to
	``-fstack-protector``. It protects from non-linear overflows and arbitrary
	memory writes to the return address slot; however, similarly to
	``-fstack-protector`` this protection suffers from race conditions because of
	the call-return semantics on x86_64. There is a short race between the call
	instruction and the first instruction in the function that reads the return
	address where an attacker could overwrite the return address and bypass
	ShadowCallStack. Similarly, there is a time-of-check-to-time-of-use race in the
	function epilog where an attacker could overwrite the return address after it
	has been checked and before it has been returned to. Modifying the call-return
	semantics to fix this on x86_64 would incur an unacceptable performance overhead
	due to return branch prediction.

	The instrumentation makes use of the ``gs`` segment register on x86_64,
	or the ``x18`` register on aarch64, to reference the shadow call stack
	meaning that references to the shadow call stack do not have to be stored in
	memory. This makes it possible to implement a runtime that avoids exposing
	the address of the shadow call stack to attackers that can read arbitrary
	memory. However, attackers could still try to exploit side channels exposed
	by the operating system `[1]`_ `[2]`_ or processor `[3]`_ to discover the
	address of the shadow call stack.

	.. _`[1]`: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
	.. _`[2]`: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
	.. _`[3]`: https://www.vusec.net/projects/anc/

	On x86_64, leaf functions are optimized to store the return address in a
	free register and avoid writing to the shadow call stack if a register is
	available. Very short leaf functions are uninstrumented if their execution
	is judged to be shorter than the race condition window intrinsic to the
	instrumentation.

	On aarch64, the architecture's call and return instructions (``bl`` and
	``ret``) operate on a register rather than the stack, which means that
	leaf functions are generally protected from return address overwrites even
	without ShadowCallStack. It also means that ShadowCallStack on aarch64 is not
	vulnerable to the same types of time-of-check-to-time-of-use races as x86_64.

	Usage
	=====

	To enable ShadowCallStack, just pass the ``-fsanitize=shadow-call-stack``
	flag to both compile and link command lines. On aarch64, you also need to pass
	``-ffixed-x18`` unless your target already reserves ``x18``.

	Low-level API
	-------------

	``__has_feature(shadow_call_stack)``
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	In some cases one may need to execute different code depending on whether
	ShadowCallStack is enabled. The macro ``__has_feature(shadow_call_stack)`` can
	be used for this purpose.

	.. code-block:: c

	#if defined(__has_feature)
	# if __has_feature(shadow_call_stack)
	// code that builds only under ShadowCallStack
	# endif
	#endif

	``__attribute__((no_sanitize("shadow-call-stack")))``
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Use ``__attribute__((no_sanitize("shadow-call-stack")))`` on a function
	declaration to specify that the shadow call stack instrumentation should not be
	applied to that function, even if enabled globally.

	Example
	=======

	The following example code:

	.. code-block:: c++

	int foo() {
	return bar() + 1;
	}

	Generates the following x86_64 assembly when compiled with ``-O2``:

	.. code-block:: gas

	push %rax
	callq bar
	add $0x1,%eax
	pop %rcx
	retq

	or the following aarch64 assembly:

	.. code-block:: none

	stp x29, x30, [sp, #-16]!
	mov x29, sp
	bl bar
	add w0, w0, #1
	ldp x29, x30, [sp], #16
	ret


	Adding ``-fsanitize=shadow-call-stack`` would output the following x86_64
	assembly:

	.. code-block:: gas

	mov (%rsp),%r10
	xor %r11,%r11
	addq $0x8,%gs:(%r11)
	mov %gs:(%r11),%r11
	mov %r10,%gs:(%r11)
	push %rax
	callq bar
	add $0x1,%eax
	pop %rcx
	xor %r11,%r11
	mov %gs:(%r11),%r10
	mov %gs:(%r10),%r10
	subq $0x8,%gs:(%r11)
	cmp %r10,(%rsp)
	jne trap
	retq

	trap:
	ud2

	or the following aarch64 assembly:

	.. code-block:: none

	str x30, [x18], #8
	stp x29, x30, [sp, #-16]!
	mov x29, sp
	bl bar
	add w0, w0, #1
	ldp x29, x30, [sp], #16
	ldr x30, [x18, #-8]!
	ret