Inferencium/doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update GrapheneOS hardened_malloc documentation from version 0.0.0.7 to 0.1.0.12.

Browse Source
This commit is contained in:
inference 2023-06-13 12:59:21 +01:00
parent 9d703608e9
commit b0436f0aea
Signed by: inference
SSH Key Fingerprint: SHA256:9Pl0nZ2UJacgm+IeEtLSZ4FOESgP1eKCtRflfPfdX9M
1 changed files with 29 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
security/hardened_malloc.adoc
View File

@ -1,12 +1,15 @@
= GrapheneOS hardened_malloc = GrapheneOS hardened_malloc
Version: 0.0.0.7 Version: 0.1.0.12
This documentation contains instructions to use 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 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 == Increase Permitted Amount of Memory Pages
@ -16,25 +19,40 @@ of guard pages.
== Clone hardened_malloc Source Code == 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 == Enter hardened_malloc Local Git Repository
`cd hardened_malloc/` `$ cd hardened_malloc/`
== Compile hardened_malloc == Compile hardened_malloc
`make <arguments>` `$ make <arguments>`
`CONFIG_N_ARENA=n` can be adjusted to increase parallel performance at the expense of memory usage, `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 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, values prefer parallel performance, lower values prefer lower memory usage. The number of arenas has
`VARIANT=light` can be used to compile the light variant of hardened_malloc, which sacrifices some no impact on the security properties of hardened_malloc.
security for much less memory usage.
* 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 == Copy Compiled hardened_malloc Library
`cp out/libhardened_malloc.so <target_path>` `# cp out/libhardened_malloc.so <target_path>`
== Set System to Preload hardened_malloc on Boot == Set System to Preload hardened_malloc on Boot