doc/security/hardened_malloc.adoc

= GrapheneOS hardened_malloc

Version: 0.0.0.7


This documentation contains instructions to use
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.


== Increase Permitted Amount of Memory Pages

Add `vm.max_map_count = 1048576` to `/etc/sysctl.conf` to accommodate hardened_malloc's large amount
of guard pages.

== Clone hardened_malloc Source Code

`git clone https://github.com/GrapheneOS/hardened_malloc.git`

== Enter hardened_malloc Local Git Repository

`cd hardened_malloc/`

== Compile hardened_malloc

`make <arguments>`

`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.

== Copy Compiled hardened_malloc Library

`cp out/libhardened_malloc.so <target_path>`

== Set System to Preload hardened_malloc on Boot

musl-based systems: Add `export LD_PRELOAD="<hardened_malloc_path>"` to `/etc/environment` +
 +
glibc-based systems: Add `<hardened_malloc_path>` to `/etc/ld.so.preload`