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 Allocator
  30 ---------
  31 Scudo can be considered a Frontend to the Sanitizers' common allocator (later
  32 referenced as the Backend). It is split between a Primary allocator, fast and
  33 efficient, that services smaller allocation sizes, and a Secondary allocator
  34 that services larger allocation sizes and is backed by the operating system
  35 memory mapping primitives.
  36
  37 Scudo was designed with security in mind, but aims at striking a good balance
  38 between security and performance. It is highly tunable and configurable.
  39
  40 Chunk Header
  41 ------------
  42 Every chunk of heap memory will be preceded by a chunk header. This has two
  43 purposes, the first one being to store various information about the chunk,
  44 the second one being to detect potential heap overflows. In order to achieve
  45 this, the header will be checksummed, involving the pointer to the chunk itself
  46 and a global secret. Any corruption of the header will be detected when said
  47 header is accessed, and the process terminated.
  48
  49 The following information is stored in the header:
  50
  51 - the 16-bit checksum;
  52 - the class ID for that chunk, which is the "bucket" where the chunk resides
  53   for Primary backed allocations, or 0 for Secondary backed allocations;
  54 - the size (Primary) or unused bytes amount (Secondary) for that chunk, which is
  55   necessary for computing the size of the chunk;
  56 - the state of the chunk (available, allocated or quarantined);
  57 - the allocation type (malloc, new, new[] or memalign), to detect potential
  58   mismatches in the allocation APIs used;
  59 - the offset of the chunk, which is the distance in bytes from the beginning of
  60   the returned chunk to the beginning of the Backend allocation;
  61
  62 This header fits within 8 bytes, on all platforms supported.
  63
  64 The checksum is computed as a CRC32 (made faster with hardware support)
  65 of the global secret, the chunk pointer itself, and the 8 bytes of header with
  66 the checksum field zeroed out. It is not intended to be cryptographically
  67 strong.
  68
  69 The header is atomically loaded and stored to prevent races. This is important
  70 as two consecutive chunks could belong to different threads. We also want to
  71 avoid any type of double fetches of information located in the header, and use
  72 local copies of the header for this purpose.
  73
  74 Delayed Freelist
  75 -----------------
  76 A delayed freelist allows us to not return a chunk directly to the Backend, but
  77 to keep it aside for a while. Once a criterion is met, the delayed freelist is
  78 emptied, and the quarantined chunks are returned to the Backend. This helps
  79 mitigate use-after-free vulnerabilities by reducing the determinism of the
  80 allocation and deallocation patterns.
  81
  82 This feature is using the Sanitizer's Quarantine as its base, and the amount of
  83 memory that it can hold is configurable by the user (see the Options section
  84 below).
  85
  86 Randomness
  87 ----------
  88 It is important for the allocator to not make use of fixed addresses. We use
  89 the dynamic base option for the SizeClassAllocator, allowing us to benefit
  90 from the randomness of mmap.
  91
  92 Usage
  93 =====
  94
  95 Library
  96 -------
  97 The allocator static library can be built from the LLVM build tree thanks to
  98 the ``scudo`` CMake rule. The associated tests can be exercised thanks to the
  99 ``check-scudo`` CMake rule.
 100
 101 Linking the static library to your project can require the use of the
 102 ``whole-archive`` linker flag (or equivalent), depending on your linker.
 103 Additional flags might also be necessary.
 104
 105 Your linked binary should now make use of the Scudo allocation and deallocation
 106 functions.
 107
 108 You may also build Scudo like this:
 109
 110 .. code::
 111
 112   cd $LLVM/projects/compiler-rt/lib
 113   clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \
 114     $(\ls sanitizer_common/*.{cc,S} | grep -v "sanitizer_termination\|sanitizer_common_nolibc") \
 115     -shared -o scudo-allocator.so -pthread
 116
 117 and then use it with existing binaries as follows:
 118
 119 .. code::
 120
 121   LD_PRELOAD=`pwd`/scudo-allocator.so ./a.out
 122
 123 Clang
 124 -----
 125 With a recent version of Clang (post rL317337), the allocator can be linked with
 126 a binary at compilation using the ``-fsanitize=scudo`` command-line argument, if
 127 the target platform is supported. Currently, the only other Sanitizer Scudo is
 128 compatible with is UBSan (eg: ``-fsanitize=scudo,undefined``). Compiling with
 129 Scudo will also enforce PIE for the output binary.
 130
 131 Options
 132 -------
 133 Several aspects of the allocator can be configured through the following ways:
 134
 135 - by defining a ``__scudo_default_options`` function in one's program that
 136   returns the options string to be parsed. Said function must have the following
 137   prototype: ``extern "C" const char* __scudo_default_options(void)``.
 138
 139 - through the environment variable SCUDO_OPTIONS, containing the options string
 140   to be parsed. Options defined this way will override any definition made
 141   through ``__scudo_default_options``;
 142
 143 The options string follows a syntax similar to ASan, where distinct options
 144 can be assigned in the same string, separated by colons.
 145
 146 For example, using the environment variable:
 147
 148 .. code::
 149
 150   SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeKb=64" ./a.out
 151
 152 Or using the function:
 153
 154 .. code:: cpp
 155
 156   extern "C" const char *__scudo_default_options() {
 157     return "DeleteSizeMismatch=1:QuarantineSizeKb=64";
 158   }
 159
 160
 161 The following options are available:
 162
 163 +-----------------------------+----------------+----------------+------------------------------------------------+
 164 | Option                      | 64-bit default | 32-bit default | Description                                    |
 165 +-----------------------------+----------------+----------------+------------------------------------------------+
 166 | QuarantineSizeKb            | 256            | 64             | The size (in Kb) of quarantine used to delay   |
 167 |                             |                |                | the actual deallocation of chunks. Lower value |
 168 |                             |                |                | may reduce memory usage but decrease the       |
 169 |                             |                |                | effectiveness of the mitigation; a negative    |
 170 |                             |                |                | value will fallback to the defaults.           |
 171 +-----------------------------+----------------+----------------+------------------------------------------------+
 172 | QuarantineChunksUpToSize    | 2048           | 512            | Size (in bytes) up to which chunks can be      |
 173 |                             |                |                | quarantined.                                   |
 174 +-----------------------------+----------------+----------------+------------------------------------------------+
 175 | ThreadLocalQuarantineSizeKb | 1024           | 256            | The size (in Kb) of per-thread cache use to    |
 176 |                             |                |                | offload the global quarantine. Lower value may |
 177 |                             |                |                | reduce memory usage but might increase         |
 178 |                             |                |                | contention on the global quarantine.           |
 179 +-----------------------------+----------------+----------------+------------------------------------------------+
 180 | DeallocationTypeMismatch    | true           | true           | Whether or not we report errors on             |
 181 |                             |                |                | malloc/delete, new/free, new/delete[], etc.    |
 182 +-----------------------------+----------------+----------------+------------------------------------------------+
 183 | DeleteSizeMismatch          | true           | true           | Whether or not we report errors on mismatch    |
 184 |                             |                |                | between sizes of new and delete.               |
 185 +-----------------------------+----------------+----------------+------------------------------------------------+
 186 | ZeroContents                | false          | false          | Whether or not we zero chunk contents on       |
 187 |                             |                |                | allocation and deallocation.                   |
 188 +-----------------------------+----------------+----------------+------------------------------------------------+
 189
 190 Allocator related common Sanitizer options can also be passed through Scudo
 191 options, such as ``allocator_may_return_null``. A detailed list including those
 192 can be found here:
 193 https://github.com/google/sanitizers/wiki/SanitizerCommonFlags.
 194