From: Andrey Konovalov <andreyknvl@google.com>
To: Andrew Morton <akpm@linux-foundation.org>
Cc: linux-arm-kernel@lists.infradead.org,
Marco Elver <elver@google.com>,
Catalin Marinas <catalin.marinas@arm.com>,
Kevin Brodsky <kevin.brodsky@arm.com>,
Will Deacon <will.deacon@arm.com>,
Branislav Rankov <Branislav.Rankov@arm.com>,
kasan-dev@googlegroups.com, linux-kernel@vger.kernel.org,
linux-mm@kvack.org, Alexander Potapenko <glider@google.com>,
Evgenii Stepanov <eugenis@google.com>,
Andrey Konovalov <andreyknvl@google.com>,
Andrey Ryabinin <aryabinin@virtuozzo.com>,
Vincenzo Frascino <vincenzo.frascino@arm.com>,
Dmitry Vyukov <dvyukov@google.com>
Subject: [PATCH mm v11 41/42] kasan: add documentation for hardware tag-based mode
Date: Mon, 23 Nov 2020 21:08:05 +0100 [thread overview]
Message-ID: <20ed1d387685e89fc31be068f890f070ef9fd5d5.1606161801.git.andreyknvl@google.com> (raw)
In-Reply-To: <cover.1606161801.git.andreyknvl@google.com>
Add documentation for hardware tag-based KASAN mode and also add some
clarifications for software tag-based mode.
Signed-off-by: Andrey Konovalov <andreyknvl@google.com>
Signed-off-by: Vincenzo Frascino <vincenzo.frascino@arm.com>
Reviewed-by: Marco Elver <elver@google.com>
Reviewed-by: Alexander Potapenko <glider@google.com>
---
Change-Id: Ib46cb444cfdee44054628940a82f5139e10d0258
---
Documentation/dev-tools/kasan.rst | 80 +++++++++++++++++++++++--------
1 file changed, 59 insertions(+), 21 deletions(-)
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
index 2d55d788971c..ffbae8ce5748 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. Any supported Clang version is compatible, 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.
Currently generic KASAN is supported for the x86_64, arm, arm64, xtensa, s390
-and riscv architectures, and tag-based KASAN is supported only for arm64.
+and 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,36 @@ 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
+kmem_cache_alloc/kmalloc and page_alloc 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
+kmem_cache_alloc/kmalloc and page_alloc memory.
What memory accesses are sanitised by KASAN?
--------------------------------------------
--
2.29.2.454.gaff20da3a2-goog
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2020-11-23 20:27 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-23 20:07 [PATCH mm v11 00/42] kasan: add hardware tag-based mode for arm64 Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 01/42] kasan: drop unnecessary GPL text from comment headers Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 02/42] kasan: KASAN_VMALLOC depends on KASAN_GENERIC Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 03/42] kasan: group vmalloc code Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 04/42] kasan: shadow declarations only for software modes Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 05/42] kasan: rename (un)poison_shadow to (un)poison_range Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 06/42] kasan: rename KASAN_SHADOW_* to KASAN_GRANULE_* Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 07/42] kasan: only build init.c for software modes Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 08/42] kasan: split out shadow.c from common.c Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 09/42] kasan: define KASAN_MEMORY_PER_SHADOW_PAGE Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 10/42] kasan: rename report and tags files Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 11/42] kasan: don't duplicate config dependencies Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 12/42] kasan: hide invalid free check implementation Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 13/42] kasan: decode stack frame only with KASAN_STACK_ENABLE Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 14/42] kasan, arm64: only init shadow for software modes Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 15/42] kasan, arm64: only use kasan_depth " Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 16/42] kasan, arm64: move initialization message Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 17/42] kasan, arm64: rename kasan_init_tags and mark as __init Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 18/42] kasan: rename addr_has_shadow to addr_has_metadata Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 19/42] kasan: rename print_shadow_for_address to print_memory_metadata Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 20/42] kasan: rename SHADOW layout macros to META Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 21/42] kasan: separate metadata_fetch_row for each mode Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 22/42] kasan, arm64: don't allow SW_TAGS with ARM64_MTE Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 23/42] kasan: introduce CONFIG_KASAN_HW_TAGS Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 24/42] arm64: Enable armv8.5-a asm-arch option Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 25/42] arm64: mte: Add in-kernel MTE helpers Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 26/42] arm64: mte: Reset the page tag in page->flags Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 27/42] arm64: mte: Add in-kernel tag fault handler Andrey Konovalov
2020-12-03 10:26 ` Catalin Marinas
2020-12-03 10:39 ` Vincenzo Frascino
2020-11-23 20:07 ` [PATCH mm v11 28/42] arm64: kasan: Allow enabling in-kernel MTE Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 29/42] arm64: mte: Convert gcr_user into an exclude mask Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 30/42] arm64: mte: Switch GCR_EL1 in kernel entry and exit Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 31/42] kasan, mm: untag page address in free_reserved_area Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 32/42] arm64: kasan: Align allocations for HW_TAGS Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 33/42] arm64: kasan: Add arch layer for memory tagging helpers Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 34/42] kasan: define KASAN_GRANULE_SIZE for HW_TAGS Andrey Konovalov
2020-11-23 20:07 ` [PATCH mm v11 35/42] kasan, x86, s390: update undef CONFIG_KASAN Andrey Konovalov
2020-11-23 20:08 ` [PATCH mm v11 36/42] kasan, arm64: expand CONFIG_KASAN checks Andrey Konovalov
2020-11-23 20:08 ` [PATCH mm v11 37/42] kasan, arm64: implement HW_TAGS runtime Andrey Konovalov
2020-11-23 20:08 ` [PATCH mm v11 38/42] kasan, arm64: print report from tag fault handler Andrey Konovalov
2020-11-23 20:08 ` [PATCH mm v11 39/42] kasan, mm: reset tags when accessing metadata Andrey Konovalov
2020-11-23 20:08 ` [PATCH mm v11 40/42] kasan, arm64: enable CONFIG_KASAN_HW_TAGS Andrey Konovalov
2020-11-23 20:08 ` Andrey Konovalov [this message]
2020-11-23 20:08 ` [PATCH mm v11 42/42] kselftest/arm64: Check GCR_EL1 after context switch Andrey Konovalov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20ed1d387685e89fc31be068f890f070ef9fd5d5.1606161801.git.andreyknvl@google.com \
--to=andreyknvl@google.com \
--cc=Branislav.Rankov@arm.com \
--cc=akpm@linux-foundation.org \
--cc=aryabinin@virtuozzo.com \
--cc=catalin.marinas@arm.com \
--cc=dvyukov@google.com \
--cc=elver@google.com \
--cc=eugenis@google.com \
--cc=glider@google.com \
--cc=kasan-dev@googlegroups.com \
--cc=kevin.brodsky@arm.com \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=vincenzo.frascino@arm.com \
--cc=will.deacon@arm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).