From: Kostya Kortchinsky Date: Thu, 9 Feb 2017 16:07:52 +0000 (+0000) Subject: [docs] Documentation update for Scudo X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4795c086b6d946d0a4ec4980469df11c92db299a;p=llvm [docs] Documentation update for Scudo Summary: Documentation update to reflect the changes that occured in the allocator: - additional architectures support; - modification of the header; - options default values for 32 & 64-bit. Reviewers: kcc, alekseyshl Subscribers: llvm-commits Differential Revision: https://reviews.llvm.org/D29592 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@294595 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/ScudoHardenedAllocator.rst b/docs/ScudoHardenedAllocator.rst index a22051cca06..e00c8324e55 100644 --- a/docs/ScudoHardenedAllocator.rst +++ b/docs/ScudoHardenedAllocator.rst @@ -13,6 +13,13 @@ The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer's CombinedAllocator, which aims at providing additional mitigations against heap based vulnerabilities, while maintaining good performance. +Currently, the allocator supports (was tested on) the following architectures: + +- i386 (& i686) (32-bit); +- x86_64 (64-bit); +- armhf (32-bit); +- AArch64 (64-bit). + The name "Scudo" has been retained from the initial implementation (Escudo meaning Shield in Spanish and Portuguese). @@ -31,29 +38,25 @@ header is accessed, and the process terminated. The following information is stored in the header: - the 16-bit checksum; -- the user requested size for that chunk, which is necessary for reallocation - purposes; +- the unused bytes amount for that chunk, which is necessary for computing the + size of the chunk; - the state of the chunk (available, allocated or quarantined); - the allocation type (malloc, new, new[] or memalign), to detect potential mismatches in the allocation APIs used; -- whether or not the chunk is offseted (ie: if the chunk beginning is different - than the backend allocation beginning, which is most often the case with some - aligned allocations); -- the associated offset; -- a 16-bit salt. +- the offset of the chunk, which is the distance in bytes from the beginning of + the returned chunk to the beginning of the backend allocation; +- a 8-bit salt. -On x64, which is currently the only architecture supported, the header fits -within 16-bytes, which works nicely with the minimum alignment requirements. +This header fits within 8 bytes, on all platforms supported. -The checksum is computed as a CRC32 (requiring the SSE 4.2 instruction set) -of the global secret, the chunk pointer itself, and the 16 bytes of header with +The checksum is computed as a CRC32 (made faster with hardware support) +of the global secret, the chunk pointer itself, and the 8 bytes of header with the checksum field zeroed out. -The header is atomically loaded and stored to prevent races (this requires -platform support such as the cmpxchg16b instruction). This is important as two -consecutive chunks could belong to different threads. We also want to avoid -any type of double fetches of information located in the header, and use local -copies of the header for this purpose. +The header is atomically loaded and stored to prevent races. This is important +as two consecutive chunks could belong to different threads. We also want to +avoid any type of double fetches of information located in the header, and use +local copies of the header for this purpose. Delayed Freelist ----------------- @@ -94,9 +97,9 @@ You may also build Scudo like this: .. code:: cd $LLVM/projects/compiler-rt/lib - clang++ -fPIC -std=c++11 -msse4.2 -mcx16 -O2 -I. scudo/*.cpp \ + clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \ $(\ls sanitizer_common/*.{cc,S} | grep -v "sanitizer_termination\|sanitizer_common_nolibc") \ - -shared -o scudo-allocator.so -lpthread + -shared -o scudo-allocator.so -pthread and then use it with existing binaries as follows: @@ -136,29 +139,29 @@ Or using the function: The following options are available: -+-----------------------------+---------+------------------------------------------------+ -| Option | Default | Description | -+-----------------------------+---------+------------------------------------------------+ -| QuarantineSizeMb | 64 | The size (in Mb) of quarantine used to delay | -| | | the actual deallocation of chunks. Lower value | -| | | may reduce memory usage but decrease the | -| | | effectiveness of the mitigation; a negative | -| | | value will fallback to a default of 64Mb. | -+-----------------------------+---------+------------------------------------------------+ -| ThreadLocalQuarantineSizeKb | 1024 | The size (in Kb) of per-thread cache use to | -| | | offload the global quarantine. Lower value may | -| | | reduce memory usage but might increase | -| | | contention on the global quarantine. | -+-----------------------------+---------+------------------------------------------------+ -| DeallocationTypeMismatch | true | Whether or not we report errors on | -| | | malloc/delete, new/free, new/delete[], etc. | -+-----------------------------+---------+------------------------------------------------+ -| DeleteSizeMismatch | true | Whether or not we report errors on mismatch | -| | | between sizes of new and delete. | -+-----------------------------+---------+------------------------------------------------+ -| ZeroContents | false | Whether or not we zero chunk contents on | -| | | allocation and deallocation. | -+-----------------------------+---------+------------------------------------------------+ ++-----------------------------+----------------+----------------+------------------------------------------------+ +| Option | 64-bit default | 32-bit default | Description | ++-----------------------------+----------------+----------------+------------------------------------------------+ +| QuarantineSizeMb | 64 | 16 | The size (in Mb) of quarantine used to delay | +| | | | the actual deallocation of chunks. Lower value | +| | | | may reduce memory usage but decrease the | +| | | | effectiveness of the mitigation; a negative | +| | | | value will fallback to a default of 64Mb. | ++-----------------------------+----------------+----------------+------------------------------------------------+ +| ThreadLocalQuarantineSizeKb | 1024 | 256 | The size (in Kb) of per-thread cache use to | +| | | | offload the global quarantine. Lower value may | +| | | | reduce memory usage but might increase | +| | | | contention on the global quarantine. | ++-----------------------------+----------------+----------------+------------------------------------------------+ +| DeallocationTypeMismatch | true | true | Whether or not we report errors on | +| | | | malloc/delete, new/free, new/delete[], etc. | ++-----------------------------+----------------+----------------+------------------------------------------------+ +| DeleteSizeMismatch | true | true | Whether or not we report errors on mismatch | +| | | | between sizes of new and delete. | ++-----------------------------+----------------+----------------+------------------------------------------------+ +| ZeroContents | false | false | Whether or not we zero chunk contents on | +| | | | allocation and deallocation. | ++-----------------------------+----------------+----------------+------------------------------------------------+ Allocator related common Sanitizer options can also be passed through Scudo options, such as ``allocator_may_return_null``. A detailed list including those