1.\"- 2.\" Copyright (c) 2021 The FreeBSD Foundation 3.\" 4.\" This documentation was written by Mark Johnston under sponsorship from 5.\" the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd October 13, 2023 29.Dt KASAN 9 30.Os 31.Sh NAME 32.Nm KASAN 33.Nd Kernel Address SANitizer 34.Sh SYNOPSIS 35The 36.Pa GENERIC-KASAN 37kernel configuration can be used to compile a KASAN-enabled kernel using 38.Pa GENERIC 39as a base configuration. 40Alternately, to compile KASAN into the kernel, place the following line in your 41kernel configuration file: 42.Bd -ragged -offset indent 43.Cd "options KASAN" 44.Ed 45.Pp 46.In sys/asan.h 47.Ft void 48.Fn kasan_mark "const void *addr" "size_t size" "size_t redzsize" "uint8_t code" 49.Sh DESCRIPTION 50.Nm 51is a subsystem which leverages compiler instrumentation to detect invalid 52memory accesses in the kernel. 53Currently it is implemented on the amd64 and arm64 platforms. 54.Pp 55When 56.Nm 57is compiled into the kernel, the compiler is configured to emit function 58calls upon every memory access. 59The functions are implemented by 60.Nm 61and permit run-time detection of several types of bugs including 62use-after-frees, double frees and frees of invalid pointers, and out-of-bounds 63accesses. 64These protections apply to memory allocated by 65.Xr uma 9 , 66.Xr malloc 9 67and related functions, and 68.Fn kmem_malloc 69and related functions, 70as well as global variables and kernel stacks. 71.Nm 72is conservative and will not detect all instances of these types of bugs. 73Memory accesses through the kernel map are sanitized, but accesses via the 74direct map are not. 75When 76.Nm 77is configured, the kernel aims to minimize its use of the direct map. 78.Sh IMPLEMENTATION NOTES 79.Nm 80is implemented using compiler instrumentation and a kernel runtime. 81When a 82kernel is built with the KASAN option enabled, the compiler inserts function calls 83before most memory accesses in the generated code. 84The runtime implements the corresponding functions, which decide whether a 85given access is valid. 86If not, the runtime prints a warning or panics the kernel, depending on the 87value of the 88.Sy debug.kasan.panic_on_violation 89sysctl/tunable. 90.Pp 91The 92.Nm 93runtime in a KASAN-configured kernel can be disabled by 94setting the loader tunable 95.Sy debug.kasan.disable=1 . 96.Pp 97The 98.Nm 99runtime works by maintaining a shadow map for the kernel map. 100There exists a linear mapping between addresses in the kernel map and addresses 101in the shadow map. 102The shadow map is used to store information about the current state of 103allocations from the kernel map. 104For example, when a buffer is returned by 105.Xr malloc 9 , 106the corresponding region of the shadow map is marked to indicate that the 107buffer is valid. 108When it is freed, the shadow map is updated to mark the buffer as invalid. 109Accesses to the buffer are intercepted by the 110.Nm 111runtime and validated using the contents of the shadow map. 112.Pp 113Upon booting, all kernel memory is marked as valid. 114Kernel allocators must mark cached but free buffers as invalid, and must mark 115them valid before freeing the kernel virtual address range. 116This slightly reduces the effectiveness of 117.Nm 118but simplifies its maintenance and integration into the kernel. 119.Pp 120Updates to the shadow map are performed by calling 121.Fn kasan_mark . 122Parameter 123.Fa addr 124is the address of the buffer whose shadow is to be updated, 125.Fa size 126is the usable size of the buffer, and 127.Fa redzsize 128is the full size of the buffer allocated from lower layers of the system. 129.Fa redzsize 130must be greater than or equal to 131.Fa size . 132In some cases kernel allocators will return a buffer larger than that requested 133by the consumer; the unused space at the end is referred to as a red zone and is 134always marked as invalid. 135.Fa code 136allows the caller to specify an identifier used when marking a buffer as invalid. 137The identifier is included in any reports generated by 138.Nm 139and helps identify the source of the invalid access. 140For instance, when an item is freed to a 141.Xr uma 9 142zone, the item is marked with 143.Dv KASAN_UMA_FREED . 144See 145.In sys/asan.h 146for the available identifiers. 147If the entire buffer is to be marked valid, i.e., 148.Fa size 149and 150.Fa redzsize 151are equal, 152.Fa code 153should be 0. 154.Sh SEE ALSO 155.Xr build 7 , 156.Xr KMSAN 9 , 157.Xr malloc 9 , 158.Xr memguard 9 , 159.Xr redzone 9 , 160.Xr uma 9 161.Sh HISTORY 162.Nm 163was ported from 164.Nx 165and first appeared in 166.Fx 13.1 . 167.Sh BUGS 168Accesses to kernel memory outside of the kernel map are ignored by the 169.Nm 170runtime. 171When 172.Nm 173is configured, the kernel memory allocators are configured to use the kernel 174map, but some uses of the direct map remain. 175For example, on amd64 and arm64, accesses to page table pages are not tracked. 176.Pp 177Some kernel memory allocators explicitly permit accesses after an object has 178been freed. 179These cannot be sanitized by 180.Nm . 181For example, memory from all 182.Xr uma 9 183zones initialized with the 184.Dv UMA_ZONE_NOFREE 185flag are not sanitized. 186