Inferencium/website
1
0
Fork 0
Code Issues Activity

Update webpage "Documentation - hardened_malloc" from version "2.0.0" to "3.0.0"

Browse Source
This commit is contained in:
inference 2024-01-30 22:25:56 +00:00
parent f3bfe08442
commit acde0c2f2a
Signed by: inference
SSH Key Fingerprint: SHA256:FtEVfx1CmTKMy40VwZvF4k+3TC+QhCWy+EmPRg50Nnc
1 changed files with 105 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
documentation/hardened_malloc.xhtml
View File

@ -1,7 +1,7 @@
<!DOCTYPE html> <!DOCTYPE html>
<!-- Inferencium - Website - Documentation - GrapheneOS hardened_malloc --> <!-- Inferencium - Website - Documentation - hardened_malloc -->
<!-- Version: 2.0.0 --> <!-- Version: 3.0.0 -->
<!-- Copyright 2023 Jake Winters --> <!-- Copyright 2023 Jake Winters -->
<!-- SPDX-License-Identifier: BSD-3-Clause --> <!-- SPDX-License-Identifier: BSD-3-Clause -->
@ -12,95 +12,118 @@
<meta charset="utf-8"/> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/> <meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" href="../main.css"/> <link rel="stylesheet" href="../main.css"/>
<title>Inferencium - Documentation - GrapheneOS hardened_malloc</title> <title>Inferencium - Documentation - hardened_malloc</title>
</head> </head>
<body> <body>
<nav class="navbar"> <nav class="navbar">
<div><a href="../index.xhtml"><img src="../asset/img/logo-inferencium-no_text.png" width="110px" height="110px"/></a></div> <div><a href="../index.xhtml"><img src="../asset/img/logo-inferencium-no_text.png" width="110" height="110" alt="Inferencium logo"/></a></div>
<div><a href="../index.xhtml" class="title">Inferencium</a></div> <div><a href="../index.xhtml" class="title">Inferencium</a></div>
<div><a href="../about.xhtml">About</a></div> <div><a href="../about.xhtml">About</a></div>
<div><a href="../contact.xhtml">Contact</a></div>
<div><a href="../blog.xhtml">Blog</a></div>
<div><a href="../documentation.xhtml">Documentation</a></div> <div><a href="../documentation.xhtml">Documentation</a></div>
<div><a href="../source.xhtml">Source</a></div> <div><a href="../source.xhtml">Source</a></div>
<div><a href="../key.xhtml">Key</a></div>
<div><a href="../changelog.xhtml">Changelog</a></div> <div><a href="../changelog.xhtml">Changelog</a></div>
<div><a href="../blog.xhtml">Blog</a></div>
<div><a href="../contact.xhtml">Contact</a></div>
<div><a href="../directory.xhtml">Directory</a></div> <div><a href="../directory.xhtml">Directory</a></div>
<div><a href="../key.xhtml">Key</a></div>
</nav> </nav>
<section id="introduction"> <h1 id="hardened_malloc"><a href="#hardened_malloc">Documentation - hardened_malloc</a></h1>
<h1 id="introduction"><a href="#introduction">Documentation - GrapheneOS hardened_malloc</a></h1> <section id="introduction">
<p>This documentation contains instructions to use <p>This documentation contains instructions to use
<a href="https://github.com/GrapheneOS/hardened_malloc">GrapheneOS hardened_malloc</a> <a href="https://github.com/GrapheneOS/hardened_malloc">hardened_malloc</a>
memory allocator as the system's default memory allocator. These instructions apply to memory allocator as the system's default memory allocator. These instructions
both musl and glibc C libraries on Unix-based and Unix-like systems. hardened_malloc can apply to both musl and glibc C libraries on Unix-based and Unix-like
also be used per-application and/or per-user, in which case root permissions are not systems.</p>
required; this documentation focuses on system-wide usage of hardened_malloc, assumes <p>hardened_malloc can also be used per-application and/or per-user, in which
root privileges, and assumes the compiled library will be located in a path readable by case root permissions are not required; this documentation focuses on
all users of the system.</p> system-wide usage of hardened_malloc, assumes root privileges, and assumes the
<p>For the complete hardened_malloc documentation, visit its compiled library will be located in a path readable and executable by all users
<a href="https://github.com/GrapheneOS/hardened_malloc#hardened_malloc">official documentation</a>.</p> of the system.</p>
<p>This documentation is also available in portable AsciiDoc format in my <p>For the complete hardened_malloc documentation, visit its
<a href="https://src.inferencium.net/Inferencium/doc/src/branch/stable/security/hardened_malloc.adoc">documentation source code repository</a></p>. <a href="https://github.com/GrapheneOS/hardened_malloc#hardened_malloc">official documentation</a>.</p>
</section> <p>This documentation is also available in portable AsciiDoc format in my
<nav id="toc"> <a href="https://src.inferencium.net/Inferencium/doc/src/branch/stable/security/hardened_malloc.adoc">documentation source code repository</a>.</p>
<h2 id="toc"><a href="#toc">Table of Contents</a></h2> </section>
<ul> <nav id="toc">
<li><a href="#memory_pages">Increase Permitted Amount of Memory Pages</a></li> <h2><a href="#toc">Table of Contents</a></h2>
<li><a href="#clone_source_code">Clone hardened_malloc Source Code</a></li> <ul>
<li><a href="#enter_local_repository">Enter hardened_malloc Local Git Repository</a></li> <li><a href="#memory_pages">Increase Permitted Amount of Memory Pages</a></li>
<li><a href="#compile">Compile hardened_malloc</a></li> <li><a href="#clone_source_code">Clone hardened_malloc Source Code</a></li>
<li><a href="#copy_library">Copy Compiled hardened_malloc Library</a></li> <li><a href="#enter_local_repository">Enter hardened_malloc Local Git Repository</a></li>
<li><a href="#preload_on_boot">Set System to Preload hardened_malloc on Boot</a></li> <li><a href="#compile">Compile hardened_malloc</a></li>
</ul> <li><a href="#copy_library">Copy Compiled hardened_malloc Library</a></li>
</nav> <li><a href="#preload_on_boot">Set System to Preload hardened_malloc on Boot</a></li>
<section id="memory_pages"> </ul>
<h2 id="memory_pages"><a href="#memory_pages">Increase Permitted Amount of Memory Pages</a></h2> </nav>
<p>Add <code>vm.max_map_count = 1048576</code> to <section id="memory_pages">
<code>/etc/sysctl.conf</code> to accommodate hardened_malloc's large amount of guard <h2><a href="#memory_pages">Increase Permitted Amount of Memory Pages</a></h2>
pages.</p> <p>Add <code>vm.max_map_count = 1048576</code> to
</section> <code>/etc/sysctl.conf</code> to accommodate hardened_malloc's large amount of
<section id="clone_source_code"> guard pages.</p>
<h2 id="clone_source_code"><a href="#clone_source_code">Clone hardened_malloc Source Code</a></h2> </section>
<p><code>$ git clone https://github.com/GrapheneOS/hardened_malloc.git</code></p> <section id="clone_source_code">
</section> <h2><a href="#clone_source_code">Clone hardened_malloc Source Code</a></h2>
<section id="enter_local_repository"> <p><code>$ git clone https://github.com/GrapheneOS/hardened_malloc.git</code></p>
<h2 id="enter_local_repository"><a href="#enter_local_repository">Enter hardened_malloc Local Git Repository</a></h2> </section>
<p><code>$ cd hardened_malloc/</code></p> <section id="enter_local_repository">
</section> <h2><a href="#enter_local_repository">Enter hardened_malloc Local Git Repository</a></h2>
<section id="compile"> <p><code>$ cd hardened_malloc/</code></p>
<h2 id="compile"><a href="#compile">Compile hardened_malloc</a></h2> </section>
<p><code>$ make <var>&lt;arguments&gt;</var></code></p> <section id="compile">
<p><code>CONFIG_N_ARENA=<var>n</var></code> can be adjusted to increase parallel <h2><a href="#compile">Compile hardened_malloc</a></h2>
performance at the expense of memory usage, or decrease memory usage at the expense of <p><code>$ make <var>&lt;arguments&gt;</var></code></p>
parallel performance, where <var>n</var> is an integer. Higher values prefer parallel <p><code>CONFIG_N_ARENA=<var>n</var></code> can be adjusted to increase parallel
performance, lower values prefer lower memory usage. The number of arenas has no impact performance at the expense of memory usage, or decrease memory usage at the
on the security properties of hardened_malloc.<br/> expense of parallel performance, where <code><var>n</var></code> is a
<b>Minimum number of arenas:</b> 1<br/> non-negative integer. Higher values prefer parallel performance, whereas lower
<b>Maximum number of arenas:</b> 256</p> values prefer lower memory usage. Note that having too many arenas may cause
<p>For extra security, <code>CONFIG_SEAL_METADATA=true</code> can be used in order to memory fragmentation and decrease system performance. The number of arenas has
control whether Memory Protection Keys are used to disable access to all writable no impact on the security properties of hardened_malloc.</p>
allocator state outside of the memory allocator code. It's currently disabled by default <table align="center">
due to a significant performance cost for this use case on current generation hardware. <thead>
Whether or not this feature is enabled, the metadata is all contained within an isolated <tr>
memory region with high entropy random guard regions around it.</p> <th id="arena-min">Minimum</th>
<p>For low-memory systems, <code>VARIANT=light</code> can be used to compile the light <th id="arena-max">Maximum</th>
variant of hardened_malloc, which sacrifices some security for much less memory <th id="arena-def">Default</th>
usage.</p> </tr>
<p>For all compile-time options, see the </thead>
<a href="https://github.com/GrapheneOS/hardened_malloc#configuration">configuration section</a> <tbody>
of hardened_malloc's extensive official documentation.</p> <tr>
</section> <td headers="arena-min">1</td>
<section id="copy_library"> <td headers="arena-max">256</td>
<h2 id="copy_library"><a href="#copy_library">Copy Compiled hardened_malloc Library</a></h2> <td headers="arena-def">4</td>
<p><code># cp out/libhardened_malloc.so <var>&lt;target path&gt;</var></code></p> </tr>
</section> </tbody>
<section id="preload_on_boot"> </table>
<h2 id="preload_on_boot"><a href="#preload_on_boot">Set System to Preload hardened_malloc on Boot</a></h2> <p>For extra security, <code>CONFIG_SEAL_METADATA=true</code> can be used in
<p><b>musl-based systems:</b> Add order to control whether
<code>export LD_PRELOAD="<var>&lt;hardened_malloc path&gt;</var>"</code> to <a href="https://www.kernel.org/doc/html/v6.7/core-api/protection-keys.html">Memory Protection Keys</a>
<code>/etc/environment</code></p> are used to disable access to all writable allocator state outside of the memory
<p><b>glibc-based systems:</b> Add <code><var>&lt;hardened_malloc path&gt;</var></code> to allocator code. It's currently disabled by default due to a significant
<code>/etc/ld.so.preload</code></p> performance cost for this use case on current-generation hardware. Whether or
</section> not this feature is enabled, the metadata is all contained within an isolated
memory region with high-entropy random guard regions around it.</p>
<p>For low-memory systems, <code>VARIANT=light</code> 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.</p>
<p>For all compile-time options, see the
<a href="https://github.com/GrapheneOS/hardened_malloc#configuration">configuration section</a>
of hardened_malloc's extensive official documentation.</p>
</section>
<section id="copy_library">
<h2><a href="#copy_library">Copy Compiled hardened_malloc Library</a></h2>
<p><code># cp out/libhardened_malloc.so <var>&lt;target path&gt;</var></code></p>
</section>
<section id="preload_on_boot">
<h2><a href="#preload_on_boot">Set System to Preload hardened_malloc on Boot</a></h2>
<p><b>musl-based systems:</b> Add
<code>LD_PRELOAD=<var>&lt;hardened_malloc path&gt;</var></code> to
<code>/etc/environment</code></p>
<p><b>glibc-based systems:</b> Add
<code><var>&lt;hardened_malloc path&gt;</var></code> to
<code>/etc/ld.so.preload</code></p>
</section>
</body> </body>
</html> </html>