diff --git a/security/hardened_malloc.adoc b/security/hardened_malloc.adoc index d60be7b..f38bfcd 100644 --- a/security/hardened_malloc.adoc +++ b/security/hardened_malloc.adoc @@ -1,12 +1,15 @@ = GrapheneOS hardened_malloc -Version: 0.0.0.7 +Version: 0.1.0.12 This documentation contains instructions to use -https://github.com/GrapheneOS/hardened_malloc[GrapheneOS' hardened_malloc] memory allocator as the +https://github.com/GrapheneOS/hardened_malloc[GrapheneOS hardened_malloc] memory allocator as the system's default memory allocator. These instructions apply to both musl and glibc C libraries on -Unix-based and Unix-like systems. +Unix-based and Unix-like systems. hardened_malloc can also be used per-application and/or per-user, +in which case root permissions are not required; this documentation focuses on system-wide usage +of hardened_malloc, assumes root privileges, and assumes the compiled library will be located in a +path readable by all users of the system. == Increase Permitted Amount of Memory Pages @@ -16,25 +19,40 @@ of guard pages. == Clone hardened_malloc Source Code -`git clone https://github.com/GrapheneOS/hardened_malloc.git` +`$ git clone https://github.com/GrapheneOS/hardened_malloc.git` == Enter hardened_malloc Local Git Repository -`cd hardened_malloc/` +`$ cd hardened_malloc/` == Compile hardened_malloc -`make ` +`$ make ` `CONFIG_N_ARENA=n` can be adjusted to increase parallel performance at the expense of memory usage, -or decrease memory usage at the expense of parallel performance, where `n` is an integer; higher -values prefer parallel performance, lower values prefer lower memory usage. For low-memory systems, -`VARIANT=light` can be used to compile the light variant of hardened_malloc, which sacrifices some -security for much less memory usage. +or decrease memory usage at the expense of parallel performance, where `n` is an integer. Higher +values prefer parallel performance, lower values prefer lower memory usage. The number of arenas has +no impact on the security properties of hardened_malloc. + +* Minimum number of arenas: 1 +* Maximum number of arenas: 256 + +For extra security, `CONFIG_SEAL_METADATA=true` can be used in order to control whether Memory +Protection Keys are used to disable access to all writable allocator state outside of the memory +allocator code. It's currently disabled by default due to a significant performance cost for this +use case on current generation hardware. Whether or not this feature is enabled, the metadata is all +contained within an isolated memory region with high entropy random guard regions around it. + +For low-memory systems, `VARIANT=light` can be used to compile the light variant of hardened_malloc, +which sacrifices some security for much less memory usage. + +For all compile-time options, see the +https://github.com/GrapheneOS/hardened_malloc#configuration[configuration section] of +hardened_malloc's extensive official documentation. == Copy Compiled hardened_malloc Library -`cp out/libhardened_malloc.so ` +`# cp out/libhardened_malloc.so ` == Set System to Preload hardened_malloc on Boot