kfence.rst 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298
  1. .. SPDX-License-Identifier: GPL-2.0
  2. .. Copyright (C) 2020, Google LLC.
  3. Kernel Electric-Fence (KFENCE)
  4. ==============================
  5. Kernel Electric-Fence (KFENCE) is a low-overhead sampling-based memory safety
  6. error detector. KFENCE detects heap out-of-bounds access, use-after-free, and
  7. invalid-free errors.
  8. KFENCE is designed to be enabled in production kernels, and has near zero
  9. performance overhead. Compared to KASAN, KFENCE trades performance for
  10. precision. The main motivation behind KFENCE's design, is that with enough
  11. total uptime KFENCE will detect bugs in code paths not typically exercised by
  12. non-production test workloads. One way to quickly achieve a large enough total
  13. uptime is when the tool is deployed across a large fleet of machines.
  14. Usage
  15. -----
  16. To enable KFENCE, configure the kernel with::
  17. CONFIG_KFENCE=y
  18. To build a kernel with KFENCE support, but disabled by default (to enable, set
  19. ``kfence.sample_interval`` to non-zero value), configure the kernel with::
  20. CONFIG_KFENCE=y
  21. CONFIG_KFENCE_SAMPLE_INTERVAL=0
  22. KFENCE provides several other configuration options to customize behaviour (see
  23. the respective help text in ``lib/Kconfig.kfence`` for more info).
  24. Tuning performance
  25. ~~~~~~~~~~~~~~~~~~
  26. The most important parameter is KFENCE's sample interval, which can be set via
  27. the kernel boot parameter ``kfence.sample_interval`` in milliseconds. The
  28. sample interval determines the frequency with which heap allocations will be
  29. guarded by KFENCE. The default is configurable via the Kconfig option
  30. ``CONFIG_KFENCE_SAMPLE_INTERVAL``. Setting ``kfence.sample_interval=0``
  31. disables KFENCE.
  32. The KFENCE memory pool is of fixed size, and if the pool is exhausted, no
  33. further KFENCE allocations occur. With ``CONFIG_KFENCE_NUM_OBJECTS`` (default
  34. 255), the number of available guarded objects can be controlled. Each object
  35. requires 2 pages, one for the object itself and the other one used as a guard
  36. page; object pages are interleaved with guard pages, and every object page is
  37. therefore surrounded by two guard pages.
  38. The total memory dedicated to the KFENCE memory pool can be computed as::
  39. ( #objects + 1 ) * 2 * PAGE_SIZE
  40. Using the default config, and assuming a page size of 4 KiB, results in
  41. dedicating 2 MiB to the KFENCE memory pool.
  42. Note: On architectures that support huge pages, KFENCE will ensure that the
  43. pool is using pages of size ``PAGE_SIZE``. This will result in additional page
  44. tables being allocated.
  45. Error reports
  46. ~~~~~~~~~~~~~
  47. A typical out-of-bounds access looks like this::
  48. ==================================================================
  49. BUG: KFENCE: out-of-bounds read in test_out_of_bounds_read+0xa3/0x22b
  50. Out-of-bounds read at 0xffffffffb672efff (1B left of kfence-#17):
  51. test_out_of_bounds_read+0xa3/0x22b
  52. kunit_try_run_case+0x51/0x85
  53. kunit_generic_run_threadfn_adapter+0x16/0x30
  54. kthread+0x137/0x160
  55. ret_from_fork+0x22/0x30
  56. kfence-#17 [0xffffffffb672f000-0xffffffffb672f01f, size=32, cache=kmalloc-32] allocated by task 507:
  57. test_alloc+0xf3/0x25b
  58. test_out_of_bounds_read+0x98/0x22b
  59. kunit_try_run_case+0x51/0x85
  60. kunit_generic_run_threadfn_adapter+0x16/0x30
  61. kthread+0x137/0x160
  62. ret_from_fork+0x22/0x30
  63. CPU: 4 PID: 107 Comm: kunit_try_catch Not tainted 5.8.0-rc6+ #7
  64. Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
  65. ==================================================================
  66. The header of the report provides a short summary of the function involved in
  67. the access. It is followed by more detailed information about the access and
  68. its origin. Note that, real kernel addresses are only shown when using the
  69. kernel command line option ``no_hash_pointers``.
  70. Use-after-free accesses are reported as::
  71. ==================================================================
  72. BUG: KFENCE: use-after-free read in test_use_after_free_read+0xb3/0x143
  73. Use-after-free read at 0xffffffffb673dfe0 (in kfence-#24):
  74. test_use_after_free_read+0xb3/0x143
  75. kunit_try_run_case+0x51/0x85
  76. kunit_generic_run_threadfn_adapter+0x16/0x30
  77. kthread+0x137/0x160
  78. ret_from_fork+0x22/0x30
  79. kfence-#24 [0xffffffffb673dfe0-0xffffffffb673dfff, size=32, cache=kmalloc-32] allocated by task 507:
  80. test_alloc+0xf3/0x25b
  81. test_use_after_free_read+0x76/0x143
  82. kunit_try_run_case+0x51/0x85
  83. kunit_generic_run_threadfn_adapter+0x16/0x30
  84. kthread+0x137/0x160
  85. ret_from_fork+0x22/0x30
  86. freed by task 507:
  87. test_use_after_free_read+0xa8/0x143
  88. kunit_try_run_case+0x51/0x85
  89. kunit_generic_run_threadfn_adapter+0x16/0x30
  90. kthread+0x137/0x160
  91. ret_from_fork+0x22/0x30
  92. CPU: 4 PID: 109 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7
  93. Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
  94. ==================================================================
  95. KFENCE also reports on invalid frees, such as double-frees::
  96. ==================================================================
  97. BUG: KFENCE: invalid free in test_double_free+0xdc/0x171
  98. Invalid free of 0xffffffffb6741000:
  99. test_double_free+0xdc/0x171
  100. kunit_try_run_case+0x51/0x85
  101. kunit_generic_run_threadfn_adapter+0x16/0x30
  102. kthread+0x137/0x160
  103. ret_from_fork+0x22/0x30
  104. kfence-#26 [0xffffffffb6741000-0xffffffffb674101f, size=32, cache=kmalloc-32] allocated by task 507:
  105. test_alloc+0xf3/0x25b
  106. test_double_free+0x76/0x171
  107. kunit_try_run_case+0x51/0x85
  108. kunit_generic_run_threadfn_adapter+0x16/0x30
  109. kthread+0x137/0x160
  110. ret_from_fork+0x22/0x30
  111. freed by task 507:
  112. test_double_free+0xa8/0x171
  113. kunit_try_run_case+0x51/0x85
  114. kunit_generic_run_threadfn_adapter+0x16/0x30
  115. kthread+0x137/0x160
  116. ret_from_fork+0x22/0x30
  117. CPU: 4 PID: 111 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7
  118. Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
  119. ==================================================================
  120. KFENCE also uses pattern-based redzones on the other side of an object's guard
  121. page, to detect out-of-bounds writes on the unprotected side of the object.
  122. These are reported on frees::
  123. ==================================================================
  124. BUG: KFENCE: memory corruption in test_kmalloc_aligned_oob_write+0xef/0x184
  125. Corrupted memory at 0xffffffffb6797ff9 [ 0xac . . . . . . ] (in kfence-#69):
  126. test_kmalloc_aligned_oob_write+0xef/0x184
  127. kunit_try_run_case+0x51/0x85
  128. kunit_generic_run_threadfn_adapter+0x16/0x30
  129. kthread+0x137/0x160
  130. ret_from_fork+0x22/0x30
  131. kfence-#69 [0xffffffffb6797fb0-0xffffffffb6797ff8, size=73, cache=kmalloc-96] allocated by task 507:
  132. test_alloc+0xf3/0x25b
  133. test_kmalloc_aligned_oob_write+0x57/0x184
  134. kunit_try_run_case+0x51/0x85
  135. kunit_generic_run_threadfn_adapter+0x16/0x30
  136. kthread+0x137/0x160
  137. ret_from_fork+0x22/0x30
  138. CPU: 4 PID: 120 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7
  139. Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
  140. ==================================================================
  141. For such errors, the address where the corruption occurred as well as the
  142. invalidly written bytes (offset from the address) are shown; in this
  143. representation, '.' denote untouched bytes. In the example above ``0xac`` is
  144. the value written to the invalid address at offset 0, and the remaining '.'
  145. denote that no following bytes have been touched. Note that, real values are
  146. only shown if the kernel was booted with ``no_hash_pointers``; to avoid
  147. information disclosure otherwise, '!' is used instead to denote invalidly
  148. written bytes.
  149. And finally, KFENCE may also report on invalid accesses to any protected page
  150. where it was not possible to determine an associated object, e.g. if adjacent
  151. object pages had not yet been allocated::
  152. ==================================================================
  153. BUG: KFENCE: invalid read in test_invalid_access+0x26/0xe0
  154. Invalid read at 0xffffffffb670b00a:
  155. test_invalid_access+0x26/0xe0
  156. kunit_try_run_case+0x51/0x85
  157. kunit_generic_run_threadfn_adapter+0x16/0x30
  158. kthread+0x137/0x160
  159. ret_from_fork+0x22/0x30
  160. CPU: 4 PID: 124 Comm: kunit_try_catch Tainted: G W 5.8.0-rc6+ #7
  161. Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.13.0-1 04/01/2014
  162. ==================================================================
  163. DebugFS interface
  164. ~~~~~~~~~~~~~~~~~
  165. Some debugging information is exposed via debugfs:
  166. * The file ``/sys/kernel/debug/kfence/stats`` provides runtime statistics.
  167. * The file ``/sys/kernel/debug/kfence/objects`` provides a list of objects
  168. allocated via KFENCE, including those already freed but protected.
  169. Implementation Details
  170. ----------------------
  171. Guarded allocations are set up based on the sample interval. After expiration
  172. of the sample interval, the next allocation through the main allocator (SLAB or
  173. SLUB) returns a guarded allocation from the KFENCE object pool (allocation
  174. sizes up to PAGE_SIZE are supported). At this point, the timer is reset, and
  175. the next allocation is set up after the expiration of the interval. To "gate" a
  176. KFENCE allocation through the main allocator's fast-path without overhead,
  177. KFENCE relies on static branches via the static keys infrastructure. The static
  178. branch is toggled to redirect the allocation to KFENCE.
  179. KFENCE objects each reside on a dedicated page, at either the left or right
  180. page boundaries selected at random. The pages to the left and right of the
  181. object page are "guard pages", whose attributes are changed to a protected
  182. state, and cause page faults on any attempted access. Such page faults are then
  183. intercepted by KFENCE, which handles the fault gracefully by reporting an
  184. out-of-bounds access, and marking the page as accessible so that the faulting
  185. code can (wrongly) continue executing (set ``panic_on_warn`` to panic instead).
  186. To detect out-of-bounds writes to memory within the object's page itself,
  187. KFENCE also uses pattern-based redzones. For each object page, a redzone is set
  188. up for all non-object memory. For typical alignments, the redzone is only
  189. required on the unguarded side of an object. Because KFENCE must honor the
  190. cache's requested alignment, special alignments may result in unprotected gaps
  191. on either side of an object, all of which are redzoned.
  192. The following figure illustrates the page layout::
  193. ---+-----------+-----------+-----------+-----------+-----------+---
  194. | xxxxxxxxx | O : | xxxxxxxxx | : O | xxxxxxxxx |
  195. | xxxxxxxxx | B : | xxxxxxxxx | : B | xxxxxxxxx |
  196. | x GUARD x | J : RED- | x GUARD x | RED- : J | x GUARD x |
  197. | xxxxxxxxx | E : ZONE | xxxxxxxxx | ZONE : E | xxxxxxxxx |
  198. | xxxxxxxxx | C : | xxxxxxxxx | : C | xxxxxxxxx |
  199. | xxxxxxxxx | T : | xxxxxxxxx | : T | xxxxxxxxx |
  200. ---+-----------+-----------+-----------+-----------+-----------+---
  201. Upon deallocation of a KFENCE object, the object's page is again protected and
  202. the object is marked as freed. Any further access to the object causes a fault
  203. and KFENCE reports a use-after-free access. Freed objects are inserted at the
  204. tail of KFENCE's freelist, so that the least recently freed objects are reused
  205. first, and the chances of detecting use-after-frees of recently freed objects
  206. is increased.
  207. Interface
  208. ---------
  209. The following describes the functions which are used by allocators as well as
  210. page handling code to set up and deal with KFENCE allocations.
  211. .. kernel-doc:: include/linux/kfence.h
  212. :functions: is_kfence_address
  213. kfence_shutdown_cache
  214. kfence_alloc kfence_free __kfence_free
  215. kfence_ksize kfence_object_start
  216. kfence_handle_page_fault
  217. Related Tools
  218. -------------
  219. In userspace, a similar approach is taken by `GWP-ASan
  220. <http://llvm.org/docs/GwpAsan.html>`_. GWP-ASan also relies on guard pages and
  221. a sampling strategy to detect memory unsafety bugs at scale. KFENCE's design is
  222. directly influenced by GWP-ASan, and can be seen as its kernel sibling. Another
  223. similar but non-sampling approach, that also inspired the name "KFENCE", can be
  224. found in the userspace `Electric Fence Malloc Debugger
  225. <https://linux.die.net/man/3/efence>`_.
  226. In the kernel, several tools exist to debug memory access errors, and in
  227. particular KASAN can detect all bug classes that KFENCE can detect. While KASAN
  228. is more precise, relying on compiler instrumentation, this comes at a
  229. performance cost.
  230. It is worth highlighting that KASAN and KFENCE are complementary, with
  231. different target environments. For instance, KASAN is the better debugging-aid,
  232. where test cases or reproducers exists: due to the lower chance to detect the
  233. error, it would require more effort using KFENCE to debug. Deployments at scale
  234. that cannot afford to enable KASAN, however, would benefit from using KFENCE to
  235. discover bugs due to code paths not exercised by test cases or fuzzers.