doc/security/hardened_malloc.adoc

= GrapheneOS hardened_malloc

Version: 0.1.0.11


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

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