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