llvm.org GIT mirror llvm / 014bd60
[docs] Update Scudo documentation Summary: The documentation has fallen a bit behind, update it with the latest evolution of the allocator: - clarify a couple of expectations regarding what is meant to be achieved; - update the header format; - document `-fsanitize=scudo`. Reviewers: alekseyshl, flowerhack Reviewed By: alekseyshl Subscribers: llvm-commits Differential Revision: https://reviews.llvm.org/D41670 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@321811 91177308-0d34-0410-b5e6-96231b3b80d8 Kostya Kortchinsky 1 year, 10 months ago
1 changed file(s) with 30 addition(s) and 9 deletion(s). Raw diff Collapse all Expand all
2525 Design
2626 ======
2727
28 Allocator
29 ---------
30 Scudo can be considered a Frontend to the Sanitizers' common allocator (later
31 referenced as the Backend). It is split between a Primary allocator, fast and
32 efficient, that services smaller allocation sizes, and a Secondary allocator
33 that services larger allocation sizes and is backed by the operating system
34 memory mapping primitives.
35
36 Scudo was designed with security in mind, but aims at striking a good balance
37 between security and performance. It is highly tunable and configurable.
38
2839 Chunk Header
2940 ------------
3041 Every chunk of heap memory will be preceded by a chunk header. This has two
3142 purposes, the first one being to store various information about the chunk,
3243 the second one being to detect potential heap overflows. In order to achieve
33 this, the header will be checksumed, involving the pointer to the chunk itself
44 this, the header will be checksummed, involving the pointer to the chunk itself
3445 and a global secret. Any corruption of the header will be detected when said
3546 header is accessed, and the process terminated.
3647
3748 The following information is stored in the header:
3849
3950 - the 16-bit checksum;
40 - the unused bytes amount for that chunk, which is necessary for computing the
41 size of the chunk;
51 - the class ID for that chunk, which is the "bucket" where the chunk resides
52 for Primary backed allocations, or 0 for Secondary backed allocations;
53 - the size (Primary) or unused bytes amount (Secondary) for that chunk, which is
54 necessary for computing the size of the chunk;
4255 - the state of the chunk (available, allocated or quarantined);
4356 - the allocation type (malloc, new, new[] or memalign), to detect potential
4457 mismatches in the allocation APIs used;
4558 - the offset of the chunk, which is the distance in bytes from the beginning of
46 the returned chunk to the beginning of the backend allocation;
47 - a 8-bit salt.
59 the returned chunk to the beginning of the Backend allocation;
4860
4961 This header fits within 8 bytes, on all platforms supported.
5062
5163 The checksum is computed as a CRC32 (made faster with hardware support)
5264 of the global secret, the chunk pointer itself, and the 8 bytes of header with
53 the checksum field zeroed out.
65 the checksum field zeroed out. It is not intended to be cryptographically
66 strong.
5467
5568 The header is atomically loaded and stored to prevent races. This is important
5669 as two consecutive chunks could belong to different threads. We also want to
5972
6073 Delayed Freelist
6174 -----------------
62 A delayed freelist allows us to not return a chunk directly to the backend, but
75 A delayed freelist allows us to not return a chunk directly to the Backend, but
6376 to keep it aside for a while. Once a criterion is met, the delayed freelist is
64 emptied, and the quarantined chunks are returned to the backend. This helps
77 emptied, and the quarantined chunks are returned to the Backend. This helps
6578 mitigate use-after-free vulnerabilities by reducing the determinism of the
6679 allocation and deallocation patterns.
6780
106119
107120 LD_PRELOAD=`pwd`/scudo-allocator.so ./a.out
108121
122 Clang
123 -----
124 With a recent version of Clang (post rL317337), the allocator can be linked with
125 a binary at compilation using the ``-fsanitize=scudo`` command-line argument, if
126 the target platform is supported. Currently, the only other Sanitizer Scudo is
127 compatible with is UBSan (eg: ``-fsanitize=scudo,undefined``). Compiling with
128 Scudo will also enforce PIE for the output binary.
129
109130 Options
110131 -------
111132 Several aspects of the allocator can be configured through the following ways:
112133
113134 - by defining a ``__scudo_default_options`` function in one's program that
114135 returns the options string to be parsed. Said function must have the following
115 prototype: ``extern "C" const char* __scudo_default_options()``.
136 prototype: ``extern "C" const char* __scudo_default_options(void)``.
116137
117138 - through the environment variable SCUDO_OPTIONS, containing the options string
118139 to be parsed. Options defined this way will override any definition made