From 41df5005e8ea053f3c8d10d5201bde69fe6a04ee Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Mon, 4 Feb 2019 13:59:19 -0500 Subject: [PATCH] add a top-level header to the README --- README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 881cbd0..86128a3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Hardened malloc + This is a security-focused general purpose memory allocator providing the malloc API along with various extensions. It provides substantial hardening against heap corruption vulnerabilities. The security-focused design also leads @@ -34,7 +36,7 @@ this project was started as a fresh implementation better able to accomplish the goals. For 32-bit, a port of OpenBSD malloc with small extensions can be used instead as this allocator fundamentally doesn't support that environment. -# Dependencies +## Dependencies Debian stable determines the most ancient set of supported dependencies: @@ -62,7 +64,7 @@ and 9.0 but only the active AOSP branches (8.1 and 9.0) are supported by this project and it doesn't make much sense to use much older releases with far less privacy and security hardening. -# Testing +## Testing The `preload.sh` script can be used for testing with dynamically linked executables using glibc or musl: @@ -83,7 +85,7 @@ this allocator offers across different size classes. The intention is that this will be offered as part of hardened variants of the Bionic and musl C standard libraries. -# Configuration +## Configuration You can set some configuration options at compile-time via arguments to the make command as follows: @@ -175,7 +177,7 @@ control over fairly arbitrarily chosen values like the size of empty slab caches (making them smaller improves security and reduces memory usage while larger caches can substantially improves performance). -# Basic design +## Basic design The current design is very simple and will become a bit more sophisticated as the basic features are completed and the implementation is hardened and @@ -219,7 +221,7 @@ explicitly not on detecting bugs that are impossible to exploit with it in use like an 8 byte overflow. The design choices would be different if performance was a bit less important and if a core goal was finding latent bugs. -# Security properties +## Security properties * Fully out-of-line metadata * Deterministic detection of any invalid free (unallocated, unaligned, etc.) @@ -302,7 +304,7 @@ was a bit less important and if a core goal was finding latent bugs. * guarantee distinct tags for adjacent memory allocations by incrementing past matching values for deterministic detection of linear overflows -# Randomness +## Randomness The current implementation of random number generation for randomization-based mitigations is based on generating a keystream from a stream cipher (ChaCha8) @@ -330,7 +332,7 @@ The random range generation functions are a highly optimized implementation too. Traditional uniform random number generation within a range is very high overhead and can easily dwarf the cost of an efficient CSPRNG. -# Size classes +## Size classes The zero byte size class is a special case of the smallest regular size class. It's allocated in a dedicated region like other size classes but with the slabs @@ -402,7 +404,7 @@ size for 2048 byte spacing and the next spacing class matches the page size of classes required to avoid substantial waste from rounding. Further slab allocation size classes may be offered as an option in the future. -# Memory tagging +## Memory tagging Integrating extensive support for ARMv8.5 memory tagging is planned and this section will be expanded cover the details on the chosen design. The approach @@ -476,7 +478,7 @@ the tag is incremented and wraps around to 0: | 3 | 4 | 16 | 7 | 15 | 0 | -# API extensions +## API extensions The `void free_sized(void *ptr, size_t expected_size)` function exposes the sized deallocation sanity checks for C. A performance-oriented allocator could