Documentation/dev-tools/kasan.rst

5 --------
8 designed to find out-of-bound and use-after-free bugs. KASAN has three modes:
10 1. generic KASAN (similar to userspace ASan),
11 2. software tag-based KASAN (similar to userspace HWASan),
12 3. hardware tag-based KASAN (based on hardware memory tagging).
14 Software KASAN modes (1 and 2) use compile-time instrumentation to insert
20 out-of-bounds accesses for global variables is only supported since Clang 11.
22 Tag-based KASAN is only supported in Clang.
25 and riscv architectures, and tag-based KASAN modes are supported only for arm64.
28 -----
35 CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN), and
36 CONFIG_KASAN_HW_TAGS (to enable hardware tag-based KASAN).
40 The former produces smaller binary while the latter is 1.1 - 2 times faster.
43 while the hardware tag-based KASAN currently only support SLUB.
53 A typical out-of-bounds access generic KASAN report looks like this::
56     BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan]
57     Write of size 1 at addr ffff8801f44ec37b by task insmod/2760
59     CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698
60     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014
107      which belongs to the cache kmalloc-128 of size 128
109      128-byte region [ffff8801f44ec300, ffff8801f44ec380)
111     page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0
130 freed (in case of a use-after-free bug report). Next comes a description of
143 memory region are accessible; number N (1 <= N <= 7) means that the first N
144 bytes are accessible, and other (8 - N) bytes are not; any negative value
145 indicates that the entire 8-byte word is inaccessible. KASAN uses different
150 the accessed address is partially accessible. For tag-based KASAN modes this
157 Hardware tag-based KASAN mode (see the section about various modes below) is
162 - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``).
164 - ``kasan.mode=sync`` or ``=async`` controls whether KASAN is configured in
173 - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack
176 - ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN
189 - For a single file (e.g. main.o)::
193 - For all files in one directory::
199 ----------------------
206 memory is safe to access, and use compile-time instrumentation to insert checks
209 Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB
224 Compile-time instrumentation is used to insert memory access checks. Compiler
226 memory access of size 1, 2, 4, 8 or 16. These functions check whether memory
231 This option significantly enlarges kernel but it gives x1.1-x2 performance
241 Software tag-based KASAN
244 Software tag-based KASAN requires software memory tagging support in the form
245 of HWASan-like compiler instrumentation (see HWASan documentation for details).
247 Software tag-based KASAN is currently only implemented for arm64 architecture.
249 Software tag-based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs
251 it uses shadow memory to store memory tags associated with each 16-byte memory
252 cell (therefore it dedicates 1/16th of the kernel memory for shadow memory).
254 On each memory allocation software tag-based KASAN generates a random tag, tags
258 Software tag-based KASAN uses compile-time instrumentation to insert checks
261 memory. In case of a tag mismatch software tag-based KASAN prints a bug report.
263 Software tag-based KASAN also has two instrumentation modes (outline, that
270 Software tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through
274 Software tag-based KASAN currently only supports tagging of
277 Hardware tag-based KASAN
280 Hardware tag-based KASAN is similar to the software mode in concept, but uses
284 Hardware tag-based KASAN is currently only implemented for arm64 architecture
285 and based on both arm64 Memory Tagging Extension (MTE) introduced in ARMv8.5
294 Hardware tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through
298 Hardware tag-based KASAN currently only supports tagging of
301 If the hardware doesn't support MTE (pre ARMv8.5), hardware tag-based KASAN
304 Note, that enabling CONFIG_KASAN_HW_TAGS always results in in-kernel TBI being
308 Hardware tag-based KASAN only reports the first found bug. After that MTE tag
312 --------------------------------------------
328 other areas - such as vmalloc and vmemmap space - a single read-only
329 page is mapped over the shadow area. This read-only shadow page
339 lives in vmalloc space, it will be shadowed by the read-only page, and
369 unmapped. This will require changes in arch-specific code.
375 ----------------------------------------------------
379 1. Tests that are integrated with the KUnit Test Framework. Enabled with
388 Each KUnit-compatible KASAN test prints a KASAN report if an error is detected.
393         ok 28 - kmalloc_double_kzfree
399         not ok 4 - kmalloc_large_oob_right
404         Expected kasan_data->report_expected == kasan_data->report_found, but
405         kasan_data->report_expected == 1
406         kasan_data->report_found == 0
407         not ok 28 - kmalloc_double_kzfree
411         ok 1 - kasan
415         not ok 1 - kasan
418 There are a few ways to run KUnit-compatible KASAN tests.
420 1. Loadable module
427 2. Built-In
430 With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in
432 will run and print the results at boot as a late-init call.
437 With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it's also
440 passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html…
441 for more up-to-date information on ``kunit_tool``.
443 .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html