Manual Pages  — KMSAN

KMSAN – Kernel Memory SANitizer

SYNOPSIS DESCRIPTION FUNCTIONS IMPLEMENTATION NOTES Shadow Maps Assembly Code Interrupts and Exceptions EXAMPLES SEE ALSO HISTORY BUGS

The GENERIC-KMSAN kernel configuration can be used to compile a KMSAN-enabled kernel using GENERIC as a base configuration. Alternately, to compile KMSAN into the kernel, place the following line in your kernel configuration file: options KMSAN

#include <sys/msan.h>

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

void
kmsan_orig(const void *addr, size_t size, int type, uintptr_t pc);

void
kmsan_check(const void *addr, size_t size, const char *descr);

void
kmsan_check_bio(const struct bio *, const char *descr);

void
kmsan_check_ccb(const union ccb *, const char *descr);

void
kmsan_check_mbuf(const struct mbuf *, const char *descr);

void
kmsan_check_uio(const struct uio *, const char *descr);

When KMSAN is configured, the compiler will only emit instrumentation for C code. Files containing assembly code are left un-instrumented. In some cases this is handled by the sanitizer runtime, which defines wrappers for subroutines implemented in assembly. These wrappers are referred to as interceptors and handle updating shadow state to reflect the operations performed by the original subroutines. In other cases, C code which calls assembly code or is called from assembly code may need to use kmsan_mark() to manually update shadow state. This is typically only necessary in machine-dependent code.

Inline assembly is instrumented by the compiler to update shadow state based on the output operands of the code, and thus does not usually require any special handling to avoid false positives.

In addition to the shadow maps, the sanitizer requires some thread-local storage (TLS) to track initialization and origin state for function parameters and return values. The sanitizer instrumentation will automatically fetch, update and verify this state. In particular, this storage block has a layout defined by the sanitizer ABI.

Most kernel code runs in a context where interrupts or exceptions may redirect the CPU to begin execution of unrelated code. To ensure that thread-local sanitizer state remains consistent, the runtime maintains a stack of TLS blocks for each thread. When machine-dependent interrupt and exception handlers begin execution, they push a new entry onto the stack before calling into any C code, and pop the stack before resuming execution of the interrupted code. These operations are performed by the kmsan_intr_enter() and kmsan_intr_leave() functions in the sanitizer runtime.

The following contrived example demonstrates some of the types of bugs that are automatically detected by KMSAN:

int
f(size_t osz)
{
        struct {
                uint32_t bar;
                uint16_t baz;
                /* A 2-byte hole is here. */
        } foo;
        char *buf;
        size_t sz;
        int error;

        /*
         * This will raise a report since "sz" is uninitialized
         * here.  If it is initialized, and "osz" was left uninitialized
         * by the caller, a report would also be raised.
         */
        if (sz < osz)
                return (1);

        buf = malloc(32, M_TEMP, M_WAITOK);

        /*
         * This will raise a report since "buf" has not been
         * initialized and contains whatever data is left over from the
         * previous use of that memory.
         */
        for (i = 0; i < 32; i++)
                if (buf[i] != ' ')
                        foo.bar++;
        foo.baz = 0;

        /*
         * This will raise a report since the pad bytes in "foo" have
         * not been initialized, e.g., by memset(), and this call will
         * thus copy uninitialized kernel stack memory into userspace.
         */
        copyout(&foo, uaddr, sizeof(foo));

        /*
         * This line itself will not raise a report, but may trigger
         * a report in the caller depending on how the return value is
         * used.
         */
        return (error);
}

KMSAN was ported from NetBSD and first appeared in FreeBSD 14.0 .

Accesses to kernel memory outside of the kernel map are ignored by the KMSAN runtime. In particular, memory accesses via the direct map are not validated. When memory is copied from outside the kernel map into the kernel map, that region of the kernel map is marked as initialized. When KMSAN is configured, kernel memory allocators are configured to use the kernel map, and filesystems are configured to always map data buffers into the kernel map, so usage of the direct map is minimized. However, some uses of the direct map remain. This is a conservative policy which aims to avoid false positives, but it will mask bug in some kernel subsystems.

On amd64, global variables and the physical page array vm_page_array are not sanitized. This is intentional, as it reduces memory usage by avoiding creating shadows of large regions of the kernel map. However, this can allow bugs to go undetected by KMSAN.

Some kernel memory allocators provide type-stable objects, and code which uses them frequently depends on object data being preserved across allocations. Such allocations cannot be sanitized by KMSAN. However, in some cases it may be possible to use kmsan_mark() to manually annotate fields which are known to contain invalid data upon allocation.