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