diff --git a/llvm/docs/MemTagSanitizer.rst b/llvm/docs/MemTagSanitizer.rst new file mode 100644 --- /dev/null +++ b/llvm/docs/MemTagSanitizer.rst @@ -0,0 +1,99 @@ +================ +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 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 +`_ +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 `_ +* `Memory Tagging Whitepaper `_ + +.. _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 --- a/llvm/docs/Reference.rst +++ b/llvm/docs/Reference.rst @@ -36,6 +36,7 @@ ORCv2 PDB/index ScudoHardenedAllocator + MemTagSanitizer SegmentedStacks StackMaps SpeculativeLoadHardening @@ -187,6 +188,10 @@ :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 ` A description of the design of the various dependence graphs such as the DDG (Data Dependence Graph). @@ -208,4 +213,4 @@ LLVM support for coroutines. :doc:`YamlIO` - A reference guide for using LLVM's YAML I/O library. \ No newline at end of file + A reference guide for using LLVM's YAML I/O library.