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