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