About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kasan.txt


Based on kernel version 4.8. Page generated on 2016-10-06 23:16 EST.

1	KernelAddressSanitizer (KASAN)
2	==============================
3	
4	0. Overview
5	===========
6	
7	KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
8	a fast and comprehensive solution for finding use-after-free and out-of-bounds
9	bugs.
10	
11	KASAN uses compile-time instrumentation for checking every memory access,
12	therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is
13	required for detection of out-of-bounds accesses to stack or global variables.
14	
15	Currently KASAN is supported only for x86_64 architecture.
16	
17	1. Usage
18	========
19	
20	To enable KASAN configure kernel with:
21	
22		  CONFIG_KASAN = y
23	
24	and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and
25	inline are compiler instrumentation types. The former produces smaller binary
26	the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC
27	version 5.0 or later.
28	
29	KASAN works with both SLUB and SLAB memory allocators.
30	For better bug detection and nicer reporting, enable CONFIG_STACKTRACE.
31	
32	To disable instrumentation for specific files or directories, add a line
33	similar to the following to the respective kernel Makefile:
34	
35	        For a single file (e.g. main.o):
36	                KASAN_SANITIZE_main.o := n
37	
38	        For all files in one directory:
39	                KASAN_SANITIZE := n
40	
41	1.1 Error reports
42	=================
43	
44	A typical out of bounds access report looks like this:
45	
46	==================================================================
47	BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
48	Write of size 1 by task modprobe/1689
49	=============================================================================
50	BUG kmalloc-128 (Not tainted): kasan error
51	-----------------------------------------------------------------------------
52	
53	Disabling lock debugging due to kernel taint
54	INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
55	 __slab_alloc+0x4b4/0x4f0
56	 kmem_cache_alloc_trace+0x10b/0x190
57	 kmalloc_oob_right+0x3d/0x75 [test_kasan]
58	 init_module+0x9/0x47 [test_kasan]
59	 do_one_initcall+0x99/0x200
60	 load_module+0x2cb3/0x3b20
61	 SyS_finit_module+0x76/0x80
62	 system_call_fastpath+0x12/0x17
63	INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
64	INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
65	
66	Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a  ........ZZZZZZZZ
67	Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
68	Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
69	Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
70	Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
71	Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
72	Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
73	Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
74	Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5  kkkkkkkkkkkkkkk.
75	Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc                          ........
76	Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a                          ZZZZZZZZ
77	CPU: 0 PID: 1689 Comm: modprobe Tainted: G    B          3.18.0-rc1-mm1+ #98
78	Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
79	 ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78
80	 ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8
81	 ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558
82	Call Trace:
83	 [<ffffffff81cc68ae>] dump_stack+0x46/0x58
84	 [<ffffffff811fd848>] print_trailer+0xf8/0x160
85	 [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
86	 [<ffffffff811ff0f5>] object_err+0x35/0x40
87	 [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
88	 [<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0
89	 [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
90	 [<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40
91	 [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
92	 [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
93	 [<ffffffff8120a995>] __asan_store1+0x75/0xb0
94	 [<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan]
95	 [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
96	 [<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan]
97	 [<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan]
98	 [<ffffffff810002d9>] do_one_initcall+0x99/0x200
99	 [<ffffffff811e4e5c>] ? __vunmap+0xec/0x160
100	 [<ffffffff81114f63>] load_module+0x2cb3/0x3b20
101	 [<ffffffff8110fd70>] ? m_show+0x240/0x240
102	 [<ffffffff81115f06>] SyS_finit_module+0x76/0x80
103	 [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17
104	Memory state around the buggy address:
105	 ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
106	 ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc
107	 ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
108	 ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
109	 ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00
110	>ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
111	                                                 ^
112	 ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
113	 ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
114	 ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb
115	 ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
116	 ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
117	==================================================================
118	
119	The header of the report discribe what kind of bug happened and what kind of
120	access caused it. It's followed by the description of the accessed slub object
121	(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and
122	the description of the accessed memory page.
123	
124	In the last section the report shows memory state around the accessed address.
125	Reading this part requires some understanding of how KASAN works.
126	
127	The state of each 8 aligned bytes of memory is encoded in one shadow byte.
128	Those 8 bytes can be accessible, partially accessible, freed or be a redzone.
129	We use the following encoding for each shadow byte: 0 means that all 8 bytes
130	of the corresponding memory region are accessible; number N (1 <= N <= 7) means
131	that the first N bytes are accessible, and other (8 - N) bytes are not;
132	any negative value indicates that the entire 8-byte word is inaccessible.
133	We use different negative values to distinguish between different kinds of
134	inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h).
135	
136	In the report above the arrows point to the shadow byte 03, which means that
137	the accessed address is partially accessible.
138	
139	
140	2. Implementation details
141	=========================
142	
143	From a high level, our approach to memory error detection is similar to that
144	of kmemcheck: use shadow memory to record whether each byte of memory is safe
145	to access, and use compile-time instrumentation to check shadow memory on each
146	memory access.
147	
148	AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory
149	(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and
150	offset to translate a memory address to its corresponding shadow address.
151	
152	Here is the function which translates an address to its corresponding shadow
153	address:
154	
155	static inline void *kasan_mem_to_shadow(const void *addr)
156	{
157		return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
158			+ KASAN_SHADOW_OFFSET;
159	}
160	
161	where KASAN_SHADOW_SCALE_SHIFT = 3.
162	
163	Compile-time instrumentation used for checking memory accesses. Compiler inserts
164	function calls (__asan_load*(addr), __asan_store*(addr)) before each memory
165	access of size 1, 2, 4, 8 or 16. These functions check whether memory access is
166	valid or not by checking corresponding shadow memory.
167	
168	GCC 5.0 has possibility to perform inline instrumentation. Instead of making
169	function calls GCC directly inserts the code to check the shadow memory.
170	This option significantly enlarges kernel but it gives x1.1-x2 performance
171	boost over outline instrumented kernel.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog