<!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>Getting Started — 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.17', 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="Information Flow: Pipes and Filters" href="filters.html" /> <link rel="prev" title="Building The Library" href="building.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="getting-started"> <h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1> <p>All declarations in the library are contained within the namespace <tt class="docutils literal"><span class="pre">Botan</span></tt>, so you need to either prefix types with <tt class="docutils literal"><span class="pre">Botan::</span></tt> or add a <tt class="docutils literal"><span class="pre">using</span></tt> declaration in your code. All examples will assume a <tt class="docutils literal"><span class="pre">using</span></tt> declaration.</p> <p>All library headers are included like so:</p> <div class="highlight-cpp"><div class="highlight"><pre><span class="cp">#include <botan/botan.h></span> </pre></div> </div> <div class="section" id="initializing-the-library"> <h2>Initializing the Library<a class="headerlink" href="#initializing-the-library" title="Permalink to this headline">¶</a></h2> <p>There is a set of core services that the library needs access to while it is performing requests. To ensure these are set up, you must create an object of type</p> <dl class="class"> <dt id="LibraryInitializer"> <em class="property">class </em><tt class="descname">LibraryInitializer</tt><a class="headerlink" href="#LibraryInitializer" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <p>prior to making any other library calls. Typically this will be named something like <tt class="docutils literal"><span class="pre">init</span></tt> or <tt class="docutils literal"><span class="pre">botan_init</span></tt>. The object lifetime must exceed that of all other Botan objects your application creates; for this reason the best place to create the <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt> is at the start of your <tt class="docutils literal"><span class="pre">main</span></tt> function, since this guarantees that it will be created first and destroyed last (via standard C++ RAII rules). The initializer does things like setting up the memory allocation system and algorithm lookup tables, finding out if there is a high resolution timer available to use, and similar such matters. With no arguments, the library is initialized with various default settings. So (unless you are writing threaded code; see below), all you need is:</p> <div class="highlight-cpp"><div class="highlight"><pre><span class="n">Botan</span><span class="o">::</span><span class="n">LibraryInitializer</span> <span class="n">init</span><span class="p">;</span> </pre></div> </div> <p>at the start of your <tt class="docutils literal"><span class="pre">main</span></tt>.</p> <p>The constructor takes an optional string that specifies arguments. Currently the only possible argument is “thread_safe”, which must have an boolean argument (for instance “thread_safe=false” or “thread_safe=true”). If “thread_safe” is specified as true the library will attempt to register a mutex type to properly guard access to shared resources. However these locks do not protect individual Botan objects: explicit locking must be used if you wish to share a single object between threads.</p> <p>If you do not create a <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt> object, all library operations will fail, because it will be unable to do basic things like allocate memory or get random bits. You should never create more than one <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt>.</p> </div> <div class="section" id="pitfalls"> <h2>Pitfalls<a class="headerlink" href="#pitfalls" title="Permalink to this headline">¶</a></h2> <p>There are a few things to watch out for to prevent problems when using the library.</p> <p>Never allocate any kind of Botan object globally. The problem with doing this is that the constructor for such an object will be called before the library is initialized. Many Botan objects will, in their constructor, make one or more calls into the library global state object. Access to this object is checked, so an exception should be thrown (rather than a memory access violation or undetected uninitialized object access). A rough equivalent that will work is to keep a global pointer to the object, initializing it after creating your <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt>. Merely making the <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt> also global will probably not help, because C++ does not make very strong guarantees about the order that such objects will be created.</p> <p>The same rule applies for making sure the destructors of all your Botan objects are called before the <tt class="docutils literal"><span class="pre">LibraryInitializer</span></tt> is destroyed. This implies you can’t have static variables that are Botan objects inside functions or classes; in many C++ runtimes, these objects will be destroyed after main has returned.</p> <p>The memory object classes (<tt class="docutils literal"><span class="pre">MemoryRegion</span></tt>, <tt class="docutils literal"><span class="pre">MemoryVector</span></tt>, <tt class="docutils literal"><span class="pre">SecureVector</span></tt>) are extremely primitive, and meant only for secure storage of potentially sensitive data like keys. They do not meet the requirements for an STL container object and you should not try to use them with STL algorithms. For a general-purpose container, use <tt class="docutils literal"><span class="pre">std::vector</span></tt>.</p> <p>Use a <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> block inside your <tt class="docutils literal"><span class="pre">main</span></tt> function, and catch any <tt class="docutils literal"><span class="pre">std::exception</span></tt> throws (remember to catch by reference, as <tt class="docutils literal"><span class="pre">std::exception::what</span></tt> is polymorphic):</p> <div class="highlight-cpp"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="n">try</span> <span class="p">{</span> <span class="n">LibraryInitializer</span> <span class="n">init</span><span class="p">;</span> <span class="c1">// ...</span> <span class="p">}</span> <span class="k">catch</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">exception</span><span class="o">&</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span> <span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="n">e</span><span class="p">.</span><span class="n">what</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </pre></div> </div> <p>This is not strictly required, but if you don’t, and Botan throws an exception, the runtime will call <tt class="docutils literal"><span class="pre">std::terminate</span></tt>, which usually calls <tt class="docutils literal"><span class="pre">abort</span></tt> or something like it, leaving you (or worse, a user of your application) wondering what went wrong.</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 current"><a class="current reference internal" href="">Getting Started</a><ul> <li class="toctree-l2"><a class="reference internal" href="#initializing-the-library">Initializing the Library</a></li> <li class="toctree-l2"><a class="reference internal" href="#pitfalls">Pitfalls</a></li> </ul> </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"><a class="reference internal" href="secmem.html">Secure Memory Containers</a></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="building.html" title="Building The Library" accesskey="P">previous</a> | <a href="filters.html" title="Information Flow: Pipes and Filters" accesskey="N">next</a> | <a href="genindex.html" title="General Index" accesskey="I">index</a> <br/> <a href="_sources/firststep.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>