From 67b88c3af1eb5b1a317036e414f32cc3bd219a23 Mon Sep 17 00:00:00 2001 From: inference Date: Mon, 29 Jan 2024 20:23:29 +0000 Subject: [PATCH] Fix 1st-level heading and section indentation --- documentation/hardened_malloc.xhtml | 162 ++++++++++++++-------------- 1 file changed, 83 insertions(+), 79 deletions(-) diff --git a/documentation/hardened_malloc.xhtml b/documentation/hardened_malloc.xhtml index 9955899..baa96c4 100644 --- a/documentation/hardened_malloc.xhtml +++ b/documentation/hardened_malloc.xhtml @@ -1,7 +1,7 @@ - + @@ -27,83 +27,87 @@
Directory
Key
-
-

Documentation - hardened_malloc

-

This documentation contains instructions to use - 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 and executable by all users of the system.

-

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.

-
- -
-

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, 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 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. 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 extensive official documentation.

-
-
-

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

-
+

Documentation - hardened_malloc

+
+

This documentation contains instructions to use + 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 and executable by all users + of the system.

+

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.

+
+ +
+

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, 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 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. 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 extensive official documentation.

+
+
+

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

+