1======================== 2Scudo Hardened Allocator 3======================== 4 5.. contents:: 6 :local: 7 :depth: 1 8 9Introduction 10============ 11 12The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer's 13CombinedAllocator, which aims at providing additional mitigations against heap 14based vulnerabilities, while maintaining good performance. 15 16Currently, 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- MIPS (32-bit & 64-bit). 23 24The name "Scudo" has been retained from the initial implementation (Escudo 25meaning Shield in Spanish and Portuguese). 26 27Design 28====== 29 30Allocator 31--------- 32Scudo can be considered a Frontend to the Sanitizers' common allocator (later 33referenced as the Backend). It is split between a Primary allocator, fast and 34efficient, that services smaller allocation sizes, and a Secondary allocator 35that services larger allocation sizes and is backed by the operating system 36memory mapping primitives. 37 38Scudo was designed with security in mind, but aims at striking a good balance 39between security and performance. It is highly tunable and configurable. 40 41Chunk Header 42------------ 43Every chunk of heap memory will be preceded by a chunk header. This has two 44purposes, the first one being to store various information about the chunk, 45the second one being to detect potential heap overflows. In order to achieve 46this, the header will be checksummed, involving the pointer to the chunk itself 47and a global secret. Any corruption of the header will be detected when said 48header is accessed, and the process terminated. 49 50The following information is stored in the header: 51 52- the 16-bit checksum; 53- the class ID for that chunk, which is the "bucket" where the chunk resides 54 for Primary backed allocations, or 0 for Secondary backed allocations; 55- the size (Primary) or unused bytes amount (Secondary) for that chunk, which is 56 necessary for computing the size of the chunk; 57- the state of the chunk (available, allocated or quarantined); 58- the allocation type (malloc, new, new[] or memalign), to detect potential 59 mismatches in the allocation APIs used; 60- the offset of the chunk, which is the distance in bytes from the beginning of 61 the returned chunk to the beginning of the Backend allocation; 62 63This header fits within 8 bytes, on all platforms supported. 64 65The checksum is computed as a CRC32 (made faster with hardware support) 66of the global secret, the chunk pointer itself, and the 8 bytes of header with 67the checksum field zeroed out. It is not intended to be cryptographically 68strong. 69 70The header is atomically loaded and stored to prevent races. This is important 71as two consecutive chunks could belong to different threads. We also want to 72avoid any type of double fetches of information located in the header, and use 73local copies of the header for this purpose. 74 75Delayed Freelist 76----------------- 77A delayed freelist allows us to not return a chunk directly to the Backend, but 78to keep it aside for a while. Once a criterion is met, the delayed freelist is 79emptied, and the quarantined chunks are returned to the Backend. This helps 80mitigate use-after-free vulnerabilities by reducing the determinism of the 81allocation and deallocation patterns. 82 83This feature is using the Sanitizer's Quarantine as its base, and the amount of 84memory that it can hold is configurable by the user (see the Options section 85below). 86 87Randomness 88---------- 89It is important for the allocator to not make use of fixed addresses. We use 90the dynamic base option for the SizeClassAllocator, allowing us to benefit 91from the randomness of the system memory mapping functions. 92 93Usage 94===== 95 96Library 97------- 98The allocator static library can be built from the LLVM build tree thanks to 99the ``scudo`` CMake rule. The associated tests can be exercised thanks to the 100``check-scudo`` CMake rule. 101 102Linking the static library to your project can require the use of the 103``whole-archive`` linker flag (or equivalent), depending on your linker. 104Additional flags might also be necessary. 105 106Your linked binary should now make use of the Scudo allocation and deallocation 107functions. 108 109You may also build Scudo like this: 110 111.. code:: console 112 113 cd $LLVM/projects/compiler-rt/lib 114 clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \ 115 $(\ls sanitizer_common/*.{cc,S} | grep -v "sanitizer_termination\|sanitizer_common_nolibc\|sancov_\|sanitizer_unwind\|sanitizer_symbol") \ 116 -shared -o libscudo.so -pthread 117 118and then use it with existing binaries as follows: 119 120.. code:: console 121 122 LD_PRELOAD=`pwd`/libscudo.so ./a.out 123 124Clang 125----- 126With a recent version of Clang (post rL317337), the allocator can be linked with 127a binary at compilation using the ``-fsanitize=scudo`` command-line argument, if 128the target platform is supported. Currently, the only other Sanitizer Scudo is 129compatible with is UBSan (eg: ``-fsanitize=scudo,undefined``). Compiling with 130Scudo will also enforce PIE for the output binary. 131 132Options 133------- 134Several aspects of the allocator can be configured on a per process basis 135through the following ways: 136 137- at compile time, by defining ``SCUDO_DEFAULT_OPTIONS`` to the options string 138 you want set by default; 139 140- by defining a ``__scudo_default_options`` function in one's program that 141 returns the options string to be parsed. Said function must have the following 142 prototype: ``extern "C" const char* __scudo_default_options(void)``, with a 143 default visibility. This will override the compile time define; 144 145- through the environment variable SCUDO_OPTIONS, containing the options string 146 to be parsed. Options defined this way will override any definition made 147 through ``__scudo_default_options``. 148 149The options string follows a syntax similar to ASan, where distinct options 150can be assigned in the same string, separated by colons. 151 152For example, using the environment variable: 153 154.. code:: console 155 156 SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeKb=64" ./a.out 157 158Or using the function: 159 160.. code:: cpp 161 162 extern "C" const char *__scudo_default_options() { 163 return "DeleteSizeMismatch=1:QuarantineSizeKb=64"; 164 } 165 166 167The following options are available: 168 169+-----------------------------+----------------+----------------+------------------------------------------------+ 170| Option | 64-bit default | 32-bit default | Description | 171+-----------------------------+----------------+----------------+------------------------------------------------+ 172| QuarantineSizeKb | 256 | 64 | The size (in Kb) of quarantine used to delay | 173| | | | the actual deallocation of chunks. Lower value | 174| | | | may reduce memory usage but decrease the | 175| | | | effectiveness of the mitigation; a negative | 176| | | | value will fallback to the defaults. Setting | 177| | | | *both* this and ThreadLocalQuarantineSizeKb to | 178| | | | zero will disable the quarantine entirely. | 179+-----------------------------+----------------+----------------+------------------------------------------------+ 180| QuarantineChunksUpToSize | 2048 | 512 | Size (in bytes) up to which chunks can be | 181| | | | quarantined. | 182+-----------------------------+----------------+----------------+------------------------------------------------+ 183| ThreadLocalQuarantineSizeKb | 1024 | 256 | The size (in Kb) of per-thread cache use to | 184| | | | offload the global quarantine. Lower value may | 185| | | | reduce memory usage but might increase | 186| | | | contention on the global quarantine. Setting | 187| | | | *both* this and QuarantineSizeKb to zero will | 188| | | | disable the quarantine entirely. | 189+-----------------------------+----------------+----------------+------------------------------------------------+ 190| DeallocationTypeMismatch | true | true | Whether or not we report errors on | 191| | | | malloc/delete, new/free, new/delete[], etc. | 192+-----------------------------+----------------+----------------+------------------------------------------------+ 193| DeleteSizeMismatch | true | true | Whether or not we report errors on mismatch | 194| | | | between sizes of new and delete. | 195+-----------------------------+----------------+----------------+------------------------------------------------+ 196| ZeroContents | false | false | Whether or not we zero chunk contents on | 197| | | | allocation and deallocation. | 198+-----------------------------+----------------+----------------+------------------------------------------------+ 199 200Allocator related common Sanitizer options can also be passed through Scudo 201options, such as ``allocator_may_return_null`` or ``abort_on_error``. A detailed 202list including those can be found here: 203https://github.com/google/sanitizers/wiki/SanitizerCommonFlags. 204 205Error Types 206=========== 207 208The allocator will output an error message, and potentially terminate the 209process, when an unexpected behavior is detected. The output usually starts with 210``"Scudo ERROR:"`` followed by a short summary of the problem that occurred as 211well as the pointer(s) involved. Once again, Scudo is meant to be a mitigation, 212and might not be the most useful of tools to help you root-cause the issue, 213please consider `ASan <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_ 214for this purpose. 215 216Here is a list of the current error messages and their potential cause: 217 218- ``"corrupted chunk header"``: the checksum verification of the chunk header 219 has failed. This is likely due to one of two things: the header was 220 overwritten (partially or totally), or the pointer passed to the function is 221 not a chunk at all; 222 223- ``"race on chunk header"``: two different threads are attempting to manipulate 224 the same header at the same time. This is usually symptomatic of a 225 race-condition or general lack of locking when performing operations on that 226 chunk; 227 228- ``"invalid chunk state"``: the chunk is not in the expected state for a given 229 operation, eg: it is not allocated when trying to free it, or it's not 230 quarantined when trying to recycle it, etc. A double-free is the typical 231 reason this error would occur; 232 233- ``"misaligned pointer"``: we strongly enforce basic alignment requirements, 8 234 bytes on 32-bit platforms, 16 bytes on 64-bit platforms. If a pointer passed 235 to our functions does not fit those, something is definitely wrong. 236 237- ``"allocation type mismatch"``: when the optional deallocation type mismatch 238 check is enabled, a deallocation function called on a chunk has to match the 239 type of function that was called to allocate it. Security implications of such 240 a mismatch are not necessarily obvious but situational at best; 241 242- ``"invalid sized delete"``: when the C++14 sized delete operator is used, and 243 the optional check enabled, this indicates that the size passed when 244 deallocating a chunk is not congruent with the one requested when allocating 245 it. This is likely to be a `compiler issue <https://software.intel.com/en-us/forums/intel-c-compiler/topic/783942>`_, 246 as was the case with Intel C++ Compiler, or some type confusion on the object 247 being deallocated; 248 249- ``"RSS limit exhausted"``: the maximum RSS optionally specified has been 250 exceeded; 251 252Several other error messages relate to parameter checking on the libc allocation 253APIs and are fairly straightforward to understand. 254