vey-mimalloc-sys 0.3.2+3.7.0

Rust FFI binding to mimalloc
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.18.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>mi-malloc: Security</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="codefolding.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="mimalloc-doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectlogo"><img alt="Logo" src="mimalloc-logo.svg"/></td>
  <td id="projectalign">
   <div id="projectname">mi-malloc<span id="projectnumber">&#160;3.6/2.5/1.15</span>
   </div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect" class="search-icon"><span class="search-icon-dropdown"></span></span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><div id="MSearchCloseImg" class="close-icon"></div></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.18.0 -->
<script type="text/javascript">
let searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', codefold.init);
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded',() => { initNavTree('security.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Security </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There are various build options to make mimalloc more secure.</p>
<p><a class="anchor" id="security_environment"></a> </p><h2>Environment Options</h2>
<p>With <span class="tt">-DMI_SECURE_ENV=ON</span>, only <span class="tt">MIMALLOC_SHOW_STATS</span>, <span class="tt">MIMALLOC_VERBOSE</span>, and <span class="tt">MIMALLOC_ALLOW_THP</span> are accepted from the environment &ndash; all other options are ignored.</p>
<p>This is by default enabled for <a class="el" href="#secure_mode" title="secure_mode">secure mode</a>, <a class="el" href="#memory_tagging" title="memory_tagging">MTE</a>, and <a class="el" href="#pointer_authentication" title="pointer_authentication">PAC</a>. This can be overridden by explicitly building with <span class="tt">-DMI_SECURE_ENV=OFF</span>. Note: even with <span class="tt">OFF</span>, an elevated process ignores all environment options. Moreover, on platforms with guard pages, a program built with secure mode always ignores settings for large or huge OS pages (as pinned memory cannot be guarded). You can still set options programmatically for trusted programs.</p>
<p><a class="anchor" id="secure_mode"></a> </p><h2>Secure Mode</h2>
<p><em>mimalloc</em> can be built in secure mode using <span class="tt">-DMI_SECURE=OFF|MINIMAL|CHECKED|ON|FULL</span> with CMake. These modes enable software mitigations to make mimalloc more robust against exploits.</p>
<p>With <span class="tt">MINIMAL</span>, only mitigations with a small performance impact are added (usually 1-3%):</p>
<ul>
<li>Internal metadata, including the page map and static data, is surrounded by guard pages so that a buffer overflow or underflow cannot reach allocator metadata. Static pointers into metadata are kept in a sealed read-only area. Free list entries are not encoded at this level and can still be corrupted through a heap block buffer overflow.</li>
<li>OS allocation addresses are randomized where possible, and detected metadata corruption aborts the process.</li>
<li>Large blocks (over 512 KiB) are followed by a guard page.</li>
<li>Pinned memory, including large and huge OS pages, is neither allocated nor accepted as arena memory on platforms with guard pages.</li>
<li><span class="tt">MI_SECURE_ENV</span> is enabled by default.</li>
</ul>
<p>With <span class="tt">CHECKED</span> (the default with <span class="tt">-DMI_MTE</span> or <span class="tt">-DMI_PAC</span>), the performance and memory impact is still relatively small (usually less than 10%, but can be 2x slower):</p>
<ul>
<li>Free list pointers are encoded with per-page keys to prevent overwrites with a known pointer and detect corruption. With <a class="el" href="#pointer_authentication" title="pointer_authentication">PAC</a>, hardware keys can be used.</li>
<li>Pointers passed to <a class="el" href="group__malloc.html#gaf2c7b89c327d1f60f59e68b9ea644d95" title="Free previously allocated memory.">mi_free()</a> and related functions are validated. Pointers that do not originate from mimalloc are ignored, and interior pointers are adjusted to the start of their block.</li>
<li>Free lists are initialized in random order, and allocation randomly chooses between extension and reuse within a page to make allocation order less predictable.</li>
<li>Reuse of freed blocks is delayed until one eighth of a page is free, and a random number of recently freed blocks is held back to make reclaiming a just-freed block harder.</li>
</ul>
<p>With <span class="tt">ON</span>, performance and memory usage are impacted further (usually less than 25%, but can be 2 to 3x slower):</p>
<ul>
<li>Eight bytes of padding are added to each heap block to detect overflows when the block is freed, and to detect double frees.</li>
<li>Some use-after-free accesses that modify the first word of a block are detected.</li>
<li>The first 1 KiB of a block is zeroed on free.</li>
<li>Free lists are randomized further.</li>
<li>The library is built as <span class="tt">mimalloc-secure</span>.</li>
</ul>
<p>The <span class="tt">FULL</span> mode additionally places a guard page at the end of each mimalloc page (normally 64 KiB) and checks for byte-precise heap block overflows when freeing. This mode is generally not recommended because it costs more time and memory, and large heaps can reach the maximum VMA limit on Linux.</p>
<p>As always, evaluate with care as part of an overall security strategy as all of the above are mitigations but not guarantees.</p>
<p><a class="anchor" id="memory_tagging"></a> </p><h2>Memory Tagging (MTE)</h2>
<p>(<b>v3</b> only, experimental)</p>
<p>On recent arm64 hardware with the memory tagging extension (<a href="https://support.arm.com/documentation/108035/0100/How-does-MTE-work-">MTE</a>), build with <span class="tt">-DMI_MTE=ON</span> to give heap blocks randomized memory tags. Memory can only be accessed through a pointer with the matching tag. Adjacent blocks almost always receive different tags, and freed blocks are retagged, causing most double-free and use-after-free accesses to fault. Tags are chosen from 15 values, excluding the tags of neighboring blocks. Blocks up to 512 KiB are tagged; larger blocks use a trailing guard page because tagging takes time proportional to the block size.</p>
<p>Performance depends on the hardware and workload. On an M5, an MTE build is usually within about 20% of a release build, but can be 2 to 3x slower. <span class="tt">-DMI_MTE=ON</span> also enables <a class="el" href="#pointer_authentication" title="pointer_authentication">PAC</a> (<span class="tt">-DMI_PAC=ON</span>), <span class="tt">-DMI_SECURE=CHECKED</span>, and <span class="tt">-DMI_SECURE_ENV=ON</span> by default.</p>
<p><em>These combined options provide strong mitigation against common heap exploitation techniques.</em> As it is hardware assisted, this is stronger than <span class="tt">-DMI_SECURE=ON</span>.</p>
<p><span class="tt">-DMI_MTE=ON</span> requires CPU and OS support at runtime and aborts at initialization otherwise. On Linux, this also requires enabling tag checking for all threads. <span class="tt">-DMI_MTE=PREFER</span> uses tagging when available and otherwise runs untagged, with performance close to a regular release build. <span class="tt">-DMI_MTE=ON</span> builds have an <span class="tt">-mte-pac</span> library suffix, for example <span class="tt">mimalloc-mte-pac.o</span>, or <span class="tt">-mte</span> with <span class="tt">-DMI_PAC=OFF</span>.</p>
<ul>
<li><b>macOS:</b> requires an Apple M5 or later with macOS 26+. Executables need the hardened-process entitlements; mimalloc tests are signed automatically: <div class="fragment"><div class="line">&gt; cmake -DMI_MTE=ON ../.. &amp;&amp; make -j</div>
<div class="line">&gt; codesign -s - -f --entitlements ../../cmake/mte-entitlements.plist myprogram</div>
</div><!-- fragment --></li>
<li><b>Linux:</b> requires an arm64 kernel with MTE support; check with <span class="tt">grep mte /proc/cpuinfo</span>. Where environment policy permits it, <span class="tt">MIMALLOC_MTE=sync</span>, <span class="tt">async</span>, or <span class="tt">preferred</span> selects the checking mode (<span class="tt">sync</span> by default). Without MTE hardware, QEMU can be used for testing: <span class="tt">QEMU_CPU=max qemu-aarch64 ./myprogram</span>. Tag checking is enabled per thread and inherited by newly created threads, so mimalloc should initialize before other threads are created, as happens when dynamically linked or preloaded. Otherwise initialization reports a fatal error, or a warning with <span class="tt">PREFER</span>, because existing threads may remain untagged until they allocate and system calls with tagged pointers may fail in threads that never call mimalloc.</li>
<li><b>Android:</b> requires an MTE-capable device, such as a Pixel 8 or later, with Memory Tagging Extension enabled in Developer options. Build with the Android NDK: <div class="fragment"><div class="line">&gt; cmake -DMI_MTE=ON -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \</div>
<div class="line">        -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-30 ../..</div>
</div><!-- fragment --></li>
<li><b>iOS</b> (experimental, untested): requires an A19 or later with iOS 26+ and the Enhanced Security capability enabling hardware memory tagging. Build with the iOS SDK: <div class="fragment"><div class="line">&gt; cmake -DMI_MTE=ON -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=26.0 \</div>
<div class="line">        -DMI_BUILD_SHARED=OFF -DMI_BUILD_OBJECT=OFF -DMI_BUILD_TESTS=OFF ../..</div>
</div><!-- fragment --> Link <span class="tt">libmimalloc-mte-pac.a</span> into the app and use the hardened-process entitlements.</li>
</ul>
<p><a class="anchor" id="pointer_authentication"></a> </p><h2>Pointer Authentication (PAC)</h2>
<p>(<b>v3</b> only, experimental)</p>
<p>On arm64 hardware with pointer authentication (<a href="https://developer.arm.com/documentation/102433/0200/Return-oriented-programming">PAC</a>), build with <span class="tt">-DMI_PAC=ON</span>. Mimalloc uses secret hardware keys to sign pointers and validates them on access to detect tampering. On an M5, the overhead is usually about 10%, but can be 1 to 2x slower.</p>
<p>This is most effective together with MTE, and it is enabled by default with <span class="tt">-DMI_MTE=ON</span>. Without MTE, it is best combined with <span class="tt">-DMI_SECURE=ON</span> to get the most benefit. Mimalloc signs:</p>
<ul>
<li>Free list links, so heap block overflows or use-after-free writes cannot forge links even when the per-page keys are known.</li>
<li>Page map entries, thread-local theap pointers, and other root pointers that may reside adjacent to user memory.</li>
</ul>
<p>Authentication failures abort the process. Like MTE, PAC enables <span class="tt">-DMI_SECURE=CHECKED</span> and <span class="tt">-DMI_SECURE_ENV=ON</span> by default. <span class="tt">-DMI_PAC=ON</span> requires CPU and OS support at runtime and aborts at initialization otherwise. On other platforms, or with MSVC, <span class="tt">-DMI_PAC=WEAK</span> signs pointers using a random software process key. An attacker who can read memory may recover that key, but it still prevents forging pointers through blind overwrites.</p>
<p>PAC is part of Armv8.3-A and later. Supported examples include:</p>
<ul>
<li>Apple A12 and M1 or later processors, on macOS and iOS.</li>
<li>Linux 5.0+ and Android on Arm Cortex-A710/X2 and later Armv9 cores, Arm Neoverse V1/V2/N2, AmpereOne, and Qualcomm Oryon. Check with <span class="tt">grep pacg /proc/cpuinfo</span>.</li>
</ul>
<p>Older cores such as Cortex-A76/A78/X1, AWS Graviton2, Ampere Altra, and Raspberry Pi 4 and 5 do not support it.</p>
<p><a class="anchor" id="pointer_capabilities"></a> </p><h2>Pointer Capabilities (CHERI)</h2>
<p>(<b>v3</b> only, experimental)</p>
<p><a href="https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/">CHERI</a> extends an architecture with capabilities: 128-bit pointers carrying bounds, permissions, and an unforgeable validity tag. Integers cannot be turned into valid pointers. Mimalloc supports the pure-capability ABI, bounding allocated blocks and keeping internal metadata unreachable through user capabilities. The default secure level is 3: <span class="tt">CHECKED</span> plus zeroing the first 1 KiB on free and double-free detection. Unlike MTE, CHERI does not prevent use-after-free by itself; that requires capability revocation.</p>
<p>CHERI is available on the Arm <a href="https://www.arm.com/architecture/cpu/morello">Morello</a> research platform and some CHERI RISC-V cores, such as the Codasip X730, running <a href="https://www.cheribsd.org">CheriBSD</a>. For a native pure-capability CheriBSD build, use <span class="tt">cmake ../.. &amp;&amp; make -j</span>. Cross-compilation with CHERI LLVM requires the pure-capability flags, for example:</p>
<ul>
<li>Morello: <span class="tt">-DCMAKE_C_FLAGS="-march=morello -mabi=purecap"</span>.</li>
<li>CHERI-RISC-V: <span class="tt">-DCMAKE_C_FLAGS="-march=rv64imafdcxcheri -mabi=l64pc128d"</span>.</li>
</ul>
<p>We thank ARM and <a href="https://homepages.inf.ed.ac.uk/stark/">Ian Stark</a> for providing a Morello system to test CHERI with mimalloc. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.18.0 </li>
  </ul>
</div>
</body>
</html>