Commit | Line | Data |
---|---|---|
2757aafa JC |
1 | The Kernel Address Sanitizer (KASAN) |
2 | ==================================== | |
3 | ||
4 | Overview | |
5 | -------- | |
6 | ||
c2ec0c8f AK |
7 | Kernel Address Sanitizer (KASAN) is a dynamic memory safety error detector |
8 | designed to find out-of-bounds and use-after-free bugs. | |
2757aafa | 9 | |
c2ec0c8f | 10 | KASAN has three modes: |
2757aafa | 11 | |
c2ec0c8f AK |
12 | 1. Generic KASAN |
13 | 2. Software Tag-Based KASAN | |
14 | 3. Hardware Tag-Based KASAN | |
3cbc37dc | 15 | |
c2ec0c8f AK |
16 | Generic KASAN, enabled with CONFIG_KASAN_GENERIC, is the mode intended for |
17 | debugging, similar to userspace ASan. This mode is supported on many CPU | |
18 | architectures, but it has significant performance and memory overheads. | |
2757aafa | 19 | |
c2ec0c8f AK |
20 | Software Tag-Based KASAN or SW_TAGS KASAN, enabled with CONFIG_KASAN_SW_TAGS, |
21 | can be used for both debugging and dogfood testing, similar to userspace HWASan. | |
22 | This mode is only supported for arm64, but its moderate memory overhead allows | |
23 | using it for testing on memory-restricted devices with real workloads. | |
b3b0e6ac | 24 | |
c2ec0c8f AK |
25 | Hardware Tag-Based KASAN or HW_TAGS KASAN, enabled with CONFIG_KASAN_HW_TAGS, |
26 | is the mode intended to be used as an in-field memory bug detector or as a | |
27 | security mitigation. This mode only works on arm64 CPUs that support MTE | |
28 | (Memory Tagging Extension), but it has low memory and performance overheads and | |
29 | thus can be used in production. | |
b3b0e6ac | 30 | |
c2ec0c8f AK |
31 | For details about the memory and performance impact of each KASAN mode, see the |
32 | descriptions of the corresponding Kconfig options. | |
3cbc37dc | 33 | |
c2ec0c8f AK |
34 | The Generic and the Software Tag-Based modes are commonly referred to as the |
35 | software modes. The Software Tag-Based and the Hardware Tag-Based modes are | |
36 | referred to as the tag-based modes. | |
3cbc37dc | 37 | |
c2ec0c8f AK |
38 | Support |
39 | ------- | |
40 | ||
41 | Architectures | |
42 | ~~~~~~~~~~~~~ | |
43 | ||
44 | Generic KASAN is supported on x86_64, arm, arm64, powerpc, riscv, s390, and | |
45 | xtensa, and the tag-based KASAN modes are supported only on arm64. | |
46 | ||
47 | Compilers | |
48 | ~~~~~~~~~ | |
49 | ||
50 | Software KASAN modes use compile-time instrumentation to insert validity checks | |
51 | before every memory access and thus require a compiler version that provides | |
52 | support for that. The Hardware Tag-Based mode relies on hardware to perform | |
53 | these checks but still requires a compiler version that supports the memory | |
54 | tagging instructions. | |
55 | ||
56 | Generic KASAN requires GCC version 8.3.0 or later | |
57 | or any Clang version supported by the kernel. | |
58 | ||
59 | Software Tag-Based KASAN requires GCC 11+ | |
60 | or any Clang version supported by the kernel. | |
61 | ||
62 | Hardware Tag-Based KASAN requires GCC 10+ or Clang 12+. | |
63 | ||
64 | Memory types | |
65 | ~~~~~~~~~~~~ | |
66 | ||
67 | Generic KASAN supports finding bugs in all of slab, page_alloc, vmap, vmalloc, | |
68 | stack, and global memory. | |
69 | ||
70 | Software Tag-Based KASAN supports slab, page_alloc, vmalloc, and stack memory. | |
71 | ||
72 | Hardware Tag-Based KASAN supports slab, page_alloc, and non-executable vmalloc | |
73 | memory. | |
74 | ||
75 | For slab, both software KASAN modes support SLUB and SLAB allocators, while | |
76 | Hardware Tag-Based KASAN only supports SLUB. | |
2757aafa JC |
77 | |
78 | Usage | |
79 | ----- | |
80 | ||
86e6f08d | 81 | To enable KASAN, configure the kernel with:: |
2757aafa | 82 | |
86e6f08d | 83 | CONFIG_KASAN=y |
2757aafa | 84 | |
c2ec0c8f AK |
85 | and choose between ``CONFIG_KASAN_GENERIC`` (to enable Generic KASAN), |
86 | ``CONFIG_KASAN_SW_TAGS`` (to enable Software Tag-Based KASAN), and | |
87 | ``CONFIG_KASAN_HW_TAGS`` (to enable Hardware Tag-Based KASAN). | |
b3b0e6ac | 88 | |
c2ec0c8f | 89 | For the software modes, also choose between ``CONFIG_KASAN_OUTLINE`` and |
86e6f08d | 90 | ``CONFIG_KASAN_INLINE``. Outline and inline are compiler instrumentation types. |
c2ec0c8f | 91 | The former produces a smaller binary while the latter is up to 2 times faster. |
b3b0e6ac | 92 | |
86e6f08d AK |
93 | To include alloc and free stack traces of affected slab objects into reports, |
94 | enable ``CONFIG_STACKTRACE``. To include alloc and free stack traces of affected | |
95 | physical pages, enable ``CONFIG_PAGE_OWNER`` and boot with ``page_owner=on``. | |
0fe9a448 | 96 | |
2757aafa JC |
97 | Error reports |
98 | ~~~~~~~~~~~~~ | |
99 | ||
836f79a2 | 100 | A typical KASAN report looks like this:: |
2757aafa JC |
101 | |
102 | ================================================================== | |
b3b0e6ac AK |
103 | BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] |
104 | Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 | |
105 | ||
106 | CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 | |
107 | Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014 | |
2757aafa | 108 | Call Trace: |
b3b0e6ac AK |
109 | dump_stack+0x94/0xd8 |
110 | print_address_description+0x73/0x280 | |
111 | kasan_report+0x144/0x187 | |
112 | __asan_report_store1_noabort+0x17/0x20 | |
113 | kmalloc_oob_right+0xa8/0xbc [test_kasan] | |
114 | kmalloc_tests_init+0x16/0x700 [test_kasan] | |
115 | do_one_initcall+0xa5/0x3ae | |
116 | do_init_module+0x1b6/0x547 | |
117 | load_module+0x75df/0x8070 | |
118 | __do_sys_init_module+0x1c6/0x200 | |
119 | __x64_sys_init_module+0x6e/0xb0 | |
120 | do_syscall_64+0x9f/0x2c0 | |
121 | entry_SYSCALL_64_after_hwframe+0x44/0xa9 | |
122 | RIP: 0033:0x7f96443109da | |
123 | RSP: 002b:00007ffcf0b51b08 EFLAGS: 00000202 ORIG_RAX: 00000000000000af | |
124 | RAX: ffffffffffffffda RBX: 000055dc3ee521a0 RCX: 00007f96443109da | |
125 | RDX: 00007f96445cff88 RSI: 0000000000057a50 RDI: 00007f9644992000 | |
126 | RBP: 000055dc3ee510b0 R08: 0000000000000003 R09: 0000000000000000 | |
127 | R10: 00007f964430cd0a R11: 0000000000000202 R12: 00007f96445cff88 | |
128 | R13: 000055dc3ee51090 R14: 0000000000000000 R15: 0000000000000000 | |
129 | ||
130 | Allocated by task 2760: | |
131 | save_stack+0x43/0xd0 | |
132 | kasan_kmalloc+0xa7/0xd0 | |
133 | kmem_cache_alloc_trace+0xe1/0x1b0 | |
134 | kmalloc_oob_right+0x56/0xbc [test_kasan] | |
135 | kmalloc_tests_init+0x16/0x700 [test_kasan] | |
136 | do_one_initcall+0xa5/0x3ae | |
137 | do_init_module+0x1b6/0x547 | |
138 | load_module+0x75df/0x8070 | |
139 | __do_sys_init_module+0x1c6/0x200 | |
140 | __x64_sys_init_module+0x6e/0xb0 | |
141 | do_syscall_64+0x9f/0x2c0 | |
142 | entry_SYSCALL_64_after_hwframe+0x44/0xa9 | |
143 | ||
144 | Freed by task 815: | |
145 | save_stack+0x43/0xd0 | |
146 | __kasan_slab_free+0x135/0x190 | |
147 | kasan_slab_free+0xe/0x10 | |
148 | kfree+0x93/0x1a0 | |
149 | umh_complete+0x6a/0xa0 | |
150 | call_usermodehelper_exec_async+0x4c3/0x640 | |
151 | ret_from_fork+0x35/0x40 | |
152 | ||
153 | The buggy address belongs to the object at ffff8801f44ec300 | |
154 | which belongs to the cache kmalloc-128 of size 128 | |
155 | The buggy address is located 123 bytes inside of | |
156 | 128-byte region [ffff8801f44ec300, ffff8801f44ec380) | |
157 | The buggy address belongs to the page: | |
158 | page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0 | |
159 | flags: 0x200000000000100(slab) | |
160 | raw: 0200000000000100 ffffea0007d11dc0 0000001a0000001a ffff8801f7001640 | |
161 | raw: 0000000000000000 0000000080150015 00000001ffffffff 0000000000000000 | |
162 | page dumped because: kasan: bad access detected | |
163 | ||
2757aafa | 164 | Memory state around the buggy address: |
b3b0e6ac AK |
165 | ffff8801f44ec200: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb |
166 | ffff8801f44ec280: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc | |
167 | >ffff8801f44ec300: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 | |
168 | ^ | |
169 | ffff8801f44ec380: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb | |
170 | ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc | |
2757aafa JC |
171 | ================================================================== |
172 | ||
836f79a2 AK |
173 | The report header summarizes what kind of bug happened and what kind of access |
174 | caused it. It is followed by a stack trace of the bad access, a stack trace of | |
175 | where the accessed memory was allocated (in case a slab object was accessed), | |
176 | and a stack trace of where the object was freed (in case of a use-after-free | |
177 | bug report). Next comes a description of the accessed slab object and the | |
178 | information about the accessed memory page. | |
2757aafa | 179 | |
836f79a2 AK |
180 | In the end, the report shows the memory state around the accessed address. |
181 | Internally, KASAN tracks memory state separately for each memory granule, which | |
625d8673 AK |
182 | is either 8 or 16 aligned bytes depending on KASAN mode. Each number in the |
183 | memory state section of the report shows the state of one of the memory | |
184 | granules that surround the accessed address. | |
185 | ||
c2ec0c8f | 186 | For Generic KASAN, the size of each memory granule is 8. The state of each |
625d8673 | 187 | granule is encoded in one shadow byte. Those 8 bytes can be accessible, |
836f79a2 AK |
188 | partially accessible, freed, or be a part of a redzone. KASAN uses the following |
189 | encoding for each shadow byte: 00 means that all 8 bytes of the corresponding | |
625d8673 AK |
190 | memory region are accessible; number N (1 <= N <= 7) means that the first N |
191 | bytes are accessible, and other (8 - N) bytes are not; any negative value | |
192 | indicates that the entire 8-byte word is inaccessible. KASAN uses different | |
193 | negative values to distinguish between different kinds of inaccessible memory | |
194 | like redzones or freed memory (see mm/kasan/kasan.h). | |
2757aafa | 195 | |
836f79a2 AK |
196 | In the report above, the arrow points to the shadow byte ``03``, which means |
197 | that the accessed address is partially accessible. | |
198 | ||
199 | For tag-based KASAN modes, this last report section shows the memory tags around | |
200 | the accessed address (see the `Implementation details`_ section). | |
201 | ||
202 | Note that KASAN bug titles (like ``slab-out-of-bounds`` or ``use-after-free``) | |
203 | are best-effort: KASAN prints the most probable bug type based on the limited | |
204 | information it has. The actual type of the bug might be different. | |
205 | ||
206 | Generic KASAN also reports up to two auxiliary call stack traces. These stack | |
207 | traces point to places in code that interacted with the object but that are not | |
208 | directly present in the bad access stack trace. Currently, this includes | |
209 | call_rcu() and workqueue queuing. | |
625d8673 AK |
210 | |
211 | Boot parameters | |
212 | ~~~~~~~~~~~~~~~ | |
213 | ||
f3590747 AK |
214 | KASAN is affected by the generic ``panic_on_warn`` command line parameter. |
215 | When it is enabled, KASAN panics the kernel after printing a bug report. | |
216 | ||
217 | By default, KASAN prints a bug report only for the first invalid memory access. | |
218 | With ``kasan_multi_shot``, KASAN prints a report on every invalid access. This | |
219 | effectively disables ``panic_on_warn`` for KASAN reports. | |
220 | ||
c2ec0c8f | 221 | Alternatively, independent of ``panic_on_warn``, the ``kasan.fault=`` boot |
c9d1af2b WL |
222 | parameter can be used to control panic and reporting behaviour: |
223 | ||
224 | - ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN | |
225 | report or also panic the kernel (default: ``report``). The panic happens even | |
226 | if ``kasan_multi_shot`` is enabled. | |
227 | ||
c2ec0c8f | 228 | Hardware Tag-Based KASAN mode (see the section about various modes below) is |
7169487b | 229 | intended for use in production as a security mitigation. Therefore, it supports |
c9d1af2b | 230 | additional boot parameters that allow disabling KASAN or controlling features: |
625d8673 | 231 | |
76bc99e8 | 232 | - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``). |
625d8673 | 233 | |
2d27e585 VF |
234 | - ``kasan.mode=sync``, ``=async`` or ``=asymm`` controls whether KASAN |
235 | is configured in synchronous, asynchronous or asymmetric mode of | |
236 | execution (default: ``sync``). | |
2603f8a7 VF |
237 | Synchronous mode: a bad access is detected immediately when a tag |
238 | check fault occurs. | |
239 | Asynchronous mode: a bad access detection is delayed. When a tag check | |
240 | fault occurs, the information is stored in hardware (in the TFSR_EL1 | |
241 | register for arm64). The kernel periodically checks the hardware and | |
242 | only reports tag faults during these checks. | |
2d27e585 VF |
243 | Asymmetric mode: a bad access is detected synchronously on reads and |
244 | asynchronously on writes. | |
2603f8a7 | 245 | |
8479d7b5 AK |
246 | - ``kasan.vmalloc=off`` or ``=on`` disables or enables tagging of vmalloc |
247 | allocations (default: ``on``). | |
248 | ||
76bc99e8 | 249 | - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack |
1cc4cdb5 | 250 | traces collection (default: ``on``). |
625d8673 | 251 | |
2757aafa JC |
252 | Implementation details |
253 | ---------------------- | |
254 | ||
b3b0e6ac AK |
255 | Generic KASAN |
256 | ~~~~~~~~~~~~~ | |
257 | ||
b8191d7d AK |
258 | Software KASAN modes use shadow memory to record whether each byte of memory is |
259 | safe to access and use compile-time instrumentation to insert shadow memory | |
260 | checks before each memory access. | |
2757aafa | 261 | |
b8191d7d | 262 | Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (16TB |
b3b0e6ac AK |
263 | to cover 128TB on x86_64) and uses direct mapping with a scale and offset to |
264 | translate a memory address to its corresponding shadow address. | |
2757aafa JC |
265 | |
266 | Here is the function which translates an address to its corresponding shadow | |
267 | address:: | |
268 | ||
269 | static inline void *kasan_mem_to_shadow(const void *addr) | |
270 | { | |
b8191d7d | 271 | return (void *)((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) |
2757aafa JC |
272 | + KASAN_SHADOW_OFFSET; |
273 | } | |
274 | ||
275 | where ``KASAN_SHADOW_SCALE_SHIFT = 3``. | |
276 | ||
b3b0e6ac | 277 | Compile-time instrumentation is used to insert memory access checks. Compiler |
b8191d7d AK |
278 | inserts function calls (``__asan_load*(addr)``, ``__asan_store*(addr)``) before |
279 | each memory access of size 1, 2, 4, 8, or 16. These functions check whether | |
280 | memory accesses are valid or not by checking corresponding shadow memory. | |
2757aafa | 281 | |
b8191d7d AK |
282 | With inline instrumentation, instead of making function calls, the compiler |
283 | directly inserts the code to check shadow memory. This option significantly | |
284 | enlarges the kernel, but it gives an x1.1-x2 performance boost over the | |
285 | outline-instrumented kernel. | |
b3b0e6ac | 286 | |
b8191d7d | 287 | Generic KASAN is the only mode that delays the reuse of freed objects via |
625d8673 AK |
288 | quarantine (see mm/kasan/quarantine.c for implementation). |
289 | ||
c2ec0c8f | 290 | Software Tag-Based KASAN |
b3b0e6ac AK |
291 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
292 | ||
c2ec0c8f | 293 | Software Tag-Based KASAN uses a software memory tagging approach to checking |
a6c18d4e | 294 | access validity. It is currently only implemented for the arm64 architecture. |
948e3253 | 295 | |
c2ec0c8f | 296 | Software Tag-Based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs |
a6c18d4e AK |
297 | to store a pointer tag in the top byte of kernel pointers. It uses shadow memory |
298 | to store memory tags associated with each 16-byte memory cell (therefore, it | |
299 | dedicates 1/16th of the kernel memory for shadow memory). | |
b3b0e6ac | 300 | |
c2ec0c8f | 301 | On each memory allocation, Software Tag-Based KASAN generates a random tag, tags |
a6c18d4e | 302 | the allocated memory with this tag, and embeds the same tag into the returned |
948e3253 AK |
303 | pointer. |
304 | ||
c2ec0c8f | 305 | Software Tag-Based KASAN uses compile-time instrumentation to insert checks |
a6c18d4e AK |
306 | before each memory access. These checks make sure that the tag of the memory |
307 | that is being accessed is equal to the tag of the pointer that is used to access | |
c2ec0c8f | 308 | this memory. In case of a tag mismatch, Software Tag-Based KASAN prints a bug |
a6c18d4e | 309 | report. |
b3b0e6ac | 310 | |
c2ec0c8f | 311 | Software Tag-Based KASAN also has two instrumentation modes (outline, which |
a6c18d4e | 312 | emits callbacks to check memory accesses; and inline, which performs the shadow |
b3b0e6ac | 313 | memory checks inline). With outline instrumentation mode, a bug report is |
a6c18d4e AK |
314 | printed from the function that performs the access check. With inline |
315 | instrumentation, a ``brk`` instruction is emitted by the compiler, and a | |
316 | dedicated ``brk`` handler is used to print bug reports. | |
b3b0e6ac | 317 | |
c2ec0c8f | 318 | Software Tag-Based KASAN uses 0xFF as a match-all pointer tag (accesses through |
a6c18d4e | 319 | pointers with the 0xFF pointer tag are not checked). The value 0xFE is currently |
948e3253 AK |
320 | reserved to tag freed memory regions. |
321 | ||
c2ec0c8f | 322 | Hardware Tag-Based KASAN |
948e3253 AK |
323 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
324 | ||
c2ec0c8f | 325 | Hardware Tag-Based KASAN is similar to the software mode in concept but uses |
948e3253 AK |
326 | hardware memory tagging support instead of compiler instrumentation and |
327 | shadow memory. | |
328 | ||
c2ec0c8f | 329 | Hardware Tag-Based KASAN is currently only implemented for arm64 architecture |
948e3253 | 330 | and based on both arm64 Memory Tagging Extension (MTE) introduced in ARMv8.5 |
bb48675e | 331 | Instruction Set Architecture and Top Byte Ignore (TBI). |
948e3253 AK |
332 | |
333 | Special arm64 instructions are used to assign memory tags for each allocation. | |
334 | Same tags are assigned to pointers to those allocations. On every memory | |
bb48675e AK |
335 | access, hardware makes sure that the tag of the memory that is being accessed is |
336 | equal to the tag of the pointer that is used to access this memory. In case of a | |
337 | tag mismatch, a fault is generated, and a report is printed. | |
948e3253 | 338 | |
c2ec0c8f | 339 | Hardware Tag-Based KASAN uses 0xFF as a match-all pointer tag (accesses through |
bb48675e | 340 | pointers with the 0xFF pointer tag are not checked). The value 0xFE is currently |
948e3253 AK |
341 | reserved to tag freed memory regions. |
342 | ||
c2ec0c8f | 343 | If the hardware does not support MTE (pre ARMv8.5), Hardware Tag-Based KASAN |
bb48675e | 344 | will not be enabled. In this case, all KASAN boot parameters are ignored. |
4062c245 | 345 | |
bb48675e AK |
346 | Note that enabling CONFIG_KASAN_HW_TAGS always results in in-kernel TBI being |
347 | enabled. Even when ``kasan.mode=off`` is provided or when the hardware does not | |
4062c245 AK |
348 | support MTE (but supports TBI). |
349 | ||
c2ec0c8f | 350 | Hardware Tag-Based KASAN only reports the first found bug. After that, MTE tag |
7169487b AK |
351 | checking gets disabled. |
352 | ||
96d7d141 AK |
353 | Shadow memory |
354 | ------------- | |
3c5c3cfb | 355 | |
8479d7b5 AK |
356 | The contents of this section are only applicable to software KASAN modes. |
357 | ||
67ca1c0b AK |
358 | The kernel maps memory in several different parts of the address space. |
359 | The range of kernel virtual addresses is large: there is not enough real | |
360 | memory to support a real shadow region for every address that could be | |
361 | accessed by the kernel. Therefore, KASAN only maps real shadow for certain | |
362 | parts of the address space. | |
3c5c3cfb | 363 | |
96d7d141 AK |
364 | Default behaviour |
365 | ~~~~~~~~~~~~~~~~~ | |
3c5c3cfb DA |
366 | |
367 | By default, architectures only map real memory over the shadow region | |
368 | for the linear mapping (and potentially other small areas). For all | |
369 | other areas - such as vmalloc and vmemmap space - a single read-only | |
370 | page is mapped over the shadow area. This read-only shadow page | |
371 | declares all memory accesses as permitted. | |
372 | ||
373 | This presents a problem for modules: they do not live in the linear | |
67ca1c0b AK |
374 | mapping but in a dedicated module space. By hooking into the module |
375 | allocator, KASAN temporarily maps real shadow memory to cover them. | |
376 | This allows detection of invalid accesses to module globals, for example. | |
3c5c3cfb DA |
377 | |
378 | This also creates an incompatibility with ``VMAP_STACK``: if the stack | |
379 | lives in vmalloc space, it will be shadowed by the read-only page, and | |
380 | the kernel will fault when trying to set up the shadow data for stack | |
381 | variables. | |
382 | ||
383 | CONFIG_KASAN_VMALLOC | |
384 | ~~~~~~~~~~~~~~~~~~~~ | |
385 | ||
386 | With ``CONFIG_KASAN_VMALLOC``, KASAN can cover vmalloc space at the | |
67ca1c0b | 387 | cost of greater memory usage. Currently, this is supported on x86, |
8479d7b5 | 388 | arm64, riscv, s390, and powerpc. |
3c5c3cfb | 389 | |
67ca1c0b | 390 | This works by hooking into vmalloc and vmap and dynamically |
3c5c3cfb DA |
391 | allocating real shadow memory to back the mappings. |
392 | ||
393 | Most mappings in vmalloc space are small, requiring less than a full | |
394 | page of shadow space. Allocating a full shadow page per mapping would | |
395 | therefore be wasteful. Furthermore, to ensure that different mappings | |
396 | use different shadow pages, mappings would have to be aligned to | |
1f600626 | 397 | ``KASAN_GRANULE_SIZE * PAGE_SIZE``. |
3c5c3cfb | 398 | |
625d8673 | 399 | Instead, KASAN shares backing space across multiple mappings. It allocates |
3c5c3cfb DA |
400 | a backing page when a mapping in vmalloc space uses a particular page |
401 | of the shadow region. This page can be shared by other vmalloc | |
402 | mappings later on. | |
403 | ||
625d8673 | 404 | KASAN hooks into the vmap infrastructure to lazily clean up unused shadow |
3c5c3cfb DA |
405 | memory. |
406 | ||
625d8673 | 407 | To avoid the difficulties around swapping mappings around, KASAN expects |
3c5c3cfb | 408 | that the part of the shadow region that covers the vmalloc space will |
67ca1c0b AK |
409 | not be covered by the early shadow page but will be left unmapped. |
410 | This will require changes in arch-specific code. | |
3c5c3cfb | 411 | |
67ca1c0b | 412 | This allows ``VMAP_STACK`` support on x86 and can simplify support of |
3c5c3cfb | 413 | architectures that do not have a fixed module region. |
9ab5be97 | 414 | |
96d7d141 AK |
415 | For developers |
416 | -------------- | |
417 | ||
418 | Ignoring accesses | |
419 | ~~~~~~~~~~~~~~~~~ | |
420 | ||
421 | Software KASAN modes use compiler instrumentation to insert validity checks. | |
fe547fca AK |
422 | Such instrumentation might be incompatible with some parts of the kernel, and |
423 | therefore needs to be disabled. | |
424 | ||
425 | Other parts of the kernel might access metadata for allocated objects. | |
426 | Normally, KASAN detects and reports such accesses, but in some cases (e.g., | |
427 | in memory allocators), these accesses are valid. | |
428 | ||
429 | For software KASAN modes, to disable instrumentation for a specific file or | |
430 | directory, add a ``KASAN_SANITIZE`` annotation to the respective kernel | |
96d7d141 AK |
431 | Makefile: |
432 | ||
fe547fca | 433 | - For a single file (e.g., main.o):: |
96d7d141 AK |
434 | |
435 | KASAN_SANITIZE_main.o := n | |
436 | ||
437 | - For all files in one directory:: | |
438 | ||
439 | KASAN_SANITIZE := n | |
440 | ||
fe547fca AK |
441 | For software KASAN modes, to disable instrumentation on a per-function basis, |
442 | use the KASAN-specific ``__no_sanitize_address`` function attribute or the | |
443 | generic ``noinstr`` one. | |
444 | ||
445 | Note that disabling compiler instrumentation (either on a per-file or a | |
446 | per-function basis) makes KASAN ignore the accesses that happen directly in | |
447 | that code for software KASAN modes. It does not help when the accesses happen | |
c2ec0c8f AK |
448 | indirectly (through calls to instrumented functions) or with Hardware |
449 | Tag-Based KASAN, which does not use compiler instrumentation. | |
fe547fca AK |
450 | |
451 | For software KASAN modes, to disable KASAN reports in a part of the kernel code | |
452 | for the current task, annotate this part of the code with a | |
453 | ``kasan_disable_current()``/``kasan_enable_current()`` section. This also | |
454 | disables the reports for indirect accesses that happen through function calls. | |
455 | ||
c2ec0c8f AK |
456 | For tag-based KASAN modes, to disable access checking, use |
457 | ``kasan_reset_tag()`` or ``page_kasan_tag_reset()``. Note that temporarily | |
458 | disabling access checking via ``page_kasan_tag_reset()`` requires saving and | |
459 | restoring the per-page KASAN tag via ``page_kasan_tag``/``page_kasan_tag_set``. | |
96d7d141 AK |
460 | |
461 | Tests | |
462 | ~~~~~ | |
9ab5be97 | 463 | |
fc23c074 AK |
464 | There are KASAN tests that allow verifying that KASAN works and can detect |
465 | certain types of memory corruptions. The tests consist of two parts: | |
625d8673 AK |
466 | |
467 | 1. Tests that are integrated with the KUnit Test Framework. Enabled with | |
468 | ``CONFIG_KASAN_KUNIT_TEST``. These tests can be run and partially verified | |
fc23c074 | 469 | automatically in a few different ways; see the instructions below. |
9ab5be97 | 470 | |
625d8673 | 471 | 2. Tests that are currently incompatible with KUnit. Enabled with |
5d92bdff | 472 | ``CONFIG_KASAN_MODULE_TEST`` and can only be run as a module. These tests can |
fc23c074 | 473 | only be verified manually by loading the kernel module and inspecting the |
625d8673 | 474 | kernel log for KASAN reports. |
9ab5be97 | 475 | |
fc23c074 AK |
476 | Each KUnit-compatible KASAN test prints one of multiple KASAN reports if an |
477 | error is detected. Then the test prints its number and status. | |
625d8673 AK |
478 | |
479 | When a test passes:: | |
9ab5be97 PA |
480 | |
481 | ok 28 - kmalloc_double_kzfree | |
32519c03 | 482 | |
625d8673 | 483 | When a test fails due to a failed ``kmalloc``:: |
9ab5be97 PA |
484 | |
485 | # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 | |
486 | Expected ptr is not null, but is | |
487 | not ok 4 - kmalloc_large_oob_right | |
32519c03 | 488 | |
625d8673 | 489 | When a test fails due to a missing KASAN report:: |
9ab5be97 | 490 | |
3ff16d30 DG |
491 | # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 |
492 | KASAN failure expected in "kfree_sensitive(ptr)", but none occurred | |
493 | not ok 44 - kmalloc_double_kzfree | |
494 | ||
9ab5be97 | 495 | |
625d8673 | 496 | At the end the cumulative status of all KASAN tests is printed. On success:: |
9ab5be97 PA |
497 | |
498 | ok 1 - kasan | |
499 | ||
625d8673 | 500 | Or, if one of the tests failed:: |
9ab5be97 PA |
501 | |
502 | not ok 1 - kasan | |
503 | ||
625d8673 AK |
504 | There are a few ways to run KUnit-compatible KASAN tests. |
505 | ||
506 | 1. Loadable module | |
9ab5be97 | 507 | |
fc23c074 AK |
508 | With ``CONFIG_KUNIT`` enabled, KASAN-KUnit tests can be built as a loadable |
509 | module and run by loading ``test_kasan.ko`` with ``insmod`` or ``modprobe``. | |
9ab5be97 | 510 | |
625d8673 | 511 | 2. Built-In |
9ab5be97 | 512 | |
fc23c074 AK |
513 | With ``CONFIG_KUNIT`` built-in, KASAN-KUnit tests can be built-in as well. |
514 | In this case, the tests will run at boot as a late-init call. | |
9ab5be97 | 515 | |
625d8673 | 516 | 3. Using kunit_tool |
9ab5be97 | 517 | |
fc23c074 AK |
518 | With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it is also |
519 | possible to use ``kunit_tool`` to see the results of KUnit tests in a more | |
520 | readable way. This will not print the KASAN reports of the tests that passed. | |
521 | See `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ | |
522 | for more up-to-date information on ``kunit_tool``. | |
9ab5be97 PA |
523 | |
524 | .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html |