1 .. SPDX-License-Identifier: GPL-2.0
2 .. Copyright (C) 2020, Google LLC.
3
4 Kernel Electric-Fence (KFENCE)
5 ==============================
6
7 Kernel Electric-Fence (KFENCE) is a low-overhe
8 error detector. KFENCE detects heap out-of-bou
9 invalid-free errors.
10
11 KFENCE is designed to be enabled in production
12 performance overhead. Compared to KASAN, KFENC
13 precision. The main motivation behind KFENCE's
14 total uptime KFENCE will detect bugs in code p
15 non-production test workloads. One way to quic
16 uptime is when the tool is deployed across a l
17
18 Usage
19 -----
20
21 To enable KFENCE, configure the kernel with::
22
23 CONFIG_KFENCE=y
24
25 To build a kernel with KFENCE support, but dis
26 ``kfence.sample_interval`` to non-zero value),
27
28 CONFIG_KFENCE=y
29 CONFIG_KFENCE_SAMPLE_INTERVAL=0
30
31 KFENCE provides several other configuration op
32 the respective help text in ``lib/Kconfig.kfen
33
34 Tuning performance
35 ~~~~~~~~~~~~~~~~~~
36
37 The most important parameter is KFENCE's sampl
38 the kernel boot parameter ``kfence.sample_inte
39 sample interval determines the frequency with
40 guarded by KFENCE. The default is configurable
41 ``CONFIG_KFENCE_SAMPLE_INTERVAL``. Setting ``k
42 disables KFENCE.
43
44 The sample interval controls a timer that sets
45 default, to keep the real sample interval pred
46 causes CPU wake-ups when the system is complet
47 on power-constrained systems. The boot paramet
48 instead switches to a "deferrable" timer which
49 idle systems, at the risk of unpredictable sam
50 configurable via the Kconfig option ``CONFIG_K
51
52 .. warning::
53 The KUnit test suite is very likely to fail
54 since it currently causes very unpredictabl
55
56 By default KFENCE will only sample 1 heap allo
57 interval. *Burst mode* allows to sample succes
58 kernel boot parameter ``kfence.burst`` can be
59 denotes the *additional* successive allocation
60 setting ``kfence.burst=N`` means that ``1 + N`
61 attempted through KFENCE for each sample inter
62
63 The KFENCE memory pool is of fixed size, and i
64 further KFENCE allocations occur. With ``CONFI
65 255), the number of available guarded objects
66 requires 2 pages, one for the object itself an
67 page; object pages are interleaved with guard
68 therefore surrounded by two guard pages.
69
70 The total memory dedicated to the KFENCE memor
71
72 ( #objects + 1 ) * 2 * PAGE_SIZE
73
74 Using the default config, and assuming a page
75 dedicating 2 MiB to the KFENCE memory pool.
76
77 Note: On architectures that support huge pages
78 pool is using pages of size ``PAGE_SIZE``. Thi
79 tables being allocated.
80
81 Error reports
82 ~~~~~~~~~~~~~
83
84 A typical out-of-bounds access looks like this
85
86 ==========================================
87 BUG: KFENCE: out-of-bounds read in test_ou
88
89 Out-of-bounds read at 0xffff8c3f2e291fff (
90 test_out_of_bounds_read+0xa6/0x234
91 kunit_try_run_case+0x61/0xa0
92 kunit_generic_run_threadfn_adapter+0x16/0
93 kthread+0x176/0x1b0
94 ret_from_fork+0x22/0x30
95
96 kfence-#72: 0xffff8c3f2e292000-0xffff8c3f2
97
98 allocated by task 484 on cpu 0 at 32.91933
99 test_alloc+0xfe/0x738
100 test_out_of_bounds_read+0x9b/0x234
101 kunit_try_run_case+0x61/0xa0
102 kunit_generic_run_threadfn_adapter+0x16/0
103 kthread+0x176/0x1b0
104 ret_from_fork+0x22/0x30
105
106 CPU: 0 PID: 484 Comm: kunit_try_catch Not
107 Hardware name: QEMU Standard PC (i440FX +
108 ==========================================
109
110 The header of the report provides a short summ
111 the access. It is followed by more detailed in
112 its origin. Note that, real kernel addresses a
113 kernel command line option ``no_hash_pointers`
114
115 Use-after-free accesses are reported as::
116
117 ==========================================
118 BUG: KFENCE: use-after-free read in test_u
119
120 Use-after-free read at 0xffff8c3f2e2a0000
121 test_use_after_free_read+0xb3/0x143
122 kunit_try_run_case+0x61/0xa0
123 kunit_generic_run_threadfn_adapter+0x16/0
124 kthread+0x176/0x1b0
125 ret_from_fork+0x22/0x30
126
127 kfence-#79: 0xffff8c3f2e2a0000-0xffff8c3f2
128
129 allocated by task 488 on cpu 2 at 33.87132
130 test_alloc+0xfe/0x738
131 test_use_after_free_read+0x76/0x143
132 kunit_try_run_case+0x61/0xa0
133 kunit_generic_run_threadfn_adapter+0x16/0
134 kthread+0x176/0x1b0
135 ret_from_fork+0x22/0x30
136
137 freed by task 488 on cpu 2 at 33.871358s:
138 test_use_after_free_read+0xa8/0x143
139 kunit_try_run_case+0x61/0xa0
140 kunit_generic_run_threadfn_adapter+0x16/0
141 kthread+0x176/0x1b0
142 ret_from_fork+0x22/0x30
143
144 CPU: 2 PID: 488 Comm: kunit_try_catch Tain
145 Hardware name: QEMU Standard PC (i440FX +
146 ==========================================
147
148 KFENCE also reports on invalid frees, such as
149
150 ==========================================
151 BUG: KFENCE: invalid free in test_double_f
152
153 Invalid free of 0xffff8c3f2e2a4000 (in kfe
154 test_double_free+0xdc/0x171
155 kunit_try_run_case+0x61/0xa0
156 kunit_generic_run_threadfn_adapter+0x16/0
157 kthread+0x176/0x1b0
158 ret_from_fork+0x22/0x30
159
160 kfence-#81: 0xffff8c3f2e2a4000-0xffff8c3f2
161
162 allocated by task 490 on cpu 1 at 34.17532
163 test_alloc+0xfe/0x738
164 test_double_free+0x76/0x171
165 kunit_try_run_case+0x61/0xa0
166 kunit_generic_run_threadfn_adapter+0x16/0
167 kthread+0x176/0x1b0
168 ret_from_fork+0x22/0x30
169
170 freed by task 490 on cpu 1 at 34.175348s:
171 test_double_free+0xa8/0x171
172 kunit_try_run_case+0x61/0xa0
173 kunit_generic_run_threadfn_adapter+0x16/0
174 kthread+0x176/0x1b0
175 ret_from_fork+0x22/0x30
176
177 CPU: 1 PID: 490 Comm: kunit_try_catch Tain
178 Hardware name: QEMU Standard PC (i440FX +
179 ==========================================
180
181 KFENCE also uses pattern-based redzones on the
182 page, to detect out-of-bounds writes on the un
183 These are reported on frees::
184
185 ==========================================
186 BUG: KFENCE: memory corruption in test_kma
187
188 Corrupted memory at 0xffff8c3f2e33aff9 [ 0
189 test_kmalloc_aligned_oob_write+0xef/0x184
190 kunit_try_run_case+0x61/0xa0
191 kunit_generic_run_threadfn_adapter+0x16/0
192 kthread+0x176/0x1b0
193 ret_from_fork+0x22/0x30
194
195 kfence-#156: 0xffff8c3f2e33afb0-0xffff8c3f
196
197 allocated by task 502 on cpu 7 at 42.15930
198 test_alloc+0xfe/0x738
199 test_kmalloc_aligned_oob_write+0x57/0x184
200 kunit_try_run_case+0x61/0xa0
201 kunit_generic_run_threadfn_adapter+0x16/0
202 kthread+0x176/0x1b0
203 ret_from_fork+0x22/0x30
204
205 CPU: 7 PID: 502 Comm: kunit_try_catch Tain
206 Hardware name: QEMU Standard PC (i440FX +
207 ==========================================
208
209 For such errors, the address where the corrupt
210 invalidly written bytes (offset from the addre
211 representation, '.' denote untouched bytes. In
212 the value written to the invalid address at of
213 denote that no following bytes have been touch
214 only shown if the kernel was booted with ``no_
215 information disclosure otherwise, '!' is used
216 written bytes.
217
218 And finally, KFENCE may also report on invalid
219 where it was not possible to determine an asso
220 object pages had not yet been allocated::
221
222 ==========================================
223 BUG: KFENCE: invalid read in test_invalid_
224
225 Invalid read at 0xffffffffb670b00a:
226 test_invalid_access+0x26/0xe0
227 kunit_try_run_case+0x51/0x85
228 kunit_generic_run_threadfn_adapter+0x16/0
229 kthread+0x137/0x160
230 ret_from_fork+0x22/0x30
231
232 CPU: 4 PID: 124 Comm: kunit_try_catch Tain
233 Hardware name: QEMU Standard PC (i440FX +
234 ==========================================
235
236 DebugFS interface
237 ~~~~~~~~~~~~~~~~~
238
239 Some debugging information is exposed via debu
240
241 * The file ``/sys/kernel/debug/kfence/stats``
242
243 * The file ``/sys/kernel/debug/kfence/objects`
244 allocated via KFENCE, including those alread
245
246 Implementation Details
247 ----------------------
248
249 Guarded allocations are set up based on the sa
250 of the sample interval, the next allocation th
251 SLUB) returns a guarded allocation from the KF
252 sizes up to PAGE_SIZE are supported). At this
253 the next allocation is set up after the expira
254
255 When using ``CONFIG_KFENCE_STATIC_KEYS=y``, KF
256 through the main allocator's fast-path by rely
257 static keys infrastructure. The static branch
258 allocation to KFENCE. Depending on sample inte
259 system architecture, this may perform better t
260 Careful benchmarking is recommended.
261
262 KFENCE objects each reside on a dedicated page
263 page boundaries selected at random. The pages
264 object page are "guard pages", whose attribute
265 state, and cause page faults on any attempted
266 intercepted by KFENCE, which handles the fault
267 out-of-bounds access, and marking the page as
268 code can (wrongly) continue executing (set ``p
269
270 To detect out-of-bounds writes to memory withi
271 KFENCE also uses pattern-based redzones. For e
272 up for all non-object memory. For typical alig
273 required on the unguarded side of an object. B
274 cache's requested alignment, special alignment
275 on either side of an object, all of which are
276
277 The following figure illustrates the page layo
278
279 ---+-----------+-----------+-----------+--
280 | xxxxxxxxx | O : | xxxxxxxxx |
281 | xxxxxxxxx | B : | xxxxxxxxx |
282 | x GUARD x | J : RED- | x GUARD x | R
283 | xxxxxxxxx | E : ZONE | xxxxxxxxx |
284 | xxxxxxxxx | C : | xxxxxxxxx |
285 | xxxxxxxxx | T : | xxxxxxxxx |
286 ---+-----------+-----------+-----------+--
287
288 Upon deallocation of a KFENCE object, the obje
289 the object is marked as freed. Any further acc
290 and KFENCE reports a use-after-free access. Fr
291 tail of KFENCE's freelist, so that the least r
292 first, and the chances of detecting use-after-
293 is increased.
294
295 If pool utilization reaches 75% (default) or a
296 pool eventually being fully occupied by alloca
297 coverage of allocations, KFENCE limits current
298 same source from further filling up the pool.
299 based on its partial allocation stack trace. A
300 limits frequent long-lived allocations (e.g. p
301 filling up the pool permanently, which is the
302 becoming full and the sampled allocation rate
303 at which to start limiting currently covered a
304 the boot parameter ``kfence.skip_covered_thres
305
306 Interface
307 ---------
308
309 The following describes the functions which ar
310 page handling code to set up and deal with KFE
311
312 .. kernel-doc:: include/linux/kfence.h
313 :functions: is_kfence_address
314 kfence_shutdown_cache
315 kfence_alloc kfence_free __kfen
316 kfence_ksize kfence_object_star
317 kfence_handle_page_fault
318
319 Related Tools
320 -------------
321
322 In userspace, a similar approach is taken by `
323 <http://llvm.org/docs/GwpAsan.html>`_. GWP-ASa
324 a sampling strategy to detect memory unsafety
325 directly influenced by GWP-ASan, and can be se
326 similar but non-sampling approach, that also i
327 found in the userspace `Electric Fence Malloc
328 <https://linux.die.net/man/3/efence>`_.
329
330 In the kernel, several tools exist to debug me
331 particular KASAN can detect all bug classes th
332 is more precise, relying on compiler instrumen
333 performance cost.
334
335 It is worth highlighting that KASAN and KFENCE
336 different target environments. For instance, K
337 where test cases or reproducers exists: due to
338 error, it would require more effort using KFEN
339 that cannot afford to enable KASAN, however, w
340 discover bugs due to code paths not exercised
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.