1======================== 2Scudo Hardened Allocator 3======================== 4 5.. contents:: 6 :local: 7 :depth: 1 8 9Introduction 10============ 11The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer's 12CombinedAllocator, which aims at providing additional mitigations against heap 13based vulnerabilities, while maintaining good performance. 14 15The name "Scudo" has been retained from the initial implementation (Escudo 16meaning Shield in Spanish and Portuguese). 17 18Design 19====== 20Chunk Header 21------------ 22Every chunk of heap memory will be preceded by a chunk header. This has two 23purposes, the first one being to store various information about the chunk, 24the second one being to detect potential heap overflows. In order to achieve 25this, the header will be checksumed, involving the pointer to the chunk itself 26and a global secret. Any corruption of the header will be detected when said 27header is accessed, and the process terminated. 28 29The following information is stored in the header: 30 31- the 16-bit checksum; 32- the user requested size for that chunk, which is necessary for reallocation 33 purposes; 34- the state of the chunk (available, allocated or quarantined); 35- the allocation type (malloc, new, new[] or memalign), to detect potential 36 mismatches in the allocation APIs used; 37- whether or not the chunk is offseted (ie: if the chunk beginning is different 38 than the backend allocation beginning, which is most often the case with some 39 aligned allocations); 40- the associated offset; 41- a 16-bit salt. 42 43On x64, which is currently the only architecture supported, the header fits 44within 16-bytes, which works nicely with the minimum alignment requirements. 45 46The checksum is computed as a CRC32 (requiring the SSE 4.2 instruction set) 47of the global secret, the chunk pointer itself, and the 16 bytes of header with 48the checksum field zeroed out. 49 50The header is atomically loaded and stored to prevent races (this requires 51platform support such as the cmpxchg16b instruction). This is important as two 52consecutive chunks could belong to different threads. We also want to avoid 53any type of double fetches of information located in the header, and use local 54copies of the header for this purpose. 55 56Delayed Freelist 57----------------- 58A delayed freelist allows us to not return a chunk directly to the backend, but 59to keep it aside for a while. Once a criterion is met, the delayed freelist is 60emptied, and the quarantined chunks are returned to the backend. This helps 61mitigate use-after-free vulnerabilities by reducing the determinism of the 62allocation and deallocation patterns. 63 64This feature is using the Sanitizer's Quarantine as its base, and the amount of 65memory that it can hold is configurable by the user (see the Options section 66below). 67 68Randomness 69---------- 70It is important for the allocator to not make use of fixed addresses. We use 71the dynamic base option for the SizeClassAllocator, allowing us to benefit 72from the randomness of mmap. 73 74Usage 75===== 76 77Library 78------- 79The allocator static library can be built from the LLVM build tree thanks to 80the "scudo" CMake rule. The associated tests can be exercised thanks to the 81"check-scudo" CMake rule. 82 83Linking the static library to your project can require the use of the 84"whole-archive" linker flag (or equivalent), depending on your linker. 85Additional flags might also be necessary. 86 87Your linked binary should now make use of the Scudo allocation and deallocation 88functions. 89 90Options 91------- 92Several aspects of the allocator can be configured through environment options, 93following the usual ASan options syntax, through the variable SCUDO_OPTIONS. 94 95For example: SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeMb=16". 96 97The following options are available: 98 99- QuarantineSizeMb (integer, defaults to 64): the size (in Mb) of quarantine 100 used to delay the actual deallocation of chunks. Lower value may reduce 101 memory usage but decrease the effectiveness of the mitigation; a negative 102 value will fallback to a default of 64Mb; 103 104- ThreadLocalQuarantineSizeKb (integer, default to 1024): the size (in Kb) of 105 per-thread cache used to offload the global quarantine. Lower value may 106 reduce memory usage but might increase the contention on the global 107 quarantine. 108 109- DeallocationTypeMismatch (boolean, defaults to true): whether or not we report 110 errors on malloc/delete, new/free, new/delete[], etc; 111 112- DeleteSizeMismatch (boolean, defaults to true): whether or not we report 113 errors on mismatch between size of new and delete; 114 115- ZeroContents (boolean, defaults to false): whether or not we zero chunk 116 contents on allocation and deallocation. 117 118