Documentation/dev-tools/kfence.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 Kernel Electric-Fence (KFENCE)
7 Kernel Electric-Fence (KFENCE) is a low-overhead sampling-based memory safety
8 error detector. KFENCE detects heap out-of-bounds access, use-after-free, and
9 invalid-free errors.
15 non-production test workloads. One way to quickly achieve a large enough total
19 -----
26 ``kfence.sample_interval`` to non-zero value), configure the kernel with::
44 The sample interval controls a timer that sets up KFENCE allocations. By
45 default, to keep the real sample interval predictable, the normal timer also
46 causes CPU wake-ups when the system is completely idle. This may be undesirable
47 on power-constrained systems. The boot parameter ``kfence.deferrable=1``
48 instead switches to a "deferrable" timer which does not force CPU wake-ups on
53    The KUnit test suite is very likely to fail when using a deferrable timer
58 kernel boot parameter ``kfence.burst`` can be set to a non-zero value which
84 A typical out-of-bounds access looks like this::
87     BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa6/0x234
89     Out-of-bounds read at 0xffff8c3f2e291fff (1B left of kfence-#72):
96     kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2e29201f, size=32, cache=kmalloc-32
98     allocated by task 484 on cpu 0 at 32.919330s:
106     CPU: 0 PID: 484 Comm: kunit_try_catch Not tainted 5.13.0-rc3+ #7
107     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
115 Use-after-free accesses are reported as::
118     BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143
120     Use-after-free read at 0xffff8c3f2e2a0000 (in kfence-#79):
127     kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2e2a001f, size=32, cache=kmalloc-32
129     allocated by task 488 on cpu 2 at 33.871326s:
137     freed by task 488 on cpu 2 at 33.871358s:
144     CPU: 2 PID: 488 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
145     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
148 KFENCE also reports on invalid frees, such as double-frees::
153     Invalid free of 0xffff8c3f2e2a4000 (in kfence-#81):
160     kfence-#81: 0xffff8c3f2e2a4000-0xffff8c3f2e2a401f, size=32, cache=kmalloc-32
162     allocated by task 490 on cpu 1 at 34.175321s:
170     freed by task 490 on cpu 1 at 34.175348s:
177     CPU: 1 PID: 490 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
178     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
181 KFENCE also uses pattern-based redzones on the other side of an object's guard
182 page, to detect out-of-bounds writes on the unprotected side of the object.
188     Corrupted memory at 0xffff8c3f2e33aff9 [ 0xac . . . . . . ] (in kfence-#156):
195     kfence-#156: 0xffff8c3f2e33afb0-0xffff8c3f2e33aff8, size=73, cache=kmalloc-96
197     allocated by task 502 on cpu 7 at 42.159302s:
205     CPU: 7 PID: 502 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
206     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
232     CPU: 4 PID: 124 Comm: kunit_try_catch Tainted: G        W         5.8.0-rc6+ #7
233     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
247 ----------------------
252 sizes up to PAGE_SIZE are supported). At this point, the timer is reset, and
256 through the main allocator's fast-path by relying on static branches via the
267 out-of-bounds access, and marking the page as accessible so that the faulting
270 To detect out-of-bounds writes to memory within the object's page itself,
271 KFENCE also uses pattern-based redzones. For each object page, a redzone is set
272 up for all non-object memory. For typical alignments, the redzone is only
279     ---+-----------+-----------+-----------+-----------+-----------+---
282        | x GUARD x | J : RED-  | x GUARD x | RED-  : J | x GUARD x |
286     ---+-----------+-----------+-----------+-----------+-----------+---
290 and KFENCE reports a use-after-free access. Freed objects are inserted at the
292 first, and the chances of detecting use-after-frees of recently freed objects
299 based on its partial allocation stack trace. A side-effect is that this also
300 limits frequent long-lived allocations (e.g. pagecache) of the same source
307 ---------
312 .. kernel-doc:: include/linux/kfence.h
320 -------------
322 In userspace, a similar approach is taken by `GWP-ASan
323 <http://llvm.org/docs/GwpAsan.html>`_. GWP-ASan also relies on guard pages and
325 directly influenced by GWP-ASan, and can be seen as its kernel sibling. Another
326 similar but non-sampling approach, that also inspired the name "KFENCE", can be
336 different target environments. For instance, KASAN is the better debugging-aid,
339 that cannot afford to enable KASAN, however, would benefit from using KFENCE to