On Fri, Sep 25, 2020 at 12:50AM +0200, Andrey Konovalov wrote: > Add documentation for hardware tag-based KASAN mode and also add some > clarifications for software tag-based mode. > > Signed-off-by: Andrey Konovalov <andreyknvl@xxxxxxxxxx> > Signed-off-by: Vincenzo Frascino <vincenzo.frascino@xxxxxxx> Reviewed-by: Marco Elver <elver@xxxxxxxxxx> > --- > Change-Id: Ib46cb444cfdee44054628940a82f5139e10d0258 > --- > Documentation/dev-tools/kasan.rst | 78 ++++++++++++++++++++++--------- > 1 file changed, 57 insertions(+), 21 deletions(-) > > diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst > index a3030fc6afe5..d2d47c82a7b9 100644 > --- a/Documentation/dev-tools/kasan.rst > +++ b/Documentation/dev-tools/kasan.rst > @@ -5,12 +5,14 @@ Overview > -------- > > KernelAddressSANitizer (KASAN) is a dynamic memory error detector designed to > -find out-of-bound and use-after-free bugs. KASAN has two modes: generic KASAN > -(similar to userspace ASan) and software tag-based KASAN (similar to userspace > -HWASan). > +find out-of-bound and use-after-free bugs. KASAN has three modes: > +1. generic KASAN (similar to userspace ASan), > +2. software tag-based KASAN (similar to userspace HWASan), > +3. hardware tag-based KASAN (based on hardware memory tagging). > > -KASAN uses compile-time instrumentation to insert validity checks before every > -memory access, and therefore requires a compiler version that supports that. > +Software KASAN modes (1 and 2) use compile-time instrumentation to insert > +validity checks before every memory access, and therefore require a compiler > +version that supports that. > > Generic KASAN is supported in both GCC and Clang. With GCC it requires version > 8.3.0 or later. With Clang it requires version 7.0.0 or later, but detection of > @@ -19,7 +21,7 @@ out-of-bounds accesses for global variables is only supported since Clang 11. > Tag-based KASAN is only supported in Clang and requires version 7.0.0 or later. > > Currently generic KASAN is supported for the x86_64, arm64, xtensa, s390 and > -riscv architectures, and tag-based KASAN is supported only for arm64. > +riscv architectures, and tag-based KASAN modes are supported only for arm64. > > Usage > ----- > @@ -28,14 +30,16 @@ To enable KASAN configure kernel with:: > > CONFIG_KASAN = y > > -and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN) and > -CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN). > +and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN), > +CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN), and > +CONFIG_KASAN_HW_TAGS (to enable hardware tag-based KASAN). > > -You also need to choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. > -Outline and inline are compiler instrumentation types. The former produces > -smaller binary while the latter is 1.1 - 2 times faster. > +For software modes, you also need to choose between CONFIG_KASAN_OUTLINE and > +CONFIG_KASAN_INLINE. Outline and inline are compiler instrumentation types. > +The former produces smaller binary while the latter is 1.1 - 2 times faster. > > -Both KASAN modes work with both SLUB and SLAB memory allocators. > +Both software KASAN modes work with both SLUB and SLAB memory allocators, > +hardware tag-based KASAN currently only support SLUB. > For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. > > To augment reports with last allocation and freeing stack of the physical page, > @@ -196,17 +200,24 @@ and the second to last. > Software tag-based KASAN > ~~~~~~~~~~~~~~~~~~~~~~~~ > > -Tag-based KASAN uses the Top Byte Ignore (TBI) feature of modern arm64 CPUs to > -store a pointer tag in the top byte of kernel pointers. Like generic KASAN it > -uses shadow memory to store memory tags associated with each 16-byte memory > +Software tag-based KASAN requires software memory tagging support in the form > +of HWASan-like compiler instrumentation (see HWASan documentation for details). > + > +Software tag-based KASAN is currently only implemented for arm64 architecture. > + > +Software tag-based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs > +to store a pointer tag in the top byte of kernel pointers. Like generic KASAN > +it uses shadow memory to store memory tags associated with each 16-byte memory > cell (therefore it dedicates 1/16th of the kernel memory for shadow memory). > > -On each memory allocation tag-based KASAN generates a random tag, tags the > -allocated memory with this tag, and embeds this tag into the returned pointer. > +On each memory allocation software tag-based KASAN generates a random tag, tags > +the allocated memory with this tag, and embeds this tag into the returned > +pointer. > + > Software tag-based KASAN uses compile-time instrumentation to insert checks > before each memory access. These checks make sure that tag of the memory that > is being accessed is equal to tag of the pointer that is used to access this > -memory. In case of a tag mismatch tag-based KASAN prints a bug report. > +memory. In case of a tag mismatch software tag-based KASAN prints a bug report. > > Software tag-based KASAN also has two instrumentation modes (outline, that > emits callbacks to check memory accesses; and inline, that performs the shadow > @@ -215,9 +226,34 @@ simply printed from the function that performs the access check. With inline > instrumentation a brk instruction is emitted by the compiler, and a dedicated > brk handler is used to print bug reports. > > -A potential expansion of this mode is a hardware tag-based mode, which would > -use hardware memory tagging support instead of compiler instrumentation and > -manual shadow memory manipulation. > +Software tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through > +pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently > +reserved to tag freed memory regions. > + > +Software tag-based KASAN currently only supports tagging of slab memory. > + > +Hardware tag-based KASAN > +~~~~~~~~~~~~~~~~~~~~~~~~ > + > +Hardware tag-based KASAN is similar to the software mode in concept, but uses > +hardware memory tagging support instead of compiler instrumentation and > +shadow memory. > + > +Hardware tag-based KASAN is currently only implemented for arm64 architecture > +and based on both arm64 Memory Tagging Extension (MTE) introduced in ARMv8.5 > +Instruction Set Architecture, and Top Byte Ignore (TBI). > + > +Special arm64 instructions are used to assign memory tags for each allocation. > +Same tags are assigned to pointers to those allocations. On every memory > +access, hardware makes sure that tag of the memory that is being accessed is > +equal to tag of the pointer that is used to access this memory. In case of a > +tag mismatch a fault is generated and a report is printed. > + > +Hardware tag-based KASAN uses 0xFF as a match-all pointer tag (accesses through > +pointers with 0xFF pointer tag aren't checked). The value 0xFE is currently > +reserved to tag freed memory regions. > + > +Hardware tag-based KASAN currently only supports tagging of slab memory. > > What memory accesses are sanitised by KASAN? > -------------------------------------------- > -- > 2.28.0.681.g6f77f65b4e-goog >
