[llvm] 27c9aba - Add MemTagSanitizer documentation.

[Evgenii Stepanov via llvm-commits]

Author: Evgenii Stepanov
Date: 2019-11-01T10:46:04-07:00
New Revision: 27c9abae656234813931e2717d60c69d988ecedc

URL: https://github.com/llvm/llvm-project/commit/27c9abae656234813931e2717d60c69d988ecedc
DIFF: https://github.com/llvm/llvm-project/commit/27c9abae656234813931e2717d60c69d988ecedc.diff

LOG: Add MemTagSanitizer documentation.

Summary: A lot of this is work in progress...

Reviewers: kcc, pcc

Subscribers: cryptoad, llvm-commits

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D69289

Added: 
    llvm/docs/MemTagSanitizer.rst

Modified: 
    llvm/docs/Reference.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/MemTagSanitizer.rst b/llvm/docs/MemTagSanitizer.rst
new file mode 100644
index 000000000000..a27370368b46
--- /dev/null
+++ b/llvm/docs/MemTagSanitizer.rst
@@ -0,0 +1,98 @@
+================
+MemTagSanitizer
+================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+**Note:** this page describes a tool under development. Part of this
+functionality is planned but not implemented.  Hardware capable of
+running MemTagSanitizer does not exist as of Oct 2019.
+
+MemTagSanitizer is a fast memory error detector and **a code hardening
+tool** based on ARMv9 `Memory Tagging Extension`_. It
+detects a similar class of errors as `AddressSanitizer`_ or `HardwareAssistedAddressSanitizer`_, but with
+**much** lower overhead.
+
+MemTagSanitizer overhead is expected to be in low single digits, both
+CPU and memory. There are plans for a debug mode with slightly higher
+memory overhead and better diagnostics. The primary use case of
+MemTagSanitizer is code hardening in production binaries, where it is
+expected to be a strong mitigation for both stack and heap-based
+memory bugs.
+
+
+Usage
+=====
+
+Compile and link your program with ``-fsanitize=memtag`` flag. This
+will only work when targeting AArch64 with MemTag extension. One
+possible way to achieve that is to add ``-target
+aarch64-linux -march=armv8+memtag`` to compilation flags.
+
+Implementation
+==============
+
+See `HardwareAssistedAddressSanitizer`_ for a general overview of a
+tag-based approach to memory safety.  MemTagSanitizer followes a
+similar implementation strategy, but with the tag storage (shadow)
+provided by the hardware.
+
+A quick overview of MTE hardware capabilities:
+
+* Every 16 aligned bytes of memory can be assigned a 4-bit Allocation Tag.
+* Every pointer can have a 4-bit Address Tag that is in its most significant byte.
+* Most memory access instructions generate an exception if Address Tag != Allocation Tag.
+* Special instructions are provided for fast tag manipulation.
+
+Stack instrumentation
+=====================
+
+Stack-based memory errors are detected by updating Allocation Tag for
+each local variable to a random value at the start of its lifetime,
+and resetting it to the stack pointer Address Tag at the end of
+it. Unallocated stack space is expected to match the Address Tag of
+SP; this allows to skip tagging of any variable when memory safety can
+be statically proven.
+
+Allocating a truly random tag for each stack variable in a large
+function may incur significant code size overhead, because it means
+that each variable's address is an independent, non-rematerializable
+value; thus a function with N local variables will have extra N live
+values to keep through most of its life time.
+
+For this reason MemTagSanitizer generates at most one random tag per
+function, called a "base tag". Other stack variables, if there are
+any, are assigned tags at a fixed offset from the base.
+
+Please refer to `this document
+<https://github.com/google/sanitizers/wiki/Stack-instrumentation-with-ARM-Memory-Tagging-Extension-(MTE)>`_
+for more details about stack instrumentation.
+
+Heap tagging
+============
+
+**Note:** this part is not implemented as of Oct 2019.
+
+MemTagSanitizer will use :doc:`ScudoHardenedAllocator`
+with additional code to update memory tags when
+
+* New memory is obtained from the system.
+* An allocation is freed.
+
+There is no need to change Allocation Tags for the bulk of the
+allocated memory in malloc(), as long as a pointer with the matching
+Address Tag is returned.
+
+More information
+================
+
+* `LLVM Developer Meeting 2018 talk on Memory Tagging <https://llvm.org/devmtg/2018-10/slides/Serebryany-Stepanov-Tsyrklevich-Memory-Tagging-Slides-LLVM-2018.pdf>`_
+* `Memory Tagging Whitepaper <https://arxiv.org/pdf/1802.09517.pdf>`_
+
+.. _Memory Tagging Extension: https://community.arm.com/developer/ip-products/processors/b/processors-ip-blog/posts/arm-a-profile-architecture-2018-developments-armv85a
+.. _AddressSanitizer: https://clang.llvm.org/docs/AddressSanitizer.html
+.. _HardwareAssistedAddressSanitizer: https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html

diff  --git a/llvm/docs/Reference.rst b/llvm/docs/Reference.rst
index 4c421a209274..8aef4eec587d 100644
--- a/llvm/docs/Reference.rst
+++ b/llvm/docs/Reference.rst
@@ -36,6 +36,7 @@ LLVM and API reference documentation.
    ORCv2
    PDB/index
    ScudoHardenedAllocator
+   MemTagSanitizer
    SegmentedStacks
    StackMaps
    SpeculativeLoadHardening
@@ -187,6 +188,10 @@ Additional Topics
 :doc:`ScudoHardenedAllocator`
   A library that implements a security-hardened `malloc()`.
 
+:doc:`MemTagSanitizer`
+  Security hardening for production code aiming to mitigate memory
+  related vulnerabilities. Based on ARMv9 Memory Tagging Extension.
+
 :doc:`Dependence Graphs <DependenceGraphs/index>`
   A description of the design of the various dependence graphs such as
   the DDG (Data Dependence Graph).