This documentation contains instructions to use hardened_malloc memory allocator as the system's default memory allocator via dynamic linking as a shared library. These instructions apply to both musl and glibc C libraries on Linux-based 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 readable and executable by all users of the system.
This documentation uses
Linux Filesystem Hierarchy Standard
paths, with the modern /usr/ merge approach of most Linux distributions. For non-standard
configurations, adjust the paths accordingly.
For the complete hardened_malloc documentation, visit its official documentation.
This documentation is also available in portable AsciiDoc format in my documentation source code repository.
Add the following to /etc/sysctl.conf or a configuration file within
/etc/sysctl.d/to accommodate hardened_malloc's large amount of guard pages:
vm.max_map_count = 1048576
$ git clone https://github.com/GrapheneOS/hardened_malloc.git
$ cd 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 a non-negative integer. Higher values prefer parallel performance,
whereas lower values prefer lower memory usage. Note that having too many arenas may cause memory
fragmentation and decrease system performance. The number of arenas has no impact on the security
properties of hardened_malloc.
| Minimum | Maximum | Default |
|---|---|---|
| 1 | 256 | 4 |
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 less memory usage. This option still produces a
more hardened memory allocator than both the default musl and glibc allocators, despite the security
sacrifices over the full variant.
For all compile-time options, see the configuration section of hardened_malloc's official documentation.
# cp out/libhardened_malloc.so /usr/local/lib/libhardened_malloc.so
In order to preload the hardened_malloc shared library on boot, perform the following actions:
musl-based systems: Add the following to /etc/environment or a configuration
file within /etc/environment.d/:
LD_PRELOAD=/usr/local/lib/libhardened_malloc.so
glibc-based systems: Add the following to /etc/ld.so.preload:
/usr/local/lib/libhardened_malloc.so