Documentation/dev-tools/kasan.rst

5 --------
8 find out-of-bound and use-after-free bugs. KASAN has two modes: generic KASAN
9 (similar to userspace ASan) and software tag-based KASAN (similar to userspace
12 KASAN uses compile-time instrumentation to insert validity checks before every
17 out-of-bounds accesses for global variables is only supported since Clang 11.
19 Tag-based KASAN is only supported in Clang.
22 riscv architectures, and tag-based KASAN is supported only for arm64.
25 -----
32 CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN).
36 smaller binary while the latter is 1.1 - 2 times faster.
47 - For a single file (e.g. main.o)::
51 - For all files in one directory::
58 A typical out-of-bounds access generic KASAN report looks like this::
61     BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan]
64     CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698
65     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014
112      which belongs to the cache kmalloc-128 of size 128
114      128-byte region [ffff8801f44ec300, ffff8801f44ec380)
116     page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0
135 freed (in case of a use-after-free bug report). Next comes a description of
145 that the first N bytes are accessible, and other (8 - N) bytes are not;
146 any negative value indicates that the entire 8-byte word is inaccessible.
153 For tag-based KASAN this last report section shows the memory tags around the
158 ----------------------
165 to access, and use compile-time instrumentation to insert checks of shadow
169 to cover 128TB on x86_64) and uses direct mapping with a scale and offset to
183 Compile-time instrumentation is used to insert memory access checks. Compiler
190 This option significantly enlarges kernel but it gives x1.1-x2 performance
196 Software tag-based KASAN
199 Tag-based KASAN uses the Top Byte Ignore (TBI) feature of modern arm64 CPUs to
201 uses shadow memory to store memory tags associated with each 16-byte memory
204 On each memory allocation tag-based KASAN generates a random tag, tags the
206 Software tag-based KASAN uses compile-time instrumentation to insert checks
209 memory. In case of a tag mismatch tag-based KASAN prints a bug report.
211 Software tag-based KASAN also has two instrumentation modes (outline, that
213 memory checks inline). With outline instrumentation mode, a bug report is
218 A potential expansion of this mode is a hardware tag-based mode, which would
223 --------------------------------------------
238 for the linear mapping (and potentially other small areas). For all
239 other areas - such as vmalloc and vmemmap space - a single read-only
240 page is mapped over the shadow area. This read-only shadow page
243 This presents a problem for modules: they do not live in the linear
244 mapping, but in a dedicated module space. By hooking in to the module
250 lives in vmalloc space, it will be shadowed by the read-only page, and
264 page of shadow space. Allocating a full shadow page per mapping would
270 a backing page when a mapping in vmalloc space uses a particular page
280 unmapped. This will require changes in arch-specific code.
286 --------------------------------------------------
297         ok 28 - kmalloc_double_kzfree
303         not ok 4 - kmalloc_large_oob_right
308         Expected kasan_data->report_expected == kasan_data->report_found, but
309         kasan_data->report_expected == 1
310         kasan_data->report_found == 0
311         not ok 28 - kmalloc_double_kzfree
316         ok 1 - kasan
320         not ok 1 - kasan
329 (2) Built-In
332 With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in
334 tests enabled will run and print the results at boot as a late-init
340 With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, we can also
343 …cumentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ for more up-to-d…
346 .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html
351 ``CONFIG_KASAN`` built-in. The type of error expected and the