Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
KASAN(9)	       FreeBSD Kernel Developer's Manual	      KASAN(9)

     kasan -- kernel address sanitizer

     To	compile	KASAN into the kernel, place the following line	in your	kernel
     configuration file:

	   options KASAN

     kasan_mark(const void *addr, size_t size, size_t redzsize,	uint8_t	code);

     kasan is a	subsystem which	leverages compiler instrumentation to detect
     invalid memory accesses in	the kernel.  Currently it is implemented only
     on	the amd64 platform.

     When kasan	is compiled into the kernel, the compiler is configured	to
     emit function calls upon every memory access.  The	functions are imple-
     mented by kasan and permit	run-time detection of several types of bugs
     including use-after-frees,	double frees and frees of invalid pointers,
     and out-of-bounds accesses.  These	protections apply to memory allocated
     by	uma(9),	malloc(9) and related functions, and kmem_malloc() and related
     functions,	as well	as global variables and	kernel stacks.	kasan is con-
     servative and will	not detect all instances of these types	of bugs.  Mem-
     ory accesses through the kernel map are sanitized,	but accesses via the
     direct map	are not.  When kasan is	configured, the	kernel aims to mini-
     mize its use of the direct	map.

     kasan is implemented using	compiler instrumentation and a kernel runtime.
     When a kernel is built with the KASAN option enabled, the compiler	in-
     serts function calls before most memory accesses in the generated code.
     The runtime implements the	corresponding functions, which decide whether
     a given access is valid.  If not, the runtime prints a warning or panics
     the kernel, depending on the value	of the debug.kasan.panic_on_violation

     The kasan runtime works by	maintaining a shadow map for the kernel	map.
     There exists a linear mapping between addresses in	the kernel map and ad-
     dresses in	the shadow map.	 The shadow map	is used	to store information
     about the current state of	allocations from the kernel map.  For example,
     when a buffer is returned by malloc(9), the corresponding region of the
     shadow map	is marked to indicate that the buffer is valid.	 When it is
     freed, the	shadow map is updated to mark the buffer as invalid.  Accesses
     to	the buffer are intercepted by the kasan	runtime	and validated using
     the contents of the shadow	map.

     Upon booting, all kernel memory is	marked as valid.  Kernel allocators
     must mark cached but free buffers as invalid, and must mark them valid
     before freeing the	kernel virtual address range.  This slightly reduces
     the effectiveness of kasan	but simplifies its maintenance and integration
     into the kernel.

     Updates to	the shadow map are performed by	calling	kasan_mark().  Parame-
     ter addr is the address of	the buffer whose shadow	is to be updated, size
     is	the usable size	of the buffer, and redzsize is the full	size of	the
     buffer allocated from lower layers	of the system.	redzsize must be
     greater than or equal to size.  In	some cases kernel allocators will re-
     turn a buffer larger than that requested by the consumer; the unused
     space at the end is referred to as	a red zone and is always marked	as in-
     valid.  code allows the caller to specify an identifier used when marking
     a buffer as invalid.  The identifier is included in any reports generated
     by	kasan and helps	identify the source of the invalid access.  For	in-
     stance, when an item is freed to a	uma(9) zone, the item is marked	with
     KASAN_UMA_FREED.  See <sys/asan.h>	for the	available identifiers.	If the
     entire buffer is to be marked valid, i.e.,	size and redzsize are equal,
     code should be 0.

     malloc(9),	memguard(9), redzone(9), uma(9)

     kasan first appeared in FreeBSD 14.0.

     Accesses to kernel	memory outside of the kernel map are ignored by	the
     kasan runtime.  When kasan	is configured, the kernel memory allocators
     are configured to use the kernel map, but some uses of the	direct map re-
     main.  For	example, on amd64, accesses to page table pages	are not

     Some kernel memory	allocators explicitly permit accesses after an object
     has been freed.  These cannot be sanitized	by kasan.  For example,	memory
     from all uma(9) zones initialized with the	UMA_ZONE_NOFREE	flag are not

FreeBSD	13.0			April 13, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help