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::
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
59 requires 2 pages, one for the object itself and the other one used as a guard
60 page; object pages are interleaved with guard pages, and every object page is
61 therefore surrounded by two guard pages.
70 Note: On architectures that support huge pages, KFENCE will ensure that the
71 pool is using pages of size ``PAGE_SIZE``. This will result in additional page
77 A typical out-of-bounds access looks like this::
80     BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa6/0x234
82     Out-of-bounds read at 0xffff8c3f2e291fff (1B left of kfence-#72):
89     kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2e29201f, size=32, cache=kmalloc-32
99     CPU: 0 PID: 484 Comm: kunit_try_catch Not tainted 5.13.0-rc3+ #7
100     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
108 Use-after-free accesses are reported as::
111     BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143
113     Use-after-free read at 0xffff8c3f2e2a0000 (in kfence-#79):
120     kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2e2a001f, size=32, cache=kmalloc-32
137     CPU: 2 PID: 488 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
138     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
141 KFENCE also reports on invalid frees, such as double-frees::
146     Invalid free of 0xffff8c3f2e2a4000 (in kfence-#81):
153     kfence-#81: 0xffff8c3f2e2a4000-0xffff8c3f2e2a401f, size=32, cache=kmalloc-32
170     CPU: 1 PID: 490 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
171     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
174 KFENCE also uses pattern-based redzones on the other side of an object's guard
175 page, to detect out-of-bounds writes on the unprotected side of the object.
181     Corrupted memory at 0xffff8c3f2e33aff9 [ 0xac . . . . . . ] (in kfence-#156):
188     kfence-#156: 0xffff8c3f2e33afb0-0xffff8c3f2e33aff8, size=73, cache=kmalloc-96
198     CPU: 7 PID: 502 Comm: kunit_try_catch Tainted: G    B             5.13.0-rc3+ #7
199     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
213 object pages had not yet been allocated::
225     CPU: 4 PID: 124 Comm: kunit_try_catch Tainted: G        W         5.8.0-rc6+ #7
226     Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
240 ----------------------
249 through the main allocator's fast-path by relying on static branches via the
256 page boundaries selected at random. The pages to the left and right of the
257 object page are "guard pages", whose attributes are changed to a protected
260 out-of-bounds access, and marking the page as accessible so that the faulting
263 To detect out-of-bounds writes to memory within the object's page itself,
264 KFENCE also uses pattern-based redzones. For each object page, a redzone is set
265 up for all non-object memory. For typical alignments, the redzone is only
272     ---+-----------+-----------+-----------+-----------+-----------+---
275        | x GUARD x | J : RED-  | x GUARD x | RED-  : J | x GUARD x |
279     ---+-----------+-----------+-----------+-----------+-----------+---
283 and KFENCE reports a use-after-free access. Freed objects are inserted at the
285 first, and the chances of detecting use-after-frees of recently freed objects
292 based on its partial allocation stack trace. A side-effect is that this also
293 limits frequent long-lived allocations (e.g. pagecache) of the same source
300 ---------
305 .. kernel-doc:: include/linux/kfence.h
313 -------------
315 In userspace, a similar approach is taken by `GWP-ASan
316 <http://llvm.org/docs/GwpAsan.html>`_. GWP-ASan also relies on guard pages and
318 directly influenced by GWP-ASan, and can be seen as its kernel sibling. Another
319 similar but non-sampling approach, that also inspired the name "KFENCE", can be
329 different target environments. For instance, KASAN is the better debugging-aid,