Commit 1ff29758 authored by Kees Cook's avatar Kees Cook
Browse files

randomize_kstack: Improve docs on requirements/rationale 

There were some recent questions about where and why to use the
random_kstack routines when applying them to new architectures[1].
Update the header comments to reflect the design choices for the
routines.

[1] https://lore.kernel.org/lkml/1652173338.7bltwybi0c.astroid@bobo.none



Cc: Nicholas Piggin <npiggin@gmail.com>
Cc: Xiu Jianfeng <xiujianfeng@huawei.com>
Signed-off-by: default avatarKees Cook <keescook@chromium.org>
parent 8c6a490e

include/linux/randomize_kstack.h

+24 −3
Original line number Diff line number Diff line
@@ -40,10 +40,14 @@ DECLARE_PER_CPU(u32, kstack_offset); 
 */

#define KSTACK_OFFSET_MAX(x)	((x) & 0x3FF)



/*

 * These macros must be used during syscall entry when interrupts and

/**

 * add_random_kstack_offset - Increase stack utilization by previously

 *			      chosen random offset

 *

 * This should be used in the syscall entry path when interrupts and

 * preempt are disabled, and after user registers have been stored to

 * the stack.

 * the stack. For testing the resulting entropy, please see:

 * tools/testing/selftests/lkdtm/stack-entropy.sh

 */

#define add_random_kstack_offset() do {					\

	if (static_branch_maybe(CONFIG_RANDOMIZE_KSTACK_OFFSET_DEFAULT,	\
@@ -55,6 +59,23 @@ DECLARE_PER_CPU(u32, kstack_offset); 
	}								\

} while (0)



/**

 * choose_random_kstack_offset - Choose the random offset for the next

 *				 add_random_kstack_offset()

 *

 * This should only be used during syscall exit when interrupts and

 * preempt are disabled. This position in the syscall flow is done to

 * frustrate attacks from userspace attempting to learn the next offset:

 * - Maximize the timing uncertainty visible from userspace: if the

 *   offset is chosen at syscall entry, userspace has much more control

 *   over the timing between choosing offsets. "How long will we be in

 *   kernel mode?" tends to be more difficult to predict than "how long

 *   will we be in user mode?"

 * - Reduce the lifetime of the new offset sitting in memory during

 *   kernel mode execution. Exposure of "thread-local" memory content

 *   (e.g. current, percpu, etc) tends to be easier than arbitrary

 *   location memory exposure.

 */

#define choose_random_kstack_offset(rand) do {				\

	if (static_branch_maybe(CONFIG_RANDOMIZE_KSTACK_OFFSET_DEFAULT,	\

				&randomize_kstack_offset)) {		\