Documentation/dev-tools/kasan.rst

5 --------
7 KernelAddressSANitizer (KASAN) is a dynamic memory safety error detector
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
15 validity checks before every memory access, and therefore require a compiler
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 -----
30 To enable KASAN configure kernel with::
34 and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN),
35 CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN), and
36 CONFIG_KASAN_HW_TAGS (to enable hardware tag-based KASAN).
38 For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and
40 The former produces smaller binary while the latter is 1.1 - 2 times faster.
42 Both software KASAN modes work with both SLUB and SLAB memory allocators,
43 while the hardware tag-based KASAN currently only support SLUB.
47 To augment reports with last allocation and freeing stack of the physical page,
48 it is recommended to enable also CONFIG_PAGE_OWNER and boot with page_owner=on.
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]
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
106     The buggy address belongs to the object at ffff8801f44ec300
107      which belongs to the cache kmalloc-128 of size 128
109      128-byte region [ffff8801f44ec300, ffff8801f44ec380)
110     The buggy address belongs to the page:
117     Memory state around the buggy address:
128 access, a stack trace of where the accessed memory was allocated (in case bad
130 freed (in case of a use-after-free bug report). Next comes a description of
131 the accessed slab object and information about the accessed memory page.
133 In the last section the report shows memory state around the accessed address.
134 Internally KASAN tracks memory state separately for each memory granule, which
136 memory state section of the report shows the state of one of the memory
139 For generic KASAN the size of each memory granule is 8. The state of each
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
146 negative values to distinguish between different kinds of inaccessible memory
147 like redzones or freed memory (see mm/kasan/kasan.h).
149 In the report above the arrows point to the shadow byte 03, which means that
150 the accessed address is partially accessible. For tag-based KASAN modes this
151 last report section shows the memory tags around the accessed address
157 Hardware tag-based KASAN mode (see the section about various modes below) is
159 boot parameters that allow to disable KASAN competely or otherwise control
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
183 Software KASAN modes use compiler instrumentation to insert validity checks.
185 therefore needs to be disabled. To disable instrumentation for specific files
186 or directories, add a line similar to the following to the respective kernel
189 - For a single file (e.g. main.o)::
193 - For all files in one directory::
199 ----------------------
204 From a high level perspective, KASAN's approach to memory error detection is
205 similar to that of kmemcheck: use shadow memory to record whether each byte of
206 memory is safe to access, and use compile-time instrumentation to insert checks
207 of shadow memory on each memory access.
209 Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB
210 to cover 128TB on x86_64) and uses direct mapping with a scale and offset to
211 translate a memory address to its corresponding shadow address.
213 Here is the function which translates an address to its corresponding shadow
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
227 access is valid or not by checking corresponding shadow memory.
229 GCC 5.0 has possibility to perform inline instrumentation. Instead of making
230 function calls GCC directly inserts the code to check the shadow memory.
231 This option significantly enlarges kernel but it gives x1.1-x2 performance
234 Generic KASAN also reports the last 2 call stacks to creation of work that
235 potentially has access to an object. Call stacks for the following are shown:
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
250 to store a pointer tag in the top byte of kernel pointers. Like generic KASAN
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
255 the allocated memory with this tag, and embeds this tag into the returned
258 Software tag-based KASAN uses compile-time instrumentation to insert checks
259 before each memory access. These checks make sure that tag of the memory that
260 is being accessed is equal to tag of the pointer that is used to access this
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
264 emits callbacks to check memory accesses; and inline, that performs the shadow
265 memory checks inline). With outline instrumentation mode, a bug report is
268 brk handler is used to print bug reports.
270 Software tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through
272 reserved to tag freed memory regions.
274 Software tag-based KASAN currently only supports tagging of
275 kmem_cache_alloc/kmalloc and page_alloc memory.
277 Hardware tag-based KASAN
280 Hardware tag-based KASAN is similar to the software mode in concept, but uses
281 hardware memory tagging support instead of compiler instrumentation and
282 shadow memory.
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
288 Special arm64 instructions are used to assign memory tags for each allocation.
289 Same tags are assigned to pointers to those allocations. On every memory
290 access, hardware makes sure that tag of the memory that is being accessed is
291 equal to tag of the pointer that is used to access this memory. In case of a
294 Hardware tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through
296 reserved to tag freed memory regions.
298 Hardware tag-based KASAN currently only supports tagging of
299 kmem_cache_alloc/kmalloc and page_alloc memory.
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
311 What memory accesses are sanitised by KASAN?
312 --------------------------------------------
314 The kernel maps memory in a number of different parts of the address
320 real memory to support a real shadow region for every address that
326 By default, architectures only map real memory over the shadow region
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
330 declares all memory accesses as permitted.
333 mapping, but in a dedicated module space. By hooking in to the module
334 allocator, KASAN can temporarily map real shadow memory to cover
335 them. This allows detection of invalid accesses to module globals, for
339 lives in vmalloc space, it will be shadowed by the read-only page, and
340 the kernel will fault when trying to set up the shadow data for stack
347 cost of greater memory usage. Currently this is only supported on x86.
350 allocating real shadow memory to back the mappings.
354 therefore be wasteful. Furthermore, to ensure that different mappings
355 use different shadow pages, mappings would have to be aligned to
363 KASAN hooks into the vmap infrastructure to lazily clean up unused shadow
364 memory.
366 To avoid the difficulties around swapping mappings around, KASAN expects
369 unmapped. This will require changes in arch-specific code.
375 ----------------------------------------------------
388 Each KUnit-compatible KASAN test prints a KASAN report if an error is detected.
393         ok 28 - kmalloc_double_kzfree
395 When a test fails due to a failed ``kmalloc``::
399         not ok 4 - kmalloc_large_oob_right
401 When a test fails due to a missing KASAN report::
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.
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
438 possible use ``kunit_tool`` to see the results of these and other KUnit tests
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