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.\" $FreeBSD$ 29.\" 30.Dd April 29, 2021 31.Dt KASAN 9 32.Os 33.Sh NAME 34.Nm KASAN 35.Nd Kernel Address SANitizer 36.Sh SYNOPSIS 37The 38.Pa GENERIC-KASAN 39kernel configuration can be used to compile a KASAN-enabled kernel using 40.Pa GENERIC 41as a base configuration. 42Alternately, to compile KASAN into the kernel, place the following line in your 43kernel configuration file: 44.Bd -ragged -offset indent 45.Cd "options KASAN" 46.Ed 47.Pp 48.In sys/asan.h 49.Ft void 50.Fn kasan_mark "const void *addr" "size_t size" "size_t redzsize" "uint8_t code" 51.Sh DESCRIPTION 52.Nm 53is a subsystem which leverages compiler instrumentation to detect invalid 54memory accesses in the kernel. 55Currently it is implemented only on the amd64 platform. 56.Pp 57When 58.Nm 59is compiled into the kernel, the compiler is configured to emit function 60calls upon every memory access. 61The functions are implemented by 62.Nm 63and permit run-time detection of several types of bugs including 64use-after-frees, double frees and frees of invalid pointers, and out-of-bounds 65accesses. 66These protections apply to memory allocated by 67.Xr uma 9 , 68.Xr malloc 9 69and related functions, and 70.Fn kmem_malloc 71and related functions, 72as well as global variables and kernel stacks. 73.Nm 74is conservative and will not detect all instances of these types of bugs. 75Memory accesses through the kernel map are sanitized, but accesses via the 76direct map are not. 77When 78.Nm 79is configured, the kernel aims to minimize its use of the direct map. 80.Sh IMPLEMENTATION NOTES 81.Nm 82is implemented using compiler instrumentation and a kernel runtime. 83When a 84kernel is built with the KASAN option enabled, the compiler inserts function calls 85before most memory accesses in the generated code. 86The runtime implements the corresponding functions, which decide whether a 87given access is valid. 88If not, the runtime prints a warning or panics the kernel, depending on the 89value of the 90.Sy debug.kasan.panic_on_violation 91sysctl/tunable. 92.Pp 93The 94.Nm 95runtime works by maintaining a shadow map for the kernel map. 96There exists a linear mapping between addresses in the kernel map and addresses 97in the shadow map. 98The shadow map is used to store information about the current state of 99allocations from the kernel map. 100For example, when a buffer is returned by 101.Xr malloc 9 , 102the corresponding region of the shadow map is marked to indicate that the 103buffer is valid. 104When it is freed, the shadow map is updated to mark the buffer as invalid. 105Accesses to the buffer are intercepted by the 106.Nm 107runtime and validated using the contents of the shadow map. 108.Pp 109Upon booting, all kernel memory is marked as valid. 110Kernel allocators must mark cached but free buffers as invalid, and must mark 111them valid before freeing the kernel virtual address range. 112This slightly reduces the effectiveness of 113.Nm 114but simplifies its maintenance and integration into the kernel. 115.Pp 116Updates to the shadow map are performed by calling 117.Fn kasan_mark . 118Parameter 119.Fa addr 120is the address of the buffer whose shadow is to be updated, 121.Fa size 122is the usable size of the buffer, and 123.Fa redzsize 124is the full size of the buffer allocated from lower layers of the system. 125.Fa redzsize 126must be greater than or equal to 127.Fa size . 128In some cases kernel allocators will return a buffer larger than that requested 129by the consumer; the unused space at the end is referred to as a red zone and is 130always marked as invalid. 131.Fa code 132allows the caller to specify an identifier used when marking a buffer as invalid. 133The identifier is included in any reports generated by 134.Nm 135and helps identify the source of the invalid access. 136For instance, when an item is freed to a 137.Xr uma 9 138zone, the item is marked with 139.Dv KASAN_UMA_FREED . 140See 141.In sys/asan.h 142for the available identifiers. 143If the entire buffer is to be marked valid, i.e., 144.Fa size 145and 146.Fa redzsize 147are equal, 148.Fa code 149should be 0. 150.Sh SEE ALSO 151.Xr build 7 , 152.Xr KMSAN 9 , 153.Xr malloc 9 , 154.Xr memguard 9 , 155.Xr redzone 9 , 156.Xr uma 9 157.Sh HISTORY 158.Nm 159was ported from 160.Nx 161and first appeared in 162.Fx 14.0 . 163.Sh BUGS 164Accesses to kernel memory outside of the kernel map are ignored by the 165.Nm 166runtime. 167When 168.Nm 169is configured, the kernel memory allocators are configured to use the kernel 170map, but some uses of the direct map remain. 171For example, on amd64, accesses to page table pages are not tracked. 172.Pp 173Some kernel memory allocators explicitly permit accesses after an object has 174been freed. 175These cannot be sanitized by 176.Nm . 177For example, memory from all 178.Xr uma 9 179zones initialized with the 180.Dv UMA_ZONE_NOFREE 181flag are not sanitized. 182