docs/modes.html

<!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: Build Modes</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.5/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('modes.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">Build Modes </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>We can build mimalloc in various modes.</p>
<h2>Secure Mode</h2>
<p><em>mimalloc</em> can be build in secure mode by using the <span class="tt">-DMI_SECURE=ON</span> flags in <span class="tt">cmake</span>. This build enables various mitigations to make mimalloc more robust against exploits. In particular:</p>
<ul>
<li>All internal mimalloc pages are surrounded by guard pages and the heap metadata is behind a guard page as well (so a buffer overflow exploit cannot reach into the metadata).</li>
<li>All free list pointers are <a href="https://github.com/microsoft/mimalloc/blob/783e3377f79ee82af43a0793910a9f2d01ac7863/include/mimalloc-internal.h#L396">encoded</a> with per-page keys which is used both to prevent overwrites with a known pointer, as well as to detect heap corruption.</li>
<li>Double free's are detected (and ignored).</li>
<li>The free lists are initialized in a random order and allocation randomly chooses between extension and reuse within a page to mitigate against attacks that rely on a predicable allocation order. Similarly, the larger heap blocks allocated by mimalloc from the OS are also address randomized.</li>
</ul>
<p>As always, evaluate with care as part of an overall security strategy as all of the above are mitigations but not guarantees.</p>
<h2>Debug Mode</h2>
<p>When <em>mimalloc</em> is built using debug mode, (<span class="tt">-DCMAKE_BUILD_TYPE=Debug</span>), various checks are done at runtime to catch development errors.</p>
<ul>
<li>Statistics are maintained in detail for each object size. They can be shown using <span class="tt">MIMALLOC_SHOW_STATS=1</span> at runtime.</li>
<li>All objects have padding at the end to detect (byte precise) heap block overflows.</li>
<li>Double free's, and freeing invalid heap pointers are detected.</li>
<li>Corrupted free-lists and some forms of use-after-free are detected.</li>
</ul>
<h2>Guarded Mode</h2>
<p><span id="guarded"><em>mimalloc</em> can be build in guarded mode using the <span class="tt">-DMI_GUARDED=ON</span> flags in <span class="tt">cmake</span>.</span> This enables placing OS guard pages behind certain object allocations to catch buffer overflows as they occur. This can be invaluable to catch buffer-overflow bugs in large programs. However, it also means that any object allocated with a guard page takes at least 8 KiB memory for the guard page and its alignment. As such, allocating a guard page for every allocation may be too expensive both in terms of memory, and in terms of performance with many system calls. Therefore, there are various environment variables (and options) to tune this:</p>
<ul>
<li><span class="tt">MIMALLOC_GUARDED_SAMPLE_RATE=N</span>: Set the sample rate to <span class="tt">N</span> (by default 4000). This mode places a guard page behind every <span class="tt">N</span> suitable object allocations (per thread). Since the performance in guarded mode without placing guard pages is close to release mode, this can be used to enable guard pages even in production to catch latent buffer overflow bugs. Set the sample rate to <span class="tt">1</span> to guard every object, and to <span class="tt">0</span> to place no guard pages at all.</li>
<li><span class="tt">MIMALLOC_GUARDED_SAMPLE_SEED=N</span>: Start sampling at <span class="tt">N</span> (by default random). Can be used to reproduce a buffer overflow if needed.</li>
<li><span class="tt">MIMALLOC_GUARDED_MIN=N</span>, <span class="tt">MIMALLOC_GUARDED_MAX=N</span>: Minimal and maximal <em>rounded</em> object sizes for which a guard page is considered (<span class="tt">0</span> and <span class="tt">1GiB</span> respectively). If you suspect a buffer overflow occurs with an object of size 141, set the minimum and maximum to <span class="tt">148</span> and the sample rate to <span class="tt">1</span> to have all of those guarded.</li>
<li><span class="tt">MIMALLOC_GUARDED_PRECISE=1</span>: If we have an object of size 13, we would usually place it an aligned 16 bytes in front of the guard page. Using <span class="tt">MIMALLOC_GUARDED_PRECISE</span> places it exactly 13 bytes before a page so that even a 1 byte overflow is detected. This violates the C/C++ minimal alignment guarantees though so use with care. </li>
</ul>
</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>