docs/ScudoHardenedAllocator.rst

   1 ========================
   2 Scudo Hardened Allocator
   3 ========================
   4
   5 .. contents::
   6    :local:
   7    :depth: 1
   8
   9 Introduction
  10 ============
  11
  12 The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer's
  13 CombinedAllocator, which aims at providing additional mitigations against heap
  14 based vulnerabilities, while maintaining good performance.
  15
  16 Currently, the allocator supports (was tested on) the following architectures:
  17
  18 - i386 (& i686) (32-bit);
  19 - x86_64 (64-bit);
  20 - armhf (32-bit);
  21 - AArch64 (64-bit).
  22
  23 The name "Scudo" has been retained from the initial implementation (Escudo
  24 meaning Shield in Spanish and Portuguese).
  25
  26 Design
  27 ======
  28
  29 Chunk Header
  30 ------------
  31 Every chunk of heap memory will be preceded by a chunk header. This has two
  32 purposes, the first one being to store various information about the chunk,
  33 the second one being to detect potential heap overflows. In order to achieve
  34 this, the header will be checksumed, involving the pointer to the chunk itself
  35 and a global secret. Any corruption of the header will be detected when said
  36 header is accessed, and the process terminated.
  37
  38 The following information is stored in the header:
  39
  40 - the 16-bit checksum;
  41 - the unused bytes amount for that chunk, which is necessary for computing the
  42   size of the chunk;
  43 - the state of the chunk (available, allocated or quarantined);
  44 - the allocation type (malloc, new, new[] or memalign), to detect potential
  45   mismatches in the allocation APIs used;
  46 - the offset of the chunk, which is the distance in bytes from the beginning of
  47   the returned chunk to the beginning of the backend allocation;
  48 - a 8-bit salt.
  49
  50 This header fits within 8 bytes, on all platforms supported.
  51
  52 The checksum is computed as a CRC32 (made faster with hardware support)
  53 of the global secret, the chunk pointer itself, and the 8 bytes of header with
  54 the checksum field zeroed out.
  55
  56 The header is atomically loaded and stored to prevent races. This is important
  57 as two consecutive chunks could belong to different threads. We also want to
  58 avoid any type of double fetches of information located in the header, and use
  59 local copies of the header for this purpose.
  60
  61 Delayed Freelist
  62 -----------------
  63 A delayed freelist allows us to not return a chunk directly to the backend, but
  64 to keep it aside for a while. Once a criterion is met, the delayed freelist is
  65 emptied, and the quarantined chunks are returned to the backend. This helps
  66 mitigate use-after-free vulnerabilities by reducing the determinism of the
  67 allocation and deallocation patterns.
  68
  69 This feature is using the Sanitizer's Quarantine as its base, and the amount of
  70 memory that it can hold is configurable by the user (see the Options section
  71 below).
  72
  73 Randomness
  74 ----------
  75 It is important for the allocator to not make use of fixed addresses. We use
  76 the dynamic base option for the SizeClassAllocator, allowing us to benefit
  77 from the randomness of mmap.
  78
  79 Usage
  80 =====
  81
  82 Library
  83 -------
  84 The allocator static library can be built from the LLVM build tree thanks to
  85 the ``scudo`` CMake rule. The associated tests can be exercised thanks to the
  86 ``check-scudo`` CMake rule.
  87
  88 Linking the static library to your project can require the use of the
  89 ``whole-archive`` linker flag (or equivalent), depending on your linker.
  90 Additional flags might also be necessary.
  91
  92 Your linked binary should now make use of the Scudo allocation and deallocation
  93 functions.
  94
  95 You may also build Scudo like this:
  96
  97 .. code::
  98
  99   cd $LLVM/projects/compiler-rt/lib
 100   clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \
 101     $(\ls sanitizer_common/*.{cc,S} | grep -v "sanitizer_termination\|sanitizer_common_nolibc") \
 102     -shared -o scudo-allocator.so -pthread
 103
 104 and then use it with existing binaries as follows:
 105
 106 .. code::
 107
 108   LD_PRELOAD=`pwd`/scudo-allocator.so ./a.out
 109
 110 Options
 111 -------
 112 Several aspects of the allocator can be configured through the following ways:
 113
 114 - by defining a ``__scudo_default_options`` function in one's program that
 115   returns the options string to be parsed. Said function must have the following
 116   prototype: ``extern "C" const char* __scudo_default_options()``.
 117
 118 - through the environment variable SCUDO_OPTIONS, containing the options string
 119   to be parsed. Options defined this way will override any definition made
 120   through ``__scudo_default_options``;
 121
 122 The options string follows a syntax similar to ASan, where distinct options
 123 can be assigned in the same string, separated by colons.
 124
 125 For example, using the environment variable:
 126
 127 .. code::
 128
 129   SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeMb=16" ./a.out
 130
 131 Or using the function:
 132
 133 .. code::
 134
 135   extern "C" const char *__scudo_default_options() {
 136     return "DeleteSizeMismatch=1:QuarantineSizeMb=16";
 137   }
 138
 139
 140 The following options are available:
 141
 142 +-----------------------------+----------------+----------------+------------------------------------------------+
 143 | Option                      | 64-bit default | 32-bit default | Description                                    |
 144 +-----------------------------+----------------+----------------+------------------------------------------------+
 145 | QuarantineSizeMb            | 64             | 16             | The size (in Mb) of quarantine used to delay   |
 146 |                             |                |                | the actual deallocation of chunks. Lower value |
 147 |                             |                |                | may reduce memory usage but decrease the       |
 148 |                             |                |                | effectiveness of the mitigation; a negative    |
 149 |                             |                |                | value will fallback to a default of 64Mb.      |
 150 +-----------------------------+----------------+----------------+------------------------------------------------+
 151 | ThreadLocalQuarantineSizeKb | 1024           | 256            | The size (in Kb) of per-thread cache use to    |
 152 |                             |                |                | offload the global quarantine. Lower value may |
 153 |                             |                |                | reduce memory usage but might increase         |
 154 |                             |                |                | contention on the global quarantine.           |
 155 +-----------------------------+----------------+----------------+------------------------------------------------+
 156 | DeallocationTypeMismatch    | true           | true           | Whether or not we report errors on             |
 157 |                             |                |                | malloc/delete, new/free, new/delete[], etc.    |
 158 +-----------------------------+----------------+----------------+------------------------------------------------+
 159 | DeleteSizeMismatch          | true           | true           | Whether or not we report errors on mismatch    |
 160 |                             |                |                | between sizes of new and delete.               |
 161 +-----------------------------+----------------+----------------+------------------------------------------------+
 162 | ZeroContents                | false          | false          | Whether or not we zero chunk contents on       |
 163 |                             |                |                | allocation and deallocation.                   |
 164 +-----------------------------+----------------+----------------+------------------------------------------------+
 165
 166 Allocator related common Sanitizer options can also be passed through Scudo
 167 options, such as ``allocator_may_return_null``. A detailed list including those
 168 can be found here:
 169 https://github.com/google/sanitizers/wiki/SanitizerCommonFlags.
 170