Home | History | Annotate | Download | only in docs
      1 ========================
      2 Scudo Hardened Allocator
      3 ========================
      4 
      5 .. contents::
      6    :local:
      7    :depth: 1
      8 
      9 Introduction
     10 ============
     11 The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer's
     12 CombinedAllocator, which aims at providing additional mitigations against heap
     13 based vulnerabilities, while maintaining good performance.
     14 
     15 The name "Scudo" has been retained from the initial implementation (Escudo
     16 meaning Shield in Spanish and Portuguese).
     17 
     18 Design
     19 ======
     20 Chunk Header
     21 ------------
     22 Every chunk of heap memory will be preceded by a chunk header. This has two
     23 purposes, the first one being to store various information about the chunk,
     24 the second one being to detect potential heap overflows. In order to achieve
     25 this, the header will be checksumed, involving the pointer to the chunk itself
     26 and a global secret. Any corruption of the header will be detected when said
     27 header is accessed, and the process terminated.
     28 
     29 The 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 
     43 On x64, which is currently the only architecture supported, the header fits
     44 within 16-bytes, which works nicely with the minimum alignment requirements.
     45 
     46 The checksum is computed as a CRC32 (requiring the SSE 4.2 instruction set)
     47 of the global secret, the chunk pointer itself, and the 16 bytes of header with
     48 the checksum field zeroed out.
     49 
     50 The header is atomically loaded and stored to prevent races (this requires
     51 platform support such as the cmpxchg16b instruction). This is important as two
     52 consecutive chunks could belong to different threads. We also want to avoid
     53 any type of double fetches of information located in the header, and use local
     54 copies of the header for this purpose.
     55 
     56 Delayed Freelist
     57 -----------------
     58 A delayed freelist allows us to not return a chunk directly to the backend, but
     59 to keep it aside for a while. Once a criterion is met, the delayed freelist is
     60 emptied, and the quarantined chunks are returned to the backend. This helps
     61 mitigate use-after-free vulnerabilities by reducing the determinism of the
     62 allocation and deallocation patterns.
     63 
     64 This feature is using the Sanitizer's Quarantine as its base, and the amount of
     65 memory that it can hold is configurable by the user (see the Options section
     66 below).
     67 
     68 Randomness
     69 ----------
     70 It is important for the allocator to not make use of fixed addresses. We use
     71 the dynamic base option for the SizeClassAllocator, allowing us to benefit
     72 from the randomness of mmap.
     73 
     74 Usage
     75 =====
     76 
     77 Library
     78 -------
     79 The allocator static library can be built from the LLVM build tree thanks to
     80 the "scudo" CMake rule. The associated tests can be exercised thanks to the
     81 "check-scudo" CMake rule.
     82 
     83 Linking the static library to your project can require the use of the
     84 "whole-archive" linker flag (or equivalent), depending on your linker.
     85 Additional flags might also be necessary.
     86 
     87 Your linked binary should now make use of the Scudo allocation and deallocation
     88 functions.
     89 
     90 Options
     91 -------
     92 Several aspects of the allocator can be configured through environment options,
     93 following the usual ASan options syntax, through the variable SCUDO_OPTIONS.
     94 
     95 For example: SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeMb=16".
     96 
     97 The 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