llvm/docs/MemTagSanitizer.rst

   1 ================
   2 MemTagSanitizer
   3 ================
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 **Note:** this page describes a tool under development. Part of this
  12 functionality is planned but not implemented.  Hardware capable of
  13 running MemTagSanitizer does not exist as of Oct 2019.
  14
  15 MemTagSanitizer is a fast memory error detector and **a code hardening
  16 tool** based on the Armv8.5-A `Memory Tagging Extension`_. It
  17 detects a similar class of errors as `AddressSanitizer`_ or `HardwareAssistedAddressSanitizer`_, but with
  18 **much** lower overhead.
  19
  20 MemTagSanitizer overhead is expected to be in low single digits, both
  21 CPU and memory. There are plans for a debug mode with slightly higher
  22 memory overhead and better diagnostics. The primary use case of
  23 MemTagSanitizer is code hardening in production binaries, where it is
  24 expected to be a strong mitigation for both stack and heap-based
  25 memory bugs.
  26
  27
  28 Usage
  29 =====
  30
  31 Compile and link your program with the ``-fsanitize=memtag`` flag. This
  32 will only work when targeting AArch64 Android with the memory tagging extension.
  33 One possible way to achieve that is to add ``--target=aarch64-linux-android -march=armv8+memtag``
  34 to your compilation flags.
  35
  36 Note that doing this will override existing flags of the same type. Assuming that
  37 you are already targeting AArch64 Android, an alternative is to add
  38 ``-Xclang -target-feature -Xclang +mte`` to your compilation flags. This
  39 adds the memory tagging feature, without changing anything else.
  40
  41 Implementation
  42 ==============
  43
  44 See `HardwareAssistedAddressSanitizer`_ for a general overview of a
  45 tag-based approach to memory safety.  MemTagSanitizer follows a
  46 similar implementation strategy, but with the tag storage (shadow)
  47 provided by the hardware.
  48
  49 A quick overview of MTE hardware capabilities:
  50
  51 * Every 16 aligned bytes of memory can be assigned a 4-bit Allocation Tag.
  52 * Every pointer can have a 4-bit Address Tag that is in its most significant byte.
  53 * Most memory access instructions generate an exception if Address Tag != Allocation Tag.
  54 * Special instructions are provided for fast tag manipulation.
  55
  56 Stack instrumentation
  57 =====================
  58
  59 Stack-based memory errors are detected by updating Allocation Tag for
  60 each local variable to a random value at the start of its lifetime,
  61 and resetting it to the stack pointer Address Tag at the end of
  62 it. Unallocated stack space is expected to match the Address Tag of
  63 SP; this allows to skip tagging of any variable when memory safety can
  64 be statically proven.
  65
  66 Allocating a truly random tag for each stack variable in a large
  67 function may incur significant code size overhead, because it means
  68 that each variable's address is an independent, non-rematerializable
  69 value; thus a function with N local variables will have extra N live
  70 values to keep through most of its life time.
  71
  72 For this reason MemTagSanitizer generates at most one random tag per
  73 function, called a "base tag". Other stack variables, if there are
  74 any, are assigned tags at a fixed offset from the base.
  75
  76 Please refer to `this document
  77 <https://github.com/google/sanitizers/wiki/Stack-instrumentation-with-ARM-Memory-Tagging-Extension-(MTE)>`_
  78 for more details about stack instrumentation.
  79
  80 Heap tagging
  81 ============
  82
  83 **Note:** this part is not implemented as of Oct 2019.
  84
  85 MemTagSanitizer will use :doc:`ScudoHardenedAllocator`
  86 with additional code to update memory tags when
  87
  88 * New memory is obtained from the system.
  89 * An allocation is freed.
  90
  91 There is no need to change Allocation Tags for the bulk of the
  92 allocated memory in malloc(), as long as a pointer with the matching
  93 Address Tag is returned.
  94
  95 More information
  96 ================
  97
  98 * `LLVM Developer Meeting 2018 talk on Memory Tagging <https://llvm.org/devmtg/2018-10/slides/Serebryany-Stepanov-Tsyrklevich-Memory-Tagging-Slides-LLVM-2018.pdf>`_
  99 * `Memory Tagging Whitepaper <https://arxiv.org/pdf/1802.09517.pdf>`_
 100
 101 .. _Memory Tagging Extension: https://community.arm.com/developer/ip-products/processors/b/processors-ip-blog/posts/arm-a-profile-architecture-2018-developments-armv85a
 102 .. _AddressSanitizer: https://clang.llvm.org/docs/AddressSanitizer.html
 103 .. _HardwareAssistedAddressSanitizer: https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html