KASAN(9)               FreeBSD Kernel Developer's Manual              KASAN(9)

NAME
     kasan - kernel address sanitizer

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

           options KASAN

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

DESCRIPTION
     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
     implemented 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 conservative and will not detect all instances of these types of
     bugs.  Memory accesses through the kernel map are sanitized, but accesses
     via the direct map are not.  When kasan is configured, the kernel aims to
     minimize its use of the direct map.

IMPLEMENTATION NOTES
     kasan is implemented using compiler instrumentation and a kernel runtime.
     When a kernel is built with the KASAN option enabled, the compiler
     inserts 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
     sysctl/tunable.

     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
     addresses 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().
     Parameter 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 return 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 invalid.  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 instance, 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.

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

HISTORY
     kasan first appeared in FreeBSD 14.0.

BUGS
     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
     remain.  For example, on amd64, accesses to page table pages are not
     tracked.

     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
     sanitized.

FreeBSD 13.1-RELEASE-p6         April 13, 2021         FreeBSD 13.1-RELEASE-p6