<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Secure Memory Containers — Botan</title> <link rel="stylesheet" href="_static/agogo.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: './', VERSION: '1.10.14', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="Botan" href="index.html" /> <link rel="next" title="Key Derivation Functions" href="kdf.html" /> <link rel="prev" title="The Low-Level Interface" href="lowlevel.html" /> </head> <body> <div class="header-wrapper"> <div class="header"> <h1>Botan</h1> </div> </div> <div class="content-wrapper"> <div class="content"> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="secure-memory-containers"> <h1>Secure Memory Containers<a class="headerlink" href="#secure-memory-containers" title="Permalink to this headline">¶</a></h1> <p>A major concern with mixing modern multiuser OSes and cryptographic code is that at any time the code (including secret keys) could be swapped to disk, where it can later be read by an attacker. Botan stores almost everything (and especially anything sensitive) in memory buffers that a) clear out their contents when their destructors are called, and b) have easy plugins for various memory locking functions, such as the <tt class="docutils literal"><span class="pre">mlock</span></tt> call on many Unix systems.</p> <p>Two of the allocation method used (“malloc” and “mmap”) don’t require any extra privileges on Unix, but locking memory does. At startup, each allocator type will attempt to allocate a few blocks (typically totaling 128k), so if you want, you can run your application <tt class="docutils literal"><span class="pre">setuid</span></tt> <tt class="docutils literal"><span class="pre">root</span></tt>, and then drop privileges immediately after creating your <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt>. If you end up using more than what’s been allocated, some of your sensitive data might end up being swappable, but that beats running as <tt class="docutils literal"><span class="pre">root</span></tt> all the time.</p> <p>These classes should also be used within your own code for storing sensitive data. They are only meant for primitive data types (int, long, etc): if you want a container of higher level Botan objects, you can just use a <tt class="docutils literal"><span class="pre">std::vector</span></tt>, since these objects know how to clear themselves when they are destroyed. You cannot, however, have a <tt class="docutils literal"><span class="pre">std::vector</span></tt> (or any other container) of <tt class="docutils literal"><span class="pre">Pipe</span></tt> objects or filters, because these types have pointers to other filters, and implementing copy constructors for these types would be both hard and quite expensive (vectors of pointers to such objects is fine, though).</p> <p>These types are not described in any great detail: for more information, consult the definitive sources~–~the header files <tt class="docutils literal"><span class="pre">secmem.h</span></tt> and <tt class="docutils literal"><span class="pre">allocate.h</span></tt>.</p> <p><tt class="docutils literal"><span class="pre">SecureBuffer</span></tt> is a simple array type, whose size is specified at compile time. It will automatically convert to a pointer of the appropriate type, and has a number of useful functions, including <tt class="docutils literal"><span class="pre">clear()</span></tt>, and <tt class="docutils literal"><span class="pre">size_t</span></tt> <tt class="docutils literal"><span class="pre">size()</span></tt>, which returns the length of the array. It is a template that takes as parameters a type, and a constant integer which is how long the array is (for example: <tt class="docutils literal"><span class="pre">SecureBuffer<byte,</span> <span class="pre">8></span> <span class="pre">key;</span></tt>).</p> <p><tt class="docutils literal"><span class="pre">SecureVector</span></tt> is a variable length array. Its size can be increased or decreased as need be, and it has a wide variety of functions useful for copying data into its buffer. Like <tt class="docutils literal"><span class="pre">SecureBuffer</span></tt>, it implements <tt class="docutils literal"><span class="pre">clear</span></tt> and <tt class="docutils literal"><span class="pre">size</span></tt>.</p> <div class="section" id="allocators"> <h2>Allocators<a class="headerlink" href="#allocators" title="Permalink to this headline">¶</a></h2> <p>The containers described above get their memory from allocators. As a user of the library, you can add new allocator methods at run time for containers, including the ones used internally by the library, to use. The interface to this is in <tt class="docutils literal"><span class="pre">allocate.h</span></tt>. Code needing to allocate or deallocate memory calls <tt class="docutils literal"><span class="pre">get_allocator</span></tt>, which returns a pointer to an allocator object. This pointer should not be freed: the caller does not own the allocator (it is shared among multiple allocatore users, and uses a mutex to serialize access internally if necessary). It is possible to call <tt class="docutils literal"><span class="pre">get_allocator</span></tt> with a specific name to request a particular type of allocator, otherwise, a default allocator type is returned.</p> <p>At start time, the only allocator known is a <tt class="docutils literal"><span class="pre">Default_Allocator</span></tt>, which just allocates memory using <tt class="docutils literal"><span class="pre">malloc</span></tt>, and zeroizes it when the memory is released. It is known by the name “malloc”. If you ask for another type of allocator (“locking” and “mmap” are currently used), and it is not available, some other allocator will be returned.</p> <p>You can add in a new allocator type using <tt class="docutils literal"><span class="pre">add_allocator_type</span></tt>. This function takes a string and a pointer to an allocator. The string gives this allocator type a name to which it can be referred when one is requesting it with <tt class="docutils literal"><span class="pre">get_allocator</span></tt>. If an error occurs (such as the name being already registered), this function returns false. It will return true if the allocator was successfully registered. If you ask it to, <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt> will do this for you.</p> <p>Finally, you can set the default allocator type that will be returned using the policy setting “default_alloc” to the name of any previously registered allocator.</p> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h3>Table Of Contents</h3> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="index.html">Welcome</a></li> <li class="toctree-l1"><a class="reference internal" href="reading.html">Recommended Reading</a></li> <li class="toctree-l1"><a class="reference internal" href="building.html">Building The Library</a></li> <li class="toctree-l1"><a class="reference internal" href="firststep.html">Getting Started</a></li> <li class="toctree-l1"><a class="reference internal" href="filters.html">Information Flow: Pipes and Filters</a></li> <li class="toctree-l1"><a class="reference internal" href="pubkey.html">Public Key Cryptography</a></li> <li class="toctree-l1"><a class="reference internal" href="x509.html">Certificate Handling</a></li> <li class="toctree-l1"><a class="reference internal" href="ssl.html">SSL and TLS</a></li> <li class="toctree-l1"><a class="reference internal" href="bigint.html">BigInt</a></li> <li class="toctree-l1"><a class="reference internal" href="lowlevel.html">The Low-Level Interface</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="">Secure Memory Containers</a><ul> <li class="toctree-l2"><a class="reference internal" href="#allocators">Allocators</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="kdf.html">Key Derivation Functions</a></li> <li class="toctree-l1"><a class="reference internal" href="pbkdf.html">PBKDF Algorithms</a></li> <li class="toctree-l1"><a class="reference internal" href="passhash.html">Password Hashing</a></li> <li class="toctree-l1"><a class="reference internal" href="rng.html">Random Number Generators</a></li> <li class="toctree-l1"><a class="reference internal" href="fpe.html">Format Preserving Encryption</a></li> <li class="toctree-l1"><a class="reference internal" href="python.html">Python Binding</a></li> </ul> <h3 style="margin-top: 1.5em;">Search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer"> <div class="left"> <a href="lowlevel.html" title="The Low-Level Interface" accesskey="P">previous</a> | <a href="kdf.html" title="Key Derivation Functions" accesskey="N">next</a> | <a href="genindex.html" title="General Index" accesskey="I">index</a> <br/> <a href="_sources/secmem.txt" rel="nofollow">Show Source</a> </div> <div class="right"> <div class="footer"> © Copyright 2000-2011, Jack Lloyd. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3. </div> </div> <div class="clearer"></div> </div> </div> </body> </html>