<!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.11.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="jquery.js"></script>
<script type="text/javascript" src="dynsections.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="resize.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>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() { init_search(); });
/* @license-end */
</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"> 1.8/2.1</span>
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.11.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</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" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('modes.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</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 <code>-DMI_SECURE=ON</code> flags in <code>cmake</code>. 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, (<code>-DCMAKE_BUILD_TYPE=Debug</code>), 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 <code>MIMALLOC_SHOW_STATS=1</code> 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 <code>-DMI_GUARDED=ON</code> flags in <code>cmake</code>.</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><code>MIMALLOC_GUARDED_SAMPLE_RATE=N</code>: Set the sample rate to <code>N</code> (by default 4000). This mode places a guard page behind every <code>N</code> 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 <code>1</code> to guard every object, and to <code>0</code> to place no guard pages at all.</li>
<li><code>MIMALLOC_GUARDED_SAMPLE_SEED=N</code>: Start sampling at <code>N</code> (by default random). Can be used to reproduce a buffer overflow if needed.</li>
<li><code>MIMALLOC_GUARDED_MIN=N</code>, <code>MIMALLOC_GUARDED_MAX=N</code>: Minimal and maximal <em>rounded</em> object sizes for which a guard page is considered (<code>0</code> and <code>1GiB</code> respectively). If you suspect a buffer overflow occurs with an object of size 141, set the minimum and maximum to <code>148</code> and the sample rate to <code>1</code> to have all of those guarded.</li>
<li><code>MIMALLOC_GUARDED_PRECISE=1</code>: If we have an object of size 13, we would usually place it an aligned 16 bytes in front of the guard page. Using <code>MIMALLOC_GUARDED_PRECISE</code> 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 -->
<!-- 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.11.0 </li>
</ul>
</div>
</body>
</html>
